# Archil (/docs/storage/archil)

<!-- agent-signals: reading_time_min: 2 · est_tokens: 1287 · updated: 2026-07-30 -->
Related: [Cloud buckets](/docs/storage/cloud-buckets.md), [OpenCode](/docs/agents/opencode.md)

[Archil](https://archil.com) is an infinite, elastic, POSIX file system that automatically synchronizes to object storage like S3, R2, and GCS. Use Archil when you need to mount a bucket to your E2B sandbox but want higher out-of-the-box performance than `s3fs` or `gcsfuse` — it's a natural fit for parallel agents that share state.

Key properties:

* Shared SSD read and write caching in front of your object storage bucket for higher performance.
* Mounted as a regular POSIX directory, so any tool, script, or agent in the sandbox can use it.
* Scales to whatever your sandbox writes — you pay only for what you use.
* [Mountable by many sandboxes at once](https://docs.archil.com/concepts/shared-disks) for shared state across parallel agents.

## Build a template [#build-a-template]

Build a template with the `archil` CLI preinstalled. The Archil package depends on `libfuse2`, which is already preinstalled in the base image.

<CodeGroup>
  <CodeBlockTabs defaultValue="JavaScript & TypeScript" groupId="javascript-typescript+python">
    <CodeBlockTabsList>
      <CodeBlockTabsTrigger value="JavaScript & TypeScript">
        JavaScript & TypeScript
      </CodeBlockTabsTrigger>

      <CodeBlockTabsTrigger value="Python">
        Python
      </CodeBlockTabsTrigger>
    </CodeBlockTabsList>

    <CodeBlockTab value="JavaScript & TypeScript">
      ```ts  
      const template = Template()
        .fromBaseImage()
        .runCmd("curl -fsSL https://archil.com/install | sh")
      ```
    </CodeBlockTab>

    <CodeBlockTab value="Python">
      ```python  
      template = (
          Template()
          .from_base_image()
          .run_cmd("curl -fsSL https://archil.com/install | sh")
      )
      ```
    </CodeBlockTab>
  </CodeBlockTabs>
</CodeGroup>

## Mount the disk [#mount-the-disk]

At sandbox runtime, mount the disk with a [disk-scoped mount token](https://docs.archil.com/concepts/disk-users#disk-token-authorization) from the [Archil console](https://console.archil.com).

<CodeGroup isRunnable="false">
  <CodeBlockTabs defaultValue="JavaScript & TypeScript" groupId="javascript-typescript+python">
    <CodeBlockTabsList>
      <CodeBlockTabsTrigger value="JavaScript & TypeScript">
        JavaScript & TypeScript
      </CodeBlockTabsTrigger>

      <CodeBlockTabsTrigger value="Python">
        Python
      </CodeBlockTabsTrigger>
    </CodeBlockTabsList>

    <CodeBlockTab value="JavaScript & TypeScript">
      ```js  
      import { Sandbox } from 'e2b'

      const sandbox = await Sandbox.create('<your template id>')
      await sandbox.commands.run('mkdir -p /home/user/archil', { user: 'root' })
      await sandbox.commands.run(
        'archil mount <disk-name-or-id> /home/user/archil --region <region>',
        { user: 'root', envs: { ARCHIL_MOUNT_TOKEN: '<disk-token>' } }
      )
      await sandbox.commands.run('chown user:user /home/user/archil', { user: 'root' })
      ```
    </CodeBlockTab>

    <CodeBlockTab value="Python">
      ```python  
      from e2b import Sandbox

      sandbox = Sandbox.create("<your template id>")
      sandbox.commands.run("mkdir -p /home/user/archil", user="root")
      sandbox.commands.run(
          "archil mount <disk-name-or-id> /home/user/archil --region <region>",
          user="root",
          envs={"ARCHIL_MOUNT_TOKEN": "<disk-token>"},
      )
      sandbox.commands.run("chown user:user /home/user/archil", user="root")
      ```
    </CodeBlockTab>
  </CodeBlockTabs>
</CodeGroup>

`<disk-name-or-id>` is either an owner-qualified name (`myorg/my-disk`) or a disk ID (`dsk-0123456789abcdef`); `<region>` is the disk's region (e.g. `aws-us-east-1`). The disk is now mounted at `/home/user/archil` as a regular POSIX directory — any tool, script, or agent in the sandbox can read and write through it.

## Unmount before killing the sandbox [#unmount-before-killing-the-sandbox]

Call `archil unmount` before tearing down the sandbox. It's best practice to release filesystem resources cleanly rather than letting the sandbox kill take them down.

<CodeGroup isRunnable="false">
  <CodeBlockTabs defaultValue="JavaScript & TypeScript" groupId="javascript-typescript+python">
    <CodeBlockTabsList>
      <CodeBlockTabsTrigger value="JavaScript & TypeScript">
        JavaScript & TypeScript
      </CodeBlockTabsTrigger>

      <CodeBlockTabsTrigger value="Python">
        Python
      </CodeBlockTabsTrigger>
    </CodeBlockTabsList>

    <CodeBlockTab value="JavaScript & TypeScript">
      ```js  
      await sandbox.commands.run('archil unmount /home/user/archil', { user: 'root' })
      await sandbox.kill()
      ```
    </CodeBlockTab>

    <CodeBlockTab value="Python">
      ```python  
      sandbox.commands.run("archil unmount /home/user/archil", user="root")
      sandbox.kill()
      ```
    </CodeBlockTab>
  </CodeBlockTabs>
</CodeGroup>

## Sharing across sandboxes [#sharing-across-sandboxes]

The same disk can be mounted by multiple sandboxes concurrently. Add `--shared` to the mount command — see [Shared Disks](https://docs.archil.com/concepts/shared-disks) for the checkout-based concurrency model.