Skip to main content
To isolate tenants in a multi-tenant agent application, give each tenant its own Archil disk. A disk is Archil’s unit of access isolation: its credentials are scoped to that one disk, including all of its branches and checkpoints, so code holding one tenant’s credentials can’t reach another tenant’s files. Disks are created with one API call (9.3 ms p50), persist across agent sessions and sandbox restarts, and scale to thousands of tenants: Team allows 25,000 disks per region and Enterprise has no cap.

Disk per tenant vs. a subdirectory per tenant

A subdirectory mount makes a directory the root of a mount, but the credentials that allow it can mount the whole disk. POSIX permissions aren’t a security boundary between untrusted tenants either. Use subdirectories to organize work within one tenant, such as a directory per agent, and use separate disks between tenants. See Use a disk as your unit of isolation.

Provision a disk per tenant

Create the tenant’s disk from your backend when the tenant signs up, or the first time one of its agents runs. Disk names can use letters, digits, -, and _.
You can also create disks with the Create Disk API or Terraform. Disks use Archil-managed storage by default, so a new tenant doesn’t need a bucket.

Scope credentials to the tenant

Archil has separate credentials for managing disks and for reaching a disk’s data. Keep the broad one on your backend and hand tenants only the narrow ones.
  • API keys are scoped to an organization and region and have full access to every disk in it. Keep them on your backend, never in a tenant’s sandbox or client.
  • Disk tokens mount one disk. They can have a TTL or be one-time use. Store each tenant’s tokens with that tenant, and revoke a token with removeUser. See Token-based disk authorization.
  • IAM authorization lets an AWS IAM role or user mount one disk, so a tenant’s workers can mount with their own IAM role instead of a token. See IAM-based disk authorization.
  • S3 credentials reach one disk over the S3 API and can expire, for example disk.createS3Credentials({ nickname: "uploads", ttl: "24h" }). Use them for your app’s uploads and downloads for that tenant. Most AWS SDKs and AWS CLI v2 need AWS_REQUEST_CHECKSUM_CALCULATION=when_required; see Client configuration.
  • Share URLs let someone download a single file without credentials. They expire after 24 hours by default, and at most after 7 days. See Create Share URL.

Run each tenant’s agents against its own disk

In an Archil sandbox, mount only the tenant’s disk. Archil handles mount authentication, so the sandbox never sees a token, and each sandbox is a Firecracker microVM with its own Linux kernel.
On the Developer plan and above, give tenant sandboxes a deny-by-default network policy, and use credential brokering so secrets are added to outgoing requests without being placed in the sandbox. See Sandbox firewall. The tenant’s files live on the disk, not in the sandbox, so they survive stopping or deleting the sandbox (stop a running sandbox before you delete it), and the next sandbox for that tenant mounts the same files. The same disk also works with serverless execution, over FUSE in sandboxes from other providers, and from your web app through the S3 API or the SDKs. When several of one tenant’s agents work at once, share that tenant’s disk between them in conditional mode, or give each agent its own branch. Branches share their disk’s credentials, so they separate work within a tenant, not between tenants. See Sharing a disk between agents.

Scale to thousands of tenants

  • Disks per region: Developer 1,000, Team 25,000, Enterprise unlimited. See Limits.
  • Clients per disk: up to 5,000 connected clients on one tenant’s disk.
  • Cost follows data, not disk count: storage is metered on the data each disk holds. Active storage counts only data in the high-speed layer, which stays active for up to an hour after its last access, so an idle tenant’s disk falls back to the lower archive rate (Archil-managed disks) or to just your bucket (disks synced to your own bucket). See Metering and Pricing & Billing.
  • Organizations: use separate organizations for environments such as Dev and Production, or to group tenants. Several organizations can be billed under one contract; contact us to set that up.

Tenants that bring their own bucket

If a tenant wants its data in its own bucket, create that tenant’s disk with the bucket as its data source. For Amazon S3, the tenant adds a bucket policy that grants access only to Archil sessions tagged with that disk’s archilSessionId. See Bucket resource policy. If many tenant disks use one bucket that you own, a policy that matches your archilAccountId covers every current and future disk in your organization without edits. The trade-off is that any disk in your organization can then reach the whole bucket, so a per-tenant bucketPrefix organizes the data but doesn’t enforce isolation. See Authorizing every disk in your organization. To mount a bucket that already holds a tenant’s data, see Mount an existing bucket.

Offboard a tenant

Revoke the tenant’s tokens and S3 credentials, then delete its disk. Deleting a disk that uses Archil-managed storage removes its data. Deleting a disk that uses the tenant’s own bucket stops synchronization and leaves the objects in the bucket, under the tenant’s control.