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

# Sandboxes Quickstart

> Install the SDK, authenticate, and run your first sandbox in under five minutes.

## Setup

<Tabs>
  <Tab title="CLI">
    <Steps>
      <Step title="Install the Tensorlake CLI">
        ```bash theme={null}
        curl -fsSL https://tensorlake.ai/install | sh
        ```

        This installs the `tl` and `tensorlake` CLIs, which you can use to manage sandboxes and other resources from the command line.
      </Step>

      <Step title="Authenticate">
        ```bash theme={null}
        tl login
        ```
      </Step>
    </Steps>
  </Tab>

  <Tab title="Python">
    <Steps>
      <Step title="Install the Tensorlake package">
        ```bash theme={null}
        pip install tensorlake
        ```

        This installs the Python SDK. It also ships the `tl` and `tensorlake` CLIs in your Python toolchain's `bin` directory.
      </Step>

      <Step title="Set your API key">
        Get an API key from the [Tensorlake Dashboard](https://cloud.tensorlake.ai) and set it in your environment:

        ```bash theme={null}
        export TENSORLAKE_API_KEY=your-api-key-here
        ```
      </Step>
    </Steps>
  </Tab>

  <Tab title="TypeScript">
    <Steps>
      <Step title="Install the TypeScript SDK">
        ```bash theme={null}
        npm install tensorlake
        ```

        This installs the TypeScript SDK. It also ships the `tl` and `tensorlake` CLIs in your Node toolchain's `bin` directory.
      </Step>

      <Step title="Set your API key">
        Get an API key from the [Tensorlake Dashboard](https://cloud.tensorlake.ai) and set it in your environment:

        ```bash theme={null}
        export TENSORLAKE_API_KEY=your-api-key-here
        ```
      </Step>
    </Steps>
  </Tab>
</Tabs>

After you run `tl login`, you can manage your sandboxes in the [Tensorlake Dashboard](https://cloud.tensorlake.ai). You can also create API keys there for sandbox connections. See [Authentication](/platform/authentication#api-keys) for the full API key setup flow.

## Run your first sandbox

Create a tiny sandbox for a quick task, or provision one with more CPU and memory for heavier workloads.

<Tabs>
  <Tab title="CLI">
    ```bash theme={null}
    # Create an ephemeral sandbox (no name — terminates when done, cannot be suspended)
    tl sbx create

    # Run code inside the sandbox
    tl sbx exec <sandbox-id> python -c 'print("Hello from sandbox")'

    # Copy files in or out as the sandbox accumulates state
    tl sbx cp local-file.txt <sandbox-id>:/workspace/local-file.txt
    ```
  </Tab>

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


    # Ephemeral sandbox — no name, terminates when done, cannot be suspended
    sandbox = Sandbox.create()

    # Run code inside the sandbox
    result = sandbox.run("python", ["-c", "print('Hello from sandbox')"])
    print(result.stdout)

    # Copy files in or out as the sandbox accumulates state
    sandbox.write_file("/workspace/local-file.txt", b"example content")
    file_bytes = bytes(sandbox.read_file("/workspace/local-file.txt"))
    print(file_bytes.decode("utf-8"))
    ```
  </Tab>

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


    // Ephemeral sandbox — no name, terminates when done, cannot be suspended
    const sandbox = await Sandbox.create();
    console.log(sandbox.sandboxId, sandbox.status);

    for (const sb of await Sandbox.list()) {
      console.log(sb.sandboxId, sb.status);
    }

    // Run code inside the sandbox
    const result = await sandbox.run("python", {
      args: ["-c", "print('Hello from sandbox')"],
    });
    console.log(result.stdout);

    // Copy files in or out as the sandbox accumulates state
    await sandbox.writeFile(
      "/workspace/local-file.txt",
      new TextEncoder().encode("example content"),
    );
    const fileBytes = await sandbox.readFile("/workspace/local-file.txt");
    console.log(new TextDecoder().decode(fileBytes));
    ```
  </Tab>
</Tabs>

#### Configure CPU, Memory, Disk, and Timeout

You can specify CPU, memory, disk, and timeout parameters when creating sandboxes. The defaults are 1 CPU, 1024 MB memory, 10 GB disk, and 600 seconds timeout.

<Tabs>
  <Tab title="CLI">
    ```bash theme={null}
    tl sbx create --cpus 2.0 --memory 2048 --disk_mb 51200 --timeout 600
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    sandbox = Sandbox.create(cpus=2.0, memory_mb=2048, disk_mb=12000, timeout_secs=600)
    ```
  </Tab>

  <Tab title="TypeScript">
    ```typescript theme={null}
    const sandbox = await Sandbox.create({
      cpus: 2.0,
      memoryMb: 2048,
      diskMb: 12000,
      timeoutSecs: 600,
    });
    ```
  </Tab>
</Tabs>

#### Suspend and Resume

Tensorlake sandboxes can be suspended and resumed. A resumed sandbox continues from the exact memory and file system state, it was suspended.
This is useful when you want to preserve the sandbox state without paying for idle compute time.

You have to name a sandbox to make them suspendable after timeout. Sandboxes without a name are ephemeral and thrown away after the timeout.

<CodeGroup>
  ```bash cli theme={null}
    tl sbx suspend <sandbox-name>
    tl sbx resume <sandbox-name>
  ```

  ```python sandbox.py theme={null}
    sandbox = Sandbox.create(name="my-agent-env", cpus=2.0, memory_mb=2048)

    sandbox.suspend()
    sandbox.resume()
  ```

  ```typescript sandbox.ts theme={null}
    const sandbox = await Sandbox.create({
      name: "my-agent-env",
      cpus: 2.0,
      memoryMb: 2048,
      timeoutSecs: 600,
    });

    await sandbox.suspend();
    await sandbox.resume();
  ```
</CodeGroup>

#### Sandbox Checkpoints

Checkpoints are point in time snapshot of a sandbox that you can use to start new sandboxes from.

<CodeGroup>
  ```bash cli theme={null}
    tl sbx checkpoint <sandbox-id>
  ```

  ```python sandbox.py theme={null}
    # Save a checkpoint you can return to later
    snapshot = sandbox.checkpoint()
    print(snapshot.snapshot_id)
  ```

  ```typescript sandbox.ts theme={null}
    const snapshot = await sandbox.checkpoint();
    console.log(snapshot.snapshotId);
  ```
</CodeGroup>

#### Terminate Sandboxes

<CodeGroup>
  ```bash cli theme={null}
    tl sbx terminate <sandbox-id>
  ```

  ```python sandbox.py theme={null}
    sandbox.terminate()
  ```

  ```typescript sandbox.ts theme={null}
    await sandbox.terminate();
  ```
</CodeGroup>

## SSH Access

You can also SSH into your sandboxes for an interactive terminal experience.

```bash theme={null}
tl sbx ssh <sandbox-id>
```

This uses a websocket based PTY session to connect you to the sandbox.

For programmatic access, you can create and control PTY session with the [Python and TypeScript SDKs](/sandboxes/pty-sessions).

## Next Steps

<CardGroup cols={2}>
  <Card title="Lifecycle" icon="recycle" href="/sandboxes/lifecycle">
    Understand the different states and behaviors of sandboxes.
  </Card>

  <Card title="Commands" icon="lightbulb" href="/sandboxes/commands">
    Run shell commands and stream output.
  </Card>

  <Card title="Sandbox Images" icon="image" href="/sandboxes/images">
    Use and customize sandbox images for your use case.
  </Card>
</CardGroup>