> ## Documentation Index
> Fetch the complete documentation index at: https://docs.archil.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Isolated per-tenant storage for multi-tenant agent applications

> Give every tenant of a multi-tenant AI agent application its own isolated, persistent disk with tenant-scoped credentials, and provision thousands of them through the API. Covers disk per tenant vs. a subdirectory per tenant, credentials, sandboxes, and tenants that bring their own bucket.

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

| | Disk per tenant | Subdirectory per tenant on a shared disk |
| - | - | - |
| Isolation boundary | Credentials are scoped to the tenant's disk | None: a mount token or IAM grant covers the entire disk |
| What tenant code can reach | Only that tenant's files | Every tenant's files, if the code can get the disk's credentials |
| Rollback and parallel attempts | Checkpoint or branch one tenant's disk on its own | Checkpoints and branches cover every tenant at once |
| Offboarding | Delete the disk | Delete the directory and rotate the shared credentials |

A [subdirectory mount](https://docs.archil.com/reference/archil-cli.md#subdirectory-mounts) 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](https://docs.archil.com/administration/best-practices.md#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 `_`.

```typescript TypeScript theme={null}
import * as archil from "disk";

// Runs on your backend, with your Archil API key.
const { disk, token } = await archil.createDisk({ name: `tenant-${tenantId}` });
// Store disk.id with the tenant. `token` mounts this disk only and is returned once.

// Later: issue another token for this tenant, or revoke one.
const user = await disk.createToken(`worker-${workerId}`);
await disk.removeUser("token", user.identifier);
```

```python Python theme={null}
import archil
from archil import TokenUser

# Runs on your backend, with your Archil API key.
result = archil.create_disk(name=f"tenant-{tenant_id}")
disk = result.disk
# Store disk.id with the tenant. result.token mounts this disk only and is returned once.

# Later: issue another token for this tenant, or revoke one.
user = disk.add_user(TokenUser(nickname=f"worker-{worker_id}"))
disk.remove_user("token", user.identifier)
```

You can also create disks with the [Create Disk API](https://docs.archil.com/api-reference/disks/create-disk.md) or
[Terraform](https://docs.archil.com/reference/terraform.md). 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](https://docs.archil.com/concepts/authorization.md#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](https://docs.archil.com/concepts/authorization.md#iam-based-disk-authorization).
* **S3 credentials** reach one disk over the [S3 API](https://docs.archil.com/protocols/s3-api.md) 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](https://docs.archil.com/protocols/s3-api.md#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](https://docs.archil.com/api-reference/disks/create-share-url.md).

## Run each tenant's agents against its own disk

In an [Archil sandbox](https://docs.archil.com/compute/sandboxes/introduction.md), 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.

```typescript theme={null}
import { Archil } from "disk";

const client = new Archil({ apiKey: process.env.ARCHIL_API_KEY, region: "aws-us-east-1" });
const sandbox = await client.sandboxes.create({
  baseImage: "ubuntu:24.04",
  mounts: [{ disk: tenantDiskId, path: "/mnt/archil" }],
});
```

On the Developer plan and above, give tenant sandboxes a deny-by-default network policy, and use
[credential brokering](https://docs.archil.com/compute/sandboxes/firewall.md#credential-brokering) so secrets are added to outgoing requests
without being placed in the sandbox. See [Sandbox firewall](https://docs.archil.com/compute/sandboxes/firewall.md).

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](https://docs.archil.com/compute/serverless-execution.md),
over FUSE in sandboxes from [other providers](https://docs.archil.com/guides/platforms/daytona.md), and from your web app through the
[S3 API](https://docs.archil.com/protocols/s3-api.md) 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](https://docs.archil.com/concepts/branches-and-checkpoints.md). Branches share their disk's credentials, so they
separate work within a tenant, not between tenants. See [Sharing a disk between agents](https://docs.archil.com/concepts/sharing-disks.md#sharing-a-disk-between-agents).

## Scale to thousands of tenants

* **Disks per region:** Developer 1,000, Team 25,000, Enterprise unlimited. See [Limits](https://docs.archil.com/reference/limits.md#disks-per-plan).
* **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](https://docs.archil.com/concepts/metering.md) and [Pricing & Billing](https://docs.archil.com/administration/billing.md).
* **Organizations:** use separate [organizations](https://docs.archil.com/administration/organizations.md) for environments such as Dev and
  Production, or to group tenants. Several organizations can be billed under one contract;
  [contact us](mailto:support@archil.com) 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](https://docs.archil.com/concepts/data-sources.md). 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](https://docs.archil.com/data-sources/s3-object-storage.md#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](https://docs.archil.com/data-sources/s3-object-storage.md#authorizing-every-disk-in-your-organization).

To mount a bucket that already holds a tenant's data, see [Mount an existing bucket](https://docs.archil.com/guides/storage/mount-existing-bucket.md).

## 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.

## Related

* [Best practices](https://docs.archil.com/administration/best-practices.md): accounts, disks, and credentials for production and multi-tenant workloads
* [Authorization](https://docs.archil.com/concepts/authorization.md): every credential type and how to create it
* On archil.com: [Isolated per-tenant storage for multi-tenant AI agent applications](https://archil.com/article/isolated-per-tenant-storage-for-multi-tenant-ai-agent-applications)
  and [Scaling a multi-tenant AI agent product to thousands of tenants](https://archil.com/article/scaling-a-multi-tenant-ai-agent-product-to-thousands-of-tenants-provisioning-credentials-and-cost-of-one-disk-per-tenant)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.