Skip to main content
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

Keep the layout simple and stable:
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:
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:
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 pinned permanent snapshot when a run must be reproducible:
Pinned mounts stay fixed for the lifetime of the sandbox. Find permanent snapshot IDs under Snapshots in tl fs history agent-assets. Recent autosave IDs can expire and should not be used as long-lived release anchors. If you need named release channels (stable, canary) that you advance deliberately, back the assets with a Git repository 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:
Agents can call the tool directly:

Choose a Mount

Next Steps

Read-only Mounts

Choose between following the file system and pinning a permanent snapshot.

File System Mounts

Give agents a separate place to write outputs.