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

> Copy, read, write, and manage files inside Tensorlake sandboxes — transfer between your local machine and the sandbox filesystem over the proxy URL.

<Note>
  File operations use the sandbox proxy URL: `https://<sandbox-id-or-name>.sandbox.tensorlake.ai`

  Named sandboxes can use the sandbox name in place of the ID in the proxy hostname. The file APIs documented here run on the management URL on port `9501`, which always requires authentication. Unauthenticated proxy access applies only to exposed user ports.
</Note>

## Copy Files

<Tabs>
  <Tab title="CLI">
    ```bash theme={null}
    # Copy a local file into the sandbox
    tl sbx cp data.csv <sandbox-id>:/workspace/data.csv

    # Copy a file from the sandbox to local
    tl sbx cp <sandbox-id>:/workspace/data.csv ./data.csv
    ```
  </Tab>

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

    sandbox = Sandbox.create()

    sandbox.write_file("/workspace/data.csv", b"name,score\nAlice,95\nBob,87")

    content = sandbox.read_file("/workspace/data.csv")
    print(bytes(content).decode("utf-8"))
    ```
  </Tab>

  <Tab title="TypeScript">
    ```typescript theme={null}
    await sandbox.writeFile(
      "/workspace/data.csv",
      new TextEncoder().encode("name,score\nAlice,95\nBob,87"),
    );

    const content = await sandbox.readFile("/workspace/data.csv");
    console.log(new TextDecoder().decode(content));
    ```
  </Tab>

  <Tab title="HTTP">
    ```bash theme={null}
    curl -X PUT "https://<sandbox-id>.sandbox.tensorlake.ai/api/v1/files?path=/workspace/data.csv" \
      -H "Authorization: Bearer $TL_API_KEY" \
      -H "Content-Type: application/octet-stream" \
      --data-binary "name,score\nAlice,95\nBob,87"

    curl "https://<sandbox-id>.sandbox.tensorlake.ai/api/v1/files?path=/workspace/data.csv" \
      -H "Authorization: Bearer $TL_API_KEY"
    ```
  </Tab>
</Tabs>

`tl sbx cp` is file-only today. Directory copy workflows should use the Python SDK, TypeScript SDK, or the raw file API.

## Read Files

<Tabs>
  <Tab title="CLI">
    ```bash theme={null}
    tl sbx cp <sandbox-id>:/workspace/data.csv ./data.csv
    tl sbx exec <sandbox-id> cat /workspace/data.csv
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    content = sandbox.read_file("/workspace/data.csv")
    print(bytes(content).decode("utf-8"))

    image_bytes = sandbox.read_file("/workspace/chart.png")
    with open("chart.png", "wb") as f:
        f.write(image_bytes)
    ```
  </Tab>

  <Tab title="TypeScript">
    ```typescript theme={null}
    const content = await sandbox.readFile("/workspace/data.csv");
    console.log(new TextDecoder().decode(content));

    const bytes = await sandbox.readFile("/workspace/chart.png");
    console.log(`Read ${bytes.byteLength} bytes`);
    ```
  </Tab>

  <Tab title="HTTP">
    ```bash theme={null}
    curl "https://<sandbox-id>.sandbox.tensorlake.ai/api/v1/files?path=/workspace/data.csv" \
      -H "Authorization: Bearer $TL_API_KEY"

    curl "https://<sandbox-id>.sandbox.tensorlake.ai/api/v1/files?path=/workspace/chart.png" \
      -H "Authorization: Bearer $TL_API_KEY" \
      -o chart.png
    ```
  </Tab>
</Tabs>

## Write Files

<Tabs>
  <Tab title="CLI">
    ```bash theme={null}
    tl sbx cp config.json <sandbox-id>:/workspace/config.json
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    sandbox.write_file("/workspace/config.json", b'{"debug": true, "port": 8080}')

    with open("model.pkl", "rb") as f:
        sandbox.write_file("/workspace/model.pkl", f.read())
    ```
  </Tab>

  <Tab title="TypeScript">
    ```typescript theme={null}
    import { readFile } from "node:fs/promises";

    await sandbox.writeFile(
      "/workspace/config.json",
      new TextEncoder().encode('{"debug": true, "port": 8080}'),
    );

    const modelBytes = await readFile("model.pkl");
    await sandbox.writeFile("/workspace/model.pkl", modelBytes);
    ```
  </Tab>

  <Tab title="HTTP">
    ```bash theme={null}
    curl -X PUT "https://<sandbox-id>.sandbox.tensorlake.ai/api/v1/files?path=/workspace/config.json" \
      -H "Authorization: Bearer $TL_API_KEY" \
      -H "Content-Type: application/octet-stream" \
      --data-binary '{"debug": true, "port": 8080}'

    curl -X PUT "https://<sandbox-id>.sandbox.tensorlake.ai/api/v1/files?path=/workspace/model.pkl" \
      -H "Authorization: Bearer $TL_API_KEY" \
      -H "Content-Type: application/octet-stream" \
      --data-binary @model.pkl
    ```
  </Tab>
</Tabs>

## List Directory Contents

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

  <Tab title="Python">
    ```python theme={null}
    entries = sandbox.list_directory("/workspace")
    for entry in entries.entries:
        print(f"{entry.name} ({entry.size} bytes)")
    ```
  </Tab>

  <Tab title="TypeScript">
    ```typescript theme={null}
    const listing = await sandbox.listDirectory("/workspace");
    for (const entry of listing.entries) {
      console.log(`${entry.name} (${entry.size ?? 0} bytes)`);
    }
    ```
  </Tab>

  <Tab title="HTTP">
    ```bash theme={null}
    curl "https://<sandbox-id>.sandbox.tensorlake.ai/api/v1/files/list?path=/workspace" \
      -H "Authorization: Bearer $TL_API_KEY"
    ```
  </Tab>
</Tabs>

## Delete Files

<Tabs>
  <Tab title="CLI">
    ```bash theme={null}
    tl sbx exec <sandbox-id> rm -rf /workspace/temp
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    sandbox.delete_file("/workspace/temp")
    ```
  </Tab>

  <Tab title="TypeScript">
    ```typescript theme={null}
    await sandbox.deleteFile("/workspace/temp");
    ```
  </Tab>

  <Tab title="HTTP">
    ```bash theme={null}
    curl -X DELETE "https://<sandbox-id>.sandbox.tensorlake.ai/api/v1/files?path=/workspace/temp" \
      -H "Authorization: Bearer $TL_API_KEY"
    ```
  </Tab>
</Tabs>

## Organize Files

<Tabs>
  <Tab title="CLI">
    ```bash theme={null}
    tl sbx exec <sandbox-id> mkdir -p /workspace/src/components
    tl sbx exec <sandbox-id> mv /workspace/old.txt /workspace/new.txt
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    sandbox.run("mkdir", ["-p", "/workspace/src/components"])
    sandbox.run("mv", ["/workspace/old.txt", "/workspace/new.txt"])
    ```
  </Tab>

  <Tab title="TypeScript">
    ```typescript theme={null}
    await sandbox.run("mkdir", {
      args: ["-p", "/workspace/src/components"],
    });
    await sandbox.run("mv", {
      args: ["/workspace/old.txt", "/workspace/new.txt"],
    });
    ```
  </Tab>

  <Tab title="HTTP">
    Not supported in the HTTP API.
  </Tab>
</Tabs>

## Best Practices

* Use `/workspace` as the default directory for application files.
* Use absolute paths to avoid ambiguity.
* Use `write_file` / `read_file` for programmatic access.
* Use `tl sbx cp` for single-file transfers.
* Use the Python SDK, TypeScript SDK, or raw file API for directory-oriented workflows.

## Learn More

<CardGroup cols={3}>
  <Card title="Commands" icon="terminal" href="/sandboxes/commands">
    Execute commands in sandboxes.
  </Card>

  <Card title="Snapshots" icon="camera" href="/sandboxes/snapshots">
    Save and restore sandbox filesystem, memory, and running processes.
  </Card>

  <Card title="Lifecycle" icon="arrows-spin" href="/sandboxes/lifecycle">
    Sandbox states, resources, and timeouts.
  </Card>
</CardGroup>