Multi-tenancy model

You need multi-tenancy when one Tonbo account serves many downstream customers whose storage must stay isolated: a sandbox platform, an agent product with per-customer data, an ML service running customer jobs. The model gives each customer a tenant you can grant, meter, and revoke as a unit, and your customers never sign up to Tonbo: your platform holds one Tonbo identity (the root user) and maps your own customer and task ids onto tenants and runtimes.

If you mount your own workspaces as yourself, none of these objects exist for you; skip this page. The end-to-end recipe is the platform quickstart; this page is the model underneath it.

┌─────────────────────────────────┐
│  Root user: your API key        │
└────────────────┬────────────────┘
                 │ owns
                 ▼
┌─────────────────────────────────┐
│  Tenant: "acme"                 │  one of your customers
└────────────────┬────────────────┘
                 │ scopes
                 ▼
┌─────────────────────────────────┐
│  Runtime: "task-123"            │  their sandbox / VM / task
└────────────────┬────────────────┘
                 │ you issue it a
                 ▼
┌─────────────────────────────────┐
│  Mount ticket: signed, short    │  the only thing the runtime gets
└────────────────┬────────────────┘
                 │ runtime mounts it at /mnt/work
                 ▼
┌─────────────────────────────────┐
│  Workspace: "my-workspace"      │  a real POSIX filesystem
└─────────────────────────────────┘

  access grant = the rule that authorizes the ticket:
     "acme / task-123  may mount  my-workspace  as  ro | rw"

Read it top to bottom: your root user owns a tenant (acme), which scopes a runtime (task-123); your backend issues that runtime a mount ticket, which it mounts at /mnt/work. The access grant is the rule that authorizes the ticket, and the workspace (my-workspace) is the storage on the other end.

Root user

Your platform's Tonbo identity: a User Center account or an API key (tbo_…). It is the only identity that signs up to Tonbo, and it stays in your control plane. It owns your tenants, workspaces, grants, and issues every ticket. Never ship it into a customer-facing runtime.

Tenant

One of your customers, projects, or account boundaries. A tenant has a stable slug and an optional external_id (your own customer id, e.g. cust_42) and metadata. It is the unit for grouping and for bulk revocation: delete a tenant and every grant and session under it is revoked. The end customer behind a tenant has no Tonbo account.

Runtime

The thing that actually mounts: a task, container, VM, agent run, or sandbox (Daytona, Modal, your own). You identify it with an opaque runtime id that you choose. It is a scope value, not a resource you pre-create. Artifacts records the runtime id directly on grants and tickets the first time you use it.

Workspace

The storage namespace being shared, addressed as artifacts://<handle>/<name>. Managed (Tonbo-issued storage credentials) or BYO (your own S3 bucket). See Workspaces.

Access grant

The durable authorization edge that connects identity to storage: this tenant (tenant-wide) or this specific runtime may mount this workspace in ro or rw. A grant with no runtime is tenant-wide and applies to any runtime under the tenant; a runtime-scoped grant applies only to requests carrying that runtime id. Grants are what you revoke. See Temporary mount credentials.

Mount ticket

The short-lived signed file a runtime presents to mount. It wraps the workspace's mount manifest (endpoint, scoped credentials, mode, expiry) and is the only material that reaches the customer runtime. The runtime mounts with artifacts mount --ticket-file <path> /mnt/work. It carries no Tonbo account and cannot widen its own access.

How they compose

Issuing a ticket is one shot. createMountTicket(tenant, runtime, { workspace, mode }) (or artifacts platform ticket create <workspace> --to <tenant>/<runtime>) creates a missing tenant and a missing runtime-scoped grant in the same call, then issues the ticket. Create tenants and grants explicitly only when you need tenant metadata, a tenant-wide grant, or to authorize without issuing yet.

Walk it end to end in Quickstart for platform users. For grant shapes, revocation, and session lifetime, see Temporary mount credentials.