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

CLI

$ tl fs create agent-assets
Created filesystem agent-assets (empty).

Python

from tensorlake.filesystem import FilesystemClient

client = FilesystemClient()
fs = client.create("agent-assets")

TypeScript

import { FilesystemClient } from "tensorlake";

const client = new FilesystemClient();
const fs = await client.create("agent-assets");

Keep the layout simple and stable:

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:

$ 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):

CLI

tl sbx create -f agent-assets:/opt/agent-assets:ro

Python

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,
        ),
    ],
)

TypeScript

import { Sandbox } from "tensorlake";

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

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:

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 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:

from tensorlake.filesystem import FilesystemClient

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

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 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:

chmod +x agent-assets/bin/validator
tl fs push ./agent-assets agent-assets -m "add validator tool"

Agents can call the tool directly:

/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

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.