Tensorlake Documentation

A file system is a project-scoped, persistent file system you create once and mount into any number of sandboxes at an absolute path. Unlike a sandbox’s own file system, which is ephemeral and disappears when the sandbox is terminated, it lives independently of any sandbox’s lifecycle, so its contents persist across runs and are visible to every sandbox that mounts it. Use file systems to:

Share a common dataset, model, or cache across a fleet of sandboxes.
Keep working state (skills, checkpoints, outputs) around after a sandbox is gone.
Hand data between sandboxes without copying it through your machine.

A file system is distinct from a sandbox’s local ephemeral disk (see File Operations) and from Snapshots, which capture a point-in-time copy of one sandbox.

How it works

Create

Create a file system in your project. You get back an id of the form file_system_....

Mount

Mount it into a sandbox at an absolute, unique path — either at boot when you create the sandbox, or on a running sandbox.

Share and persist

Reads and writes under the mount path go to the file system. Mount the same file system into other sandboxes to share its contents; the data remains after each sandbox is terminated.

Create a File System

CLI
Python
TypeScript

tl fs create --name skills --description "Skills shared across sandboxes"

from tensorlake import create_file_system

fs = create_file_system("skills", description="Skills shared across sandboxes")
print(fs.id, fs.status)  # e.g. file_system_bKtRcMWrzcRTRGfmMhgDc ready

import { createFileSystem } from "tensorlake";

const fs = await createFileSystem("skills", "Skills shared across sandboxes");
console.log(fs.id, fs.status);

List File Systems

CLI
Python
TypeScript

tl fs ls

from tensorlake import list_file_systems

for fs in list_file_systems():
    print(fs.id, fs.name, fs.region, fs.status)

import { listFileSystems } from "tensorlake";

for (const fs of await listFileSystems()) {
  console.log(fs.id, fs.name, fs.region, fs.status);
}

Delete a File System

CLI
Python
TypeScript

tl fs rm file_system_bKtRcMWrzcRTRGfmMhgDc

from tensorlake import delete_file_system

delete_file_system("file_system_bKtRcMWrzcRTRGfmMhgDc")

import { deleteFileSystem } from "tensorlake";

await deleteFileSystem("file_system_bKtRcMWrzcRTRGfmMhgDc");

Mount at Boot

Mount one or more file systems when you create a sandbox. Each mount needs the file system id and an absolute, unique path inside the sandbox.

CLI
Python
TypeScript
HTTP

# Repeat -f / --filesystem to mount more than one
tl sbx create \
  --filesystem file_system_bKtRcMWrzcRTRGfmMhgDc:/mnt/skills

from tensorlake.sandbox import Sandbox, FileSystemMount

sandbox = Sandbox.create(
    file_systems=[
        FileSystemMount(
            file_system_id="file_system_bKtRcMWrzcRTRGfmMhgDc",
            mount_path="/mnt/skills",
        )
    ],
)

# The mounted file system is now readable and writable at /mnt/skills
sandbox.write_file("/mnt/skills/notes.txt", b"persisted across sandboxes")

import { Sandbox } from "tensorlake";

const sandbox = await Sandbox.create({
  fileSystems: [
    {
      fileSystemId: "file_system_bKtRcMWrzcRTRGfmMhgDc",
      mountPath: "/mnt/skills",
    },
  ],
});

await sandbox.writeFile(
  "/mnt/skills/notes.txt",
  new TextEncoder().encode("persisted across sandboxes"),
);

curl -X POST https://api.tensorlake.ai/sandboxes \
  -H "Authorization: Bearer $TL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "file_systems": [
      {"file_system_id": "file_system_bKtRcMWrzcRTRGfmMhgDc", "mount_path": "/mnt/skills"}
    ]
  }'

Attach and Detach on a Running Sandbox

Mount or unmount a file system on a sandbox that is already running. The mount/unmount completes asynchronously; the returned sandbox info reflects the updated mounts.

CLI
Python
TypeScript
HTTP

tl sbx fs attach <sandbox-id> \
  --id file_system_bKtRcMWrzcRTRGfmMhgDc \
  --path /mnt/skills

tl sbx fs detach <sandbox-id> --path /mnt/skills

sandbox.attach_file_system(
    "file_system_bKtRcMWrzcRTRGfmMhgDc", "/mnt/skills"
)

sandbox.detach_file_system("/mnt/skills")

await sandbox.attachFileSystem(
  "file_system_bKtRcMWrzcRTRGfmMhgDc",
  "/mnt/skills",
);

await sandbox.detachFileSystem("/mnt/skills");

# Attach
curl -X POST https://api.tensorlake.ai/sandboxes/<sandbox-id>/file_systems \
  -H "Authorization: Bearer $TL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"file_system_id": "file_system_bKtRcMWrzcRTRGfmMhgDc", "mount_path": "/mnt/skills"}'

# Detach
curl -X DELETE https://api.tensorlake.ai/sandboxes/<sandbox-id>/file_systems \
  -H "Authorization: Bearer $TL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"mount_path": "/mnt/skills"}'

List Mounts on a Sandbox

CLI
Python
TypeScript
HTTP

tl sbx fs ls <sandbox-id>

for mount in sandbox.list_file_systems():
    print(mount.file_system_id, "->", mount.mount_path)

for (const mount of await sandbox.listFileSystems()) {
  console.log(mount.fileSystemId, "->", mount.mountPath);
}

# Mounts are reported under "file_systems" on the sandbox
curl https://api.tensorlake.ai/sandboxes/<sandbox-id> \
  -H "Authorization: Bearer $TL_API_KEY"

Because a file system is independent of any single sandbox, mounting the same one into multiple sandboxes gives them a common, persistent workspace.

from tensorlake import create_file_system
from tensorlake.sandbox import Sandbox, FileSystemMount

fs = create_file_system("dataset")
mounts = [FileSystemMount(file_system_id=fs.id, mount_path="/data")]

# Producer writes to the file system
producer = Sandbox.create(file_systems=mounts)
producer.write_file("/data/input.csv", b"id,value\n1,42\n")
producer.terminate()

# A later, separate sandbox reads the same data — it survived the producer
consumer = Sandbox.create(file_systems=mounts)
print(bytes(consumer.read_file("/data/input.csv")).decode())

Best Practices

Use absolute, unique mount paths (for example /mnt/skills, /data); two mounts on the same sandbox cannot share a path.
Keep large, reusable assets (datasets, model weights, caches) on a file system instead of rebaking them into every Sandbox Image.
Treat the file system id (file_system_...) as the stable handle; mount paths are per-sandbox.

Learn More

File Operations

Read, write, and copy files on a sandbox’s local filesystem.

Snapshots

Capture and restore a single sandbox’s filesystem, memory, and processes.

Skills in Sandboxes

Pre-load skill files so coding agents discover them at startup.

​How it works

​Create a File System

​List File Systems

​Delete a File System

​Mount at Boot

​Attach and Detach on a Running Sandbox

​List Mounts on a Sandbox

​Share Data Across Sandboxes

​Best Practices

​Learn More

File Operations

Snapshots

Skills in Sandboxes

How it works

Create a File System

List File Systems

Delete a File System

Mount at Boot

Attach and Detach on a Running Sandbox

List Mounts on a Sandbox

Share Data Across Sandboxes

Best Practices

Learn More