Permissions Reference

Permissions are declared in your manifest’s permissions array. They control which host APIs your instrument can access. An instrument without the required permission will get an error when calling the restricted API.

{
  "tango": {
    "instrument": {
      "permissions": ["storage.properties", "storage.files", "sessions"]
    }
  }
}

Storage permissions

`storage.properties`

Enables: api.storage.getProperty(), api.storage.setProperty(), api.storage.deleteProperty()

Key-value storage for simple JSON values. Most instruments need this for persisting UI state (selected items, user preferences, cross-panel sync).

Use when: You need to store small config values or state that survives page reloads.

`storage.files`

Enables: api.storage.readFile(), api.storage.writeFile(), api.storage.deleteFile(), api.storage.listFiles()

File-based storage in a sandboxed directory. Supports text (utf8) and binary (base64) encoding.

Use when: You need to store documents, exports, imported data, or binary content.

`storage.db`

Enables: api.storage.sqlQuery(), api.storage.sqlExecute()

Full SQLite database access. Each instrument gets its own database (or multiple named databases).

Use when: You have structured data, need queries/filtering, or have large datasets.

Session permissions

`sessions`

Enables: api.sessions.start(), api.sessions.sendFollowUp(), api.sessions.kill(), api.sessions.list(), api.sessions.focus()

Full control over Claude sessions — starting, sending follow-ups, killing, listing, and focusing.

Use when: Your instrument spawns or manages Claude sessions.

Connector permissions

`connectors.read`

Enables: api.connectors.listStageConnectors(), api.connectors.isAuthorized()

Read-only access to connector state. Can check which connectors are configured and whether they’re authorized.

Use when: You need to display connector status or conditionally show features based on available integrations.

`connectors.credentials.read`

Enables: api.connectors.getCredential()

Access to connector credentials (tokens, API keys). This is sensitive — only request if your instrument needs to make direct API calls to external services.

Use when: Your instrument calls external APIs directly (GitHub, Jira, etc.) rather than going through the host.

`connectors.connect`

Enables: api.connectors.connect(), api.connectors.disconnect()

Ability to initiate and revoke connector authorization flows.

Use when: Your instrument manages connector setup on behalf of the user.

Stage permissions

`stages.read`

Enables: api.stages.list(), api.stages.active()

Read the list of open stages (project folders) and which one is active.

Use when: Your instrument needs to know which projects are open.

`stages.observe`

Enables: Subscription to stage.added, stage.removed, stage.selected, and stage.updated events

React to stage changes in real time. stage.selected fires when the user switches stages; stage.updated fires when the active stage’s metadata refreshes (after commits, file changes). Both carry a StageInfo payload with branch, HEAD SHA, and change counts. Note: you can always subscribe to these events without this permission, but the host may throttle or filter them.

Use when: Your instrument needs to update its UI immediately when stages change or needs git context about the active stage.

Permission combinations

Common permission sets for typical instruments:

Instrument type	Permissions
Simple sidebar widget	`storage.properties`
Task manager	`storage.properties`, `storage.db`, `sessions`, `stages.read`, `stages.observe`
File browser	`storage.properties`, `storage.files`
Session monitor	`storage.properties`, `sessions`, `stages.read`
Full-featured	All 9 permissions

Requesting all permissions

For development or instruments that need everything:

{
  "permissions": [
    "storage.files",
    "storage.db",
    "storage.properties",
    "sessions",
    "connectors.read",
    "connectors.credentials.read",
    "connectors.connect",
    "stages.read",
    "stages.observe"
  ]
}