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

# Mount an existing S3 bucket as a POSIX file system

> Mount an existing Amazon S3, Google Cloud Storage, or Cloudflare R2 bucket as a POSIX file system for AI agents, without migrating or copying your data. Includes how Archil compares with Amazon S3 Files and Mountpoint for Amazon S3.

To give agents a POSIX file system over a bucket you already have, create an Archil disk with that bucket as its
[data source](https://docs.archil.com/concepts/data-sources.md), then mount the disk. You don't migrate or convert anything: the objects already
in the bucket appear as files, and files your agents write land back in the bucket as ordinary objects at the matching
key, readable by any S3 tool. Archil reads objects on demand and keeps active data on its SSD storage layer, so agents
can use `ls`, `grep`, `cat`, Python, git, and other file tools on the bucket's data without downloading it first.

This works with Amazon S3, Google Cloud Storage, Cloudflare R2, and S3-compatible stores such as Tigris, MinIO, Wasabi,
Backblaze B2, and DigitalOcean Spaces. Bringing your own bucket is available on the Developer, Team, and Enterprise
plans. See [Plans and limits](https://docs.archil.com/administration/billing.md#plans-and-limits).

## 1. Grant Archil access to the bucket

For Amazon S3, attach a bucket resource policy that lets Archil's IAM role reach the bucket, with an `archilSessionId`
condition that matches the disk's session ID. No long-lived credentials change hands. You can use static IAM credentials instead.
Google Cloud Storage uses HMAC keys, and Cloudflare R2 and other S3-compatible stores use an access key and endpoint.

The [S3 Object Storage](https://docs.archil.com/data-sources/s3-object-storage.md) page has the policy, the principal ARN for each region, and the
setup steps for every provider. The [Archil console](https://console.archil.com) walks you through the same setup when
you create a disk there: it generates the session ID and a ready-made policy. In Terraform, the session ID is
`mount[0].session_id`. The SDK examples below use static IAM credentials.

## 2. Create a disk that points at the bucket

Create the disk in the console, or with the SDK, CLI, or [Terraform](https://docs.archil.com/reference/terraform.md). Set `bucketPrefix` to
expose only part of the bucket as the disk's root.

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

const { disk, token } = await archil.createDisk({
  name: "research-data",
  mounts: [{
    type: "s3",
    bucketName: "my-bucket",
    bucketPrefix: "datasets/",
    accessKeyId: "AKIA...",
    secretAccessKey: "...",
  }],
});
// `token` is the disk's mount token. It's only returned once.
```

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

result = archil.create_disk(
    name="research-data",
    mounts=[S3Mount(
        bucket_name="my-bucket",
        bucket_prefix="datasets/",
        access_key_id="AKIA...",
        secret_access_key="...",
    )],
)
# result.token is the disk's mount token. It's only returned once.
```

For GCS, R2, and S3-compatible stores, use the mount types and fields shown on
[S3 Object Storage](https://docs.archil.com/data-sources/s3-object-storage.md).

## 3. Mount the disk where your agents run

Pick the place your agents run:

* **A Linux server, VM, or container:** install the client and run `archil mount`. See [Mount on Linux](https://docs.archil.com/mounting/linux.md)
  and [Mount in a container](https://docs.archil.com/mounting/containers.md).

  ```bash theme={null}
  curl -s https://archil.com/install | sh
  sudo mkdir -p /mnt/archil
  export ARCHIL_MOUNT_TOKEN="<disk-token>"
  sudo --preserve-env=ARCHIL_MOUNT_TOKEN archil mount <org>/research-data /mnt/archil --region aws-us-east-1
  ```

  Name the disk by its owner and name, or by its ID (`dsk-...`). On a personal account, the owner is your email
  address, for example `you@example.com/research-data`.

* **An Archil sandbox:** pass the disk in `mounts` when you create the sandbox. Archil handles mount authentication.
  See [Attaching an Archil disk](https://docs.archil.com/compute/sandboxes/introduction.md#attaching-an-archil-disk).

* **One command at a time, with no server:** run `disk.exec()` or `npx disk exec` against the disk. See
  [Serverless execution](https://docs.archil.com/compute/serverless-execution.md).

* **Kubernetes:** use the [CSI driver](https://docs.archil.com/reference/csi-driver.md).

* **Another sandbox provider:** see the guides for [Daytona](https://docs.archil.com/guides/platforms/daytona.md), [E2B](https://docs.archil.com/guides/platforms/e2b.md),
  [Modal](https://docs.archil.com/guides/platforms/modal.md), [Vercel Sandbox](https://docs.archil.com/guides/platforms/vercel-sandbox.md), and
  [Cloudflare Containers](https://docs.archil.com/guides/platforms/cloudflare-containers.md).

Many agents can use the same disk at once. A disk accepts up to 5,000 connected clients. Use read-only mounts for
readers, and conditional or shared mode for several writers. See [Sharing Disks](https://docs.archil.com/concepts/sharing-disks.md).

## What to expect

* **Your bucket stays the system of record.** Each file is an ordinary object at its path. Archil also writes
  zero-byte directory-marker objects, such as `datasets/out/`, and an `.archil/` entry. POSIX metadata such as mode
  bits and ownership is tracked by Archil and isn't visible in the bucket. See [POSIX metadata](https://docs.archil.com/concepts/data-sources.md#posix-metadata).
* **Writes are durable on Archil once `fsync` returns, and copied to the bucket in the background.** The disk is
  strongly consistent, so other Archil clients and the disk's [S3 API](https://docs.archil.com/protocols/s3-api.md) read it, not the bucket;
  only tools that read the bucket directly wait for the copy. Archil copies a file once it has gone 15 seconds without a
  write, so it usually reaches the bucket about 20 seconds after its last write. A file that keeps changing is copied
  no later than 10 minutes after its first write that hasn't reached the bucket. See
  [From the disk to the bucket](https://docs.archil.com/details/consistency.md#from-the-disk-to-the-bucket).
* **Objects written straight to the bucket appear after Archil lists that directory again.** When a directory in use
  is read and its listing is more than five minutes old, Archil relists it in the background, so new objects usually
  appear within 5 to 10 minutes. A directory the disk hasn't listed yet shows them on its first read. See
  [From the bucket to the disk](https://docs.archil.com/details/consistency.md#from-the-bucket-to-the-disk).
* **Don't write the same file from both sides at once.** Writing different paths through the bucket and the disk is
  fine. See [Concurrent writes](https://docs.archil.com/concepts/data-sources.md#concurrent-writes).
* **Deleting the disk leaves your data in the bucket.** Archil stops synchronizing and discards its cached copy.
* **Limits follow the bucket:** files up to 5 TiB and paths up to 1,024 bytes on Amazon S3, one data source per disk.
  See [Limits](https://docs.archil.com/reference/limits.md#disks-synchronized-with-a-data-source).
* **Checkpoints and branches** on disks that use your own bucket are available on Enterprise. See
  [Checkpoints on BYOB disks](https://docs.archil.com/administration/billing.md#checkpoints-on-byob-disks).

If you're starting a new data set and don't need it in your own bucket, skip the data source. Disks use Archil-managed
storage by default.

## Compared with Amazon S3 Files and Mountpoint for Amazon S3

All three let you reach data in an existing bucket through file paths, without moving it. They differ in which file
operations work, where you can mount, and when writes reach the bucket.

| | Archil | Amazon S3 Files | Mountpoint for Amazon S3 |
| - | - | - | - |
| What it is | Managed POSIX file system with an SSD storage layer replicated across Availability Zones, an S3 API, and sandboxes | NFS file system for an S3 bucket, built on Amazon EFS, for AWS compute | Open-source FUSE client that turns file operations into S3 requests |
| Buckets | Amazon S3, GCS, R2, S3-compatible | Amazon S3, with Versioning enabled | Amazon S3; other S3-compatible stores aren't supported |
| Edit existing files | Yes, including random writes and appends | Yes | Sequential writes only; overwrite is opt-in and replaces the whole file |
| Rename | Atomic on the disk, including directories | Yes on the file system; in the bucket, each object is copied and deleted, so not atomic | Files on S3 Express One Zone only; no directory rename |
| Several machines writing | Up to 5,000 clients per disk, coordinated with delegations or conditional mode | Yes, over NFS | No coordination between writers |
| When writes reach the bucket | In the background, usually tens of seconds after the last write; the disk's S3 API sees them immediately | After 60 seconds without writes to the file, as a new object version | On close or `fsync` |
| Snapshots and branches | Checkpoint p50 13 ms, branch p50 33 ms (Enterprise on your own bucket) | No native branching; S3 Versioning keeps object history | None |
| Cost model | Active storage per GiB-month, plus your bucket | Billed through AWS with the bucket | Open source; you pay for S3 requests and storage |

**Choose Amazon S3 Files** when your compute is on AWS, you want IAM-governed file access to existing S3 data with S3
Versioning as history, and your compute already isolates the code that runs there.

**Choose Mountpoint for Amazon S3** when reads of large objects dominate, such as training data or data lakes, one
client at a time writes new files sequentially, and you want a free client with no service in the data path.

**Choose Archil** when agents edit files in place, rename directories, or run git, npm, or SQLite on the data; when
several machines write the same tree; when the data is in GCS or R2 or your compute runs outside AWS; or when each
agent needs an isolated sandbox or its own branch next to the data.

For benchmarks and more detail, see [Solution Comparison](https://docs.archil.com/details/comparison.md), and on archil.com
[Archil vs Amazon S3 Files](https://archil.com/compare/amazon-s3-files),
[Archil vs Mountpoint for Amazon S3](https://archil.com/compare/mountpoint-for-amazon-s3), and
[Mounting a POSIX file system over an existing S3 bucket without migrating data](https://archil.com/article/mounting-a-posix-filesystem-directly-over-an-existing-s3-bucket-without-migrating-data).

## Related

* [Data Sources](https://docs.archil.com/concepts/data-sources.md): how synchronization, consistency, and atomicity work with your bucket
* [S3 Object Storage](https://docs.archil.com/data-sources/s3-object-storage.md): access setup for each provider
* [Isolated per-tenant storage](https://docs.archil.com/guides/storage/per-tenant-storage.md): one disk per tenant, including tenants with their own buckets
* [Data ownership and portability](https://docs.archil.com/reference/data-ownership.md)


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