Vaults

Vaults are containers that organize your files. Every file belongs to exactly one vault. This guide walks through every vault operation — creating, listing, updating, deleting, setting defaults, managing members, and organizing with folders.

Visibility

Vaults have a visibility that determines encryption and access control:

	Public	Shared
Encryption	None — plaintext	SEAL protocol (on-chain IBE)
Who can access	Anyone with the URL	Owner + granted Sui addresses
Authentication	Files downloadable without auth	Requires API key + Sui key
Use case	Public assets, open data, static hosting	Team collaboration, multi-agent workflows, sensitive data

Creating vaults

# Shared vault (default) — SEAL-encrypted, requires Sui key
opentusk vault create "Team Project"

# Public vault — unencrypted, no Sui key required
opentusk vault create "Public Assets" --public

# With a description
opentusk vault create "Research Data" --description "Q2 experiment results"

// Shared vault — requires a linked Sui address on the account
const shared = await opentusk.vaults.create({
  name: 'Team Project',
  visibility: 'shared',
});

// Public vault
const pub = await opentusk.vaults.create({
  name: 'Public Assets',
  visibility: 'public',
  description: 'Static files for the website',
});

curl -X POST https://api.opentusk.ai/api/vaults \
  -H "Authorization: Bearer otk_your_key" \
  -H "Content-Type: application/json" \
  -d '{"name": "Team Project", "visibility": "shared"}'

When you create a shared vault, OpenTusk deploys an on-chain SEAL Whitelist on the Sui blockchain. Your Sui address is automatically added as the vault owner.

Listing vaults

# List all vaults you own
opentusk vault list

# JSON output for scripting
opentusk vault list --format json

const vaults = await opentusk.vaults.list();

for (const v of vaults) {
  console.log(`${v.name} (${v.visibility}) — ${v.fileCount} files`);
}

Getting vault details

# By vault ID, slug, or name
opentusk vault info "Team Project"
opentusk vault info team-project
opentusk vault info <vault-id>

const vault = await opentusk.vaults.get('<vault-id>');
console.log(vault.name, vault.visibility, vault.fileCount);

Updating vaults

You can change a vault’s name and description. Visibility cannot be changed.

# Rename
opentusk vault rename "Team Project" "Engineering"

# Update name and/or description
opentusk vault update "Team Project" --name "Engineering" --description "Core team files"

const updated = await opentusk.vaults.update('<vault-id>', {
  name: 'Engineering',
  description: 'Core team files',
});

Deleting vaults

Deleted vaults go to trash with a 7-day grace period before permanent deletion.

# Delete an empty vault (prompts for confirmation)
opentusk vault delete "Old Project"

# Force delete — moves all files to trash first
opentusk vault delete "Old Project" --force

# Skip confirmation prompt
opentusk vault delete "Old Project" --force --yes

// Delete an empty vault
await opentusk.vaults.delete('<vault-id>');

// Force — moves files to trash, then deletes vault
await opentusk.vaults.delete('<vault-id>', { force: true });

Default vault

When you upload a file without specifying a vault, OpenTusk uses your default vault. The setup wizard sets this automatically, or you can set it manually:

# Set by name, slug, or ID
opentusk vault set-default "Team Project"

# Now uploads go here by default
opentusk upload report.pdf
# equivalent to: opentusk upload report.pdf --vault "Team Project"

You can always override the default with --vault:

opentusk upload photo.jpg --vault "Public Assets"

Shared vault members

Shared vaults use Sui address-based access control. Only the vault owner can add or remove members. Members can be humans (with their wallet address) or AI agents (with their generated Sui address).

Adding members

# Add a member by Sui address
opentusk vault members add "Team Project" 0x5678...efgh

# Add an agent (find its address in Settings → API Keys, or from invite output)
opentusk vault members add "Team Project" 0xabcd...1234

The CLI signs the on-chain transaction with your Sui key to add the address to the SEAL Whitelist.

const { member } = await opentusk.sharedVaults.addMember('<vault-id>', {
  suiAddress: '0x5678...efgh',
  txDigest: '<on-chain-tx-digest>',  // proof of on-chain addition
});

Listing members

opentusk vault members list "Team Project"

Output shows each member’s Sui address, role (owner/member), granted date, and member ID.

const { members } = await opentusk.sharedVaults.listMembers('<vault-id>');

for (const m of members) {
  console.log(`${m.suiAddress} — ${m.role} (since ${m.grantedAt})`);
}

Removing members

# Remove by member ID (shown in members list)
opentusk vault members remove "Team Project" <member-id>

# Skip confirmation
opentusk vault members remove "Team Project" <member-id> --yes

await opentusk.sharedVaults.removeMember('<vault-id>', '<member-id>', {
  txDigest: '<on-chain-tx-digest>',  // proof of on-chain removal
});

When a member is removed, their Sui address is removed from the on-chain Whitelist — they can no longer decrypt files in the vault.

Permission model

Action	Owner	Member
Upload files	Yes	Yes
Download / view files	Yes	Yes (all files, not just their own)
Create / list / manage folders	Yes	Yes
List vault members	Yes	Yes
Add / remove members	Yes	No
Update / delete vault	Yes	No

Shared vaults you’re a member of

To list vaults that other users have granted you access to (not vaults you own):

opentusk vault shared

const { vaults } = await opentusk.sharedVaults.list();

for (const entry of vaults) {
  console.log(`${entry.vault.name} — ${entry.role} (since ${entry.grantedAt})`);
}

Linking your Sui address

Before creating or joining shared vaults, you need a Sui address linked to your account. The opentusk setup wizard handles this automatically, or do it manually:

# Link an address
opentusk account link-sui 0x1234...abcd

# Unlink
opentusk account unlink-sui

# Check current address
opentusk account show-sui

// Link
await opentusk.sharedVaults.linkSuiAddress('0x1234...abcd');

// Unlink
await opentusk.sharedVaults.unlinkSuiAddress();

Folders

Vaults support nested folder hierarchies to organize files.

Creating folders

# Create a top-level folder
opentusk folder create "Documents" --vault "Team Project"

# Create a nested folder
opentusk folder create "Invoices" --vault "Team Project" --parent <parent-folder-id>

// Top-level folder
const docs = await opentusk.folders.create({
  vaultId: '<vault-id>',
  name: 'Documents',
});

// Nested folder
const invoices = await opentusk.folders.create({
  vaultId: '<vault-id>',
  parentId: docs.id,
  name: 'Invoices',
});

Listing and browsing folders

# List top-level folders in a vault
opentusk folder list --vault "Team Project"

# List children of a specific folder
opentusk folder list --vault "Team Project" --parent <folder-id>

# View folder contents (files + subfolders)
opentusk folder contents <folder-id>

# View folder details
opentusk folder info <folder-id>

// List top-level folders
const folders = await opentusk.folders.list({ vaultId: '<vault-id>' });

// List children of a folder
const children = await opentusk.folders.list({
  vaultId: '<vault-id>',
  parentId: '<folder-id>',
});

// Get folder contents (files + subfolders in one call)
const contents = await opentusk.folders.getContents('<folder-id>');
console.log(contents.folders); // subfolder list
console.log(contents.files);   // file list

Renaming and deleting folders

# Rename
opentusk folder rename <folder-id> "New Name"

# Delete (folder must be empty)
opentusk folder delete <folder-id>
opentusk folder delete <folder-id> --yes  # skip confirmation

// Rename
await opentusk.folders.update('<folder-id>', { name: 'New Name' });

// Delete (must be empty)
await opentusk.folders.delete('<folder-id>');

Uploading to folders

opentusk upload invoice.pdf --vault "Team Project" --folder <folder-id>

const file = await opentusk.files.upload({
  name: 'invoice.pdf',
  mimeType: 'application/pdf',
  vaultId: '<vault-id>',
  folderId: '<folder-id>',
  data: await readFile('./invoice.pdf'),
});

Vault lifecycle summary

Create vault → Upload files → Organize with folders
                                    │
                           Shared vaults:
                           ├── Add members by Sui address
                           ├── Members upload/download with SEAL encryption
                           └── Remove members to revoke access
                                    │
                           Delete vault → Trash (7-day grace) → Permanent delete

Encryption How SEAL encryption works for shared vaults.

Upload & file lifecycle How files move through hot, synced, and cold.

Invite codes Onboard AI agents with a single command.

CLI reference Full vault, folder, and member command reference.