> ## 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 Tensorlake 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 repository. Update the repository from a laptop, CI job, or backend service. Agents mount a branch read-only. When the branch moves, following mounts refresh changed paths automatically.

## Pattern

1. Store shared files in a Tensorlake repository.
2. Publish updates from outside the sandbox with Git or the Repository SDKs.
3. Mount the repository into agents as a read-only directory.
4. Follow a branch for automatic distribution, or pin a commit for fixed releases.

## Create an Asset Repository

```bash theme={null}
$ tl git create agent-assets --default-branch main
created https://git.tensorlake.ai/project_9f3c2a1b/agent-assets
```

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. It can be a developer machine, CI job, release service, or control plane process.

<Tabs>
  <Tab title="Git">
    ```bash theme={null}
    TOKEN=$(tl git token --repo agent-assets --json | jq -r .token)
    git clone https://t:$TOKEN@git.tensorlake.ai/project_9f3c2a1b/agent-assets

    cp -R ./manuals ./skills ./bin ./configs agent-assets/
    chmod +x agent-assets/bin/validator

    git -C agent-assets add .
    git -C agent-assets commit -m "publish agent assets"
    git -C agent-assets push origin main
    ```
  </Tab>

  <Tab title="Python">
    ```bash theme={null}
    export TENSORLAKE_API_KEY=tlk_...
    ```

    ```python theme={null}
    from tensorlake import RepositoryClient

    with RepositoryClient.from_env() as repos:
        report = repos.push_worktree(
            "agent-assets",
            root="./agent-assets",
            branch="main",
            message="publish agent assets",
        )
        print(report.commit)
    ```
  </Tab>

  <Tab title="TypeScript">
    ```bash theme={null}
    export TENSORLAKE_API_KEY=tlk_...
    ```

    ```typescript theme={null}
    import { RepositoryClient } from "tensorlake";

    const repos = await RepositoryClient.fromEnv();
    const report = await repos.pushWorktree("agent-assets", {
      path: "./agent-assets",
      branch: "main",
      message: "publish agent assets",
    });

    console.log(report.commit);
    ```
  </Tab>
</Tabs>

`push_worktree` and `pushWorktree` skip `.git`, honor `.gitignore`, preserve symlinks, and preserve executable bits on regular files.

## Mount Into Agents

Mount the asset branch read-only at a predictable path:

```bash theme={null}
$ tl fs mount agent-assets:main /opt/agent-assets --mode ro
Mounted agent-assets:main at /opt/agent-assets (workspace 7c2e9f0a1b3d, read-only, follows the branch)
```

New sandboxes read the current branch tip. Running following read-only mounts refresh as `main` moves, so updated manuals, skills, configs, and tools appear without rebuilding sandbox images.

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

## Version Releases

Use branches as channels:

```bash theme={null}
tl fs mount agent-assets:stable /opt/agent-assets --mode ro
```

Move `stable` when you want following mounts to receive a release. Branch activity records who moved the branch and which commit became the new tip.

Use a commit when a run must be reproducible:

```bash theme={null}
tl fs mount agent-assets:9f2a1c8e4d6b1a0f3c7e9d2b8a4f6c1e0d3b7a99 /opt/agent-assets --mode ro
```

Pinned mounts stay fixed for the lifetime of the sandbox.

## Binary Tools

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

```bash theme={null}
chmod +x agent-assets/bin/validator
git -C agent-assets add bin/validator
git -C agent-assets commit -m "add validator tool"
git -C agent-assets push origin main
```

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 mount                              |
| Keep an eval, benchmark, or release run fixed                | Pinned read-only mount                                 |
| Publish assets from CI or an external service                | Git push or Repository SDK `push_worktree`             |
| Let an agent create or modify files                          | [Writable workspace](/filesystems/writable-workspaces) |

## Next Steps

<CardGroup cols={2}>
  <Card title="Read-only Mounts" icon="lock" href="/filesystems/read-only-mounts">
    Choose between following branches and pinned commits.
  </Card>

  <Card title="Repository SDKs" icon="rectangle-code" href="/filesystems/repository-sdks">
    Push local files and inspect repository state from Python or TypeScript.
  </Card>

  <Card title="Git Workflows" icon="code-commit" href="/filesystems/git-repositories">
    Publish the same assets with ordinary Git commands.
  </Card>

  <Card title="Writable Workspaces" icon="pen-line" href="/filesystems/writable-workspaces">
    Give agents a separate place to write outputs.
  </Card>
</CardGroup>