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

# Distribute Files to Agents

> Distribute versioned manuals, skills, configs, and binary tools to agents with read-only mounts.

Use a versioned file system when many agents need the same files at a stable path.

Put operating manuals, skills, configs, test fixtures, or binary tools in a file system. Update it from a laptop, CI job, or backend service. Agents mount it read-only. When an autosave checkpoint or permanent snapshot commits, following mounts refresh changed paths automatically.

## Pattern

1. Store shared files in a versioned file system.
2. Publish updates from outside the sandbox with `tl fs push`.
3. Mount the file system into agents as a read-only directory.
4. Follow the file system for automatic distribution, or pin a permanent snapshot for fixed releases.

## Create an Asset File System

<Tabs>
  <Tab title="CLI">
    ```bash theme={null}
    $ tl fs create agent-assets
    Created filesystem agent-assets (empty).
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    from tensorlake.filesystem import FilesystemClient

    client = FilesystemClient()
    fs = client.create("agent-assets")
    ```
  </Tab>

  <Tab title="TypeScript">
    ```typescript theme={null}
    import { FilesystemClient } from "tensorlake";

    const client = new FilesystemClient();
    const fs = await client.create("agent-assets");
    ```
  </Tab>
</Tabs>

Keep the layout simple and stable:

```text theme={null}
agent-assets/
  manuals/
  skills/
  bin/
  configs/
```

Agents can refer to paths like `/opt/agent-assets/manuals/operator.md`, `/opt/agent-assets/skills/research/SKILL.md`, or `/opt/agent-assets/bin/validator`.

## Publish From Outside a Sandbox

The producer does not need a sandbox, and it does not need a mount. Push a directory and create a permanent snapshot for the release:

```bash theme={null}
$ tl fs push ./agent-assets agent-assets -m "publish agent assets"
Pushed ./agent-assets to agent-assets (48 file(s)).
```

Pushing the same directory again uploads only what changed, the right shape for a CI job or release service that republishes on every change. Pass `-m` on the changed push that should create a permanent snapshot; without it, the push creates an ephemeral autosave checkpoint. A push with no changes is a quiet no-op.

Pushes honor `.gitignore`, preserve symlinks, and preserve executable bits on regular files. A file system has no special `.git` handling: only `.gitignore` governs what is excluded.

## Mount Into Agents

Mount the file system read-only at a predictable path with the sandbox mount API's per-mount `read_only` option (see [Mount Filesystems](/sandboxes/mount-filesystems#read-only)):

<Tabs>
  <Tab title="CLI">
    ```bash theme={null}
    tl sbx create -f agent-assets:/opt/agent-assets:ro
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    from tensorlake.sandbox import FileSystemMount, Sandbox

    sandbox = Sandbox.create(
        file_systems=[
            FileSystemMount(
                file_system_id="agent-assets",
                mount_path="/opt/agent-assets",
                read_only=True,
            ),
        ],
    )
    ```
  </Tab>

  <Tab title="TypeScript">
    ```typescript theme={null}
    import { Sandbox } from "tensorlake";

    const sandbox = await Sandbox.create({
      fileSystems: [
        {
          fileSystemId: "agent-assets",
          mountPath: "/opt/agent-assets",
          readOnly: true,
        },
      ],
    });
    ```
  </Tab>
</Tabs>

New sandboxes read the current state. Running following mounts refresh as the shared timeline advances, so updated manuals, skills, configs, and tools appear without rebuilding sandbox images.

Agents should write outputs to a separate writable mount. Keep shared assets read-only so every agent sees the same source files.

## Version Releases

Use a permanent snapshot when a run must be reproducible. The `-m` push above already created one; find its id under `Snapshots` in `tl fs history agent-assets` and pin the mount to it:

```bash theme={null}
tl fs history agent-assets
tl sbx create -f 'agent-assets@9f2a1c8e4d6b1a0f3c7e9d2b8a4f6c1e0d3b7a99fedcba987654321001234567:/opt/agent-assets:ro'
```

A pinned mount requires `ro` and never follows the file system: `agent-assets` keeps advancing for the following fleet while every pinned run keeps serving exactly the release snapshot. Recent autosave IDs cannot be pinned — only permanent snapshots can — so a release anchor never expires. Deleting a release snapshot while sandboxes still pin it is refused with a `409` naming the pin count.

Pins work at creation, on warm-pool claims, and on runtime attach, in every SDK — see [Pinned mounts](/sandboxes/mount-filesystems#pinned-mounts) for the Python, TypeScript, and HTTP forms.

If a release needs its own file-system name — one you might promote or edit later — fork the file system at the release snapshot instead. A fork is metadata-only, sharing the immutable content, and stays fixed as long as nothing writes to it:

```python theme={null}
from tensorlake.filesystem import FilesystemClient

client = FilesystemClient()
client.fork(
    "agent-assets-v1",
    "agent-assets",
    "9f2a1c8e4d6b1a0f3c7e9d2b8a4f6c1e0d3b7a99fedcba987654321001234567",
)
```

```bash theme={null}
tl sbx create -f agent-assets-v1:/opt/agent-assets:ro
```

If you need named release channels (`stable`, `canary`) that you advance deliberately, back the assets with a [Git repository](/git/introduction) and use branches as channels. That's the surface built for explicit publication.

## Binary Tools

Put tools under a stable directory such as `bin/` with the executable bit set, and push:

```bash theme={null}
chmod +x agent-assets/bin/validator
tl fs push ./agent-assets agent-assets -m "add validator tool"
```

Agents can call the tool directly:

```bash theme={null}
/opt/agent-assets/bin/validator --input /work/result.json
```

## Choose a Mount

| Need                                                         | Use                                                                                  |
| ------------------------------------------------------------ | ------------------------------------------------------------------------------------ |
| Roll out the latest manuals, skills, or tools to many agents | Following `read_only` sandbox mount                                                  |
| Keep an eval, benchmark, or release run fixed                | Pin a permanent snapshot: `read_only` + `snapshot_id` (`agent-assets@<snapshot-id>`) |
| Give a release its own name to promote or edit later         | Fork the snapshot, mount the fork `read_only`                                        |
| Publish assets from CI or an external service                | `tl fs push`                                                                         |
| Let an agent create or modify files                          | [Writable mount](/filesystems/filesystem-mounts#writable-mounts)                     |

## Next Steps

<CardGroup cols={2}>
  <Card title="Read-only Mounts" icon="lock" href="/filesystems/read-only-mounts">
    Choose between following the file system and pinning a permanent snapshot.
  </Card>

  <Card title="File System Mounts" icon="folder-tree" href="/filesystems/filesystem-mounts">
    Give agents a separate place to write outputs.
  </Card>
</CardGroup>