> ## 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.

# File Systems

> Register project-scoped file systems and mount them into one or many sandboxes at an absolute path — persistent, reusable storage that outlives any single sandbox.

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.

<Note>
  A file system is distinct from a sandbox's local ephemeral disk (see [File Operations](/sandboxes/file-operations)) and from [Snapshots](/sandboxes/snapshots), which capture a point-in-time copy of one sandbox.
</Note>

## How it works

<Steps>
  <Step title="Create">
    [Create a file system](#create-a-file-system) in your project. You get back an id of the form `file_system_...`.
  </Step>

  <Step title="Mount">
    [Mount it into a sandbox](#mount-at-boot) at an absolute, unique path — either at boot when you create the sandbox, or [on a running sandbox](#attach-and-detach-on-a-running-sandbox).
  </Step>

  <Step title="Share and persist">
    Reads and writes under the mount path go to the file system. [Mount the same file system into other sandboxes](#share-data-across-sandboxes) to share its contents; the data remains after each sandbox is terminated.
  </Step>
</Steps>

## Create a File System

<Tabs>
  <Tab title="CLI">
    ```bash theme={null}
    tl fs create --name skills --description "Skills shared across sandboxes"
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    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
    ```
  </Tab>

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

    const fs = await createFileSystem("skills", "Skills shared across sandboxes");
    console.log(fs.id, fs.status);
    ```
  </Tab>
</Tabs>

## List File Systems

<Tabs>
  <Tab title="CLI">
    ```bash theme={null}
    tl fs ls
    ```
  </Tab>

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

    for fs in list_file_systems():
        print(fs.id, fs.name, fs.region, fs.status)
    ```
  </Tab>

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

    for (const fs of await listFileSystems()) {
      console.log(fs.id, fs.name, fs.region, fs.status);
    }
    ```
  </Tab>
</Tabs>

## Delete a File System

<Tabs>
  <Tab title="CLI">
    ```bash theme={null}
    tl fs rm file_system_bKtRcMWrzcRTRGfmMhgDc
    ```
  </Tab>

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

    delete_file_system("file_system_bKtRcMWrzcRTRGfmMhgDc")
    ```
  </Tab>

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

    await deleteFileSystem("file_system_bKtRcMWrzcRTRGfmMhgDc");
    ```
  </Tab>
</Tabs>

## 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.

<Tabs>
  <Tab title="CLI">
    ```bash theme={null}
    # Repeat -f / --filesystem to mount more than one
    tl sbx create \
      --filesystem file_system_bKtRcMWrzcRTRGfmMhgDc:/mnt/skills
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    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")
    ```
  </Tab>

  <Tab title="TypeScript">
    ```typescript theme={null}
    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"),
    );
    ```
  </Tab>

  <Tab title="HTTP">
    ```bash theme={null}
    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"}
        ]
      }'
    ```
  </Tab>
</Tabs>

## 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.

<Tabs>
  <Tab title="CLI">
    ```bash theme={null}
    tl sbx fs attach <sandbox-id> \
      --id file_system_bKtRcMWrzcRTRGfmMhgDc \
      --path /mnt/skills

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

  <Tab title="Python">
    ```python theme={null}
    sandbox.attach_file_system(
        "file_system_bKtRcMWrzcRTRGfmMhgDc", "/mnt/skills"
    )

    sandbox.detach_file_system("/mnt/skills")
    ```
  </Tab>

  <Tab title="TypeScript">
    ```typescript theme={null}
    await sandbox.attachFileSystem(
      "file_system_bKtRcMWrzcRTRGfmMhgDc",
      "/mnt/skills",
    );

    await sandbox.detachFileSystem("/mnt/skills");
    ```
  </Tab>

  <Tab title="HTTP">
    ```bash theme={null}
    # 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"}'
    ```
  </Tab>
</Tabs>

## List Mounts on a Sandbox

<Tabs>
  <Tab title="CLI">
    ```bash theme={null}
    tl sbx fs ls <sandbox-id>
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    for mount in sandbox.list_file_systems():
        print(mount.file_system_id, "->", mount.mount_path)
    ```
  </Tab>

  <Tab title="TypeScript">
    ```typescript theme={null}
    for (const mount of await sandbox.listFileSystems()) {
      console.log(mount.fileSystemId, "->", mount.mountPath);
    }
    ```
  </Tab>

  <Tab title="HTTP">
    ```bash theme={null}
    # Mounts are reported under "file_systems" on the sandbox
    curl https://api.tensorlake.ai/sandboxes/<sandbox-id> \
      -H "Authorization: Bearer $TL_API_KEY"
    ```
  </Tab>
</Tabs>

## Share Data Across Sandboxes

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

```python theme={null}
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](/sandboxes/images).
* Treat the file system id (`file_system_...`) as the stable handle; mount paths are per-sandbox.

## Learn More

<CardGroup cols={3}>
  <Card title="File Operations" icon="folder-open" href="/sandboxes/file-operations">
    Read, write, and copy files on a sandbox's local filesystem.
  </Card>

  <Card title="Snapshots" icon="camera" href="/sandboxes/snapshots">
    Capture and restore a single sandbox's filesystem, memory, and processes.
  </Card>

  <Card title="Skills in Sandboxes" icon="wand-magic-sparkles" href="/sandboxes/skills-in-sandboxes">
    Pre-load skill files so coding agents discover them at startup.
  </Card>
</CardGroup>