> ## Documentation Index
> Fetch the complete documentation index at: https://docs.baseten.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Sandbox volumes

> Keep files across sandboxes by creating, mounting, growing, and deleting persistent volumes.

Baseten Sandboxes are now available and free to use until November 16. Each organization can run up to 10 sandboxes at once. To raise this limit, [contact support](mailto:support@baseten.co).

A sandbox volume is a persistent disk that keeps its files after the sandboxes
that mount it are deleted or expire. Mount one when a later sandbox needs the
same data, such as a dataset, a model cache, or a project checkout.

A volume belongs to one region. Only sandboxes in that region can mount it, one
sandbox at a time. A volume can grow but never shrink. Without a volume, a
sandbox's files are deleted with it; see
[Local data](https://docs.baseten.co/sandboxes/lifecycle.md#local-data).

[Set up your SDK or the CLI](https://docs.baseten.co/sandboxes/manage.md#set-up) before running these
examples.

## Create a volume

**To create a volume**:

Creation returns before the volume is ready. The volume is ready when its
status is `DEPLOYED`, and its region is the one to use when you mount it.

> [tab] TypeScript
>
> Run the following code, which waits until the volume is ready:
>
> ```typescript theme={"system"}
> import { SandboxClient } from "@basetenlabs/sandbox";
>
> const client = new SandboxClient({ apiKey: process.env.BASETEN_API_KEY! });
> let volume = await client.volumes.create({ name: "data", size: "10Gi" });
> while (volume.status === "DEPLOYING") {
>   await new Promise((resolve) => setTimeout(resolve, 2000));
>   volume = await client.volumes.getInfo({ name: "data" });
> }
> console.log(volume.status, volume.region);
> ```

> [tab] Python
>
> Run the following code, which waits until the volume is ready:
>
> ```python theme={"system"}
> import os
> import time
>
> from baseten.sandbox import SandboxClient
>
> with SandboxClient(api_key=os.environ["BASETEN_API_KEY"]) as client:
>     volume = client.volumes.create(name="data", size="10Gi")
>     while volume.status == "DEPLOYING":
>         time.sleep(2)
>         volume = client.volumes.get_info(name="data")
>     print(volume.status, volume.region)
> ```

> [tab] Go
>
> Run the following code, which waits until the volume is ready:
>
> ```go theme={"system"}
> package main
>
> import (
>     "context"
>     "fmt"
>     "log"
>     "os"
>     "time"
>
>     "github.com/basetenlabs/baseten-go/sandbox"
> )
>
> func main() {
>     ctx := context.Background()
>     client, err := sandbox.NewClient(sandbox.ClientOptions{
>         APIKey: os.Getenv("BASETEN_API_KEY"),
>     })
>     if err != nil {
>         log.Fatal(err)
>     }
>     volume, err := client.Volumes().Create(ctx, sandbox.VolumeCreateOptions{
>         Name: "data",
>         Size: "10Gi",
>     })
>     if err != nil {
>         log.Fatal(err)
>     }
>     for volume.Status == sandbox.VolumeStatusDeploying {
>         time.Sleep(2 * time.Second)
>         volume, err = client.Volumes().GetInfo(ctx, sandbox.VolumeGetInfoOptions{Name: "data"})
>         if err != nil {
>             log.Fatal(err)
>         }
>     }
>     fmt.Println(volume.Status, volume.Region)
> }
> ```

> [tab] CLI
>
> 1. Run the following command to create a 10 GiB volume named `data`:
>
>    ```bash theme={"system"}
>    baseten sandbox volume create --name data --size 10Gi
>    ```
>
> 2. Run the following command to check the volume's status and region:
>
>    ```bash theme={"system"}
>    baseten sandbox volume describe --name data
>    ```

## Mount a volume

**To mount a volume in a new sandbox**:

Create a sandbox in the volume's region with the volume mounted at `/data`.

> [tab] TypeScript
>
> Run the following code with the same client:
>
> ```typescript theme={"system"}
> const sandbox = await client.create({
>   name: "hello-world",
>   region: volume.region,
>   volumes: [{ name: "data", mountPath: "/data" }],
> });
> console.log(sandbox.name);
> ```
>
> To mount it read-only, add `readOnly: true` to the mount.

> [tab] Python
>
> Add `SandboxVolumeMount` to the `baseten.sandbox` import, then run the
> following code inside the same `with` block:
>
> ```python theme={"system"}
> sandbox = client.create(
>     name="hello-world",
>     region=volume.region,
>     volumes=[SandboxVolumeMount(name="data", mount_path="/data")],
> )
> print(sandbox.name)
> ```
>
> To mount it read-only, pass `read_only=True` to `SandboxVolumeMount`.

> [tab] Go
>
> Run the following code with the same client:
>
> ```go theme={"system"}
> sb, err := client.Create(ctx, sandbox.CreateOptions{
>     Name:    "hello-world",
>     Region:  volume.Region,
>     Volumes: []sandbox.VolumeMount{{Name: "data", MountPath: "/data"}},
> })
> if err != nil {
>     log.Fatal(err)
> }
> fmt.Println(sb.Name())
> ```
>
> To mount it read-only, set `ReadOnly: true` on the `VolumeMount`.

> [tab] CLI
>
> Replace `<VOLUME_REGION>` with the region from `describe`, then run the
> following command:
>
> ```bash theme={"system"}
> baseten sandbox create --name hello-world --region <VOLUME_REGION> --volume data:/data
> ```
>
> To mount it read-only, append `:ro` to the mount, such as `data:/data:ro`.

**To confirm the mount**:

Run the following command to check the file system mounted at `/data`:

```bash theme={"system"}
baseten sandbox exec --name hello-world -- df -h /data
```

The output shows the volume's size and usage. Files that the sandbox writes
under `/data` stay on the volume after you delete the sandbox.

## Grow a volume

**To grow a volume to 20 GiB**:

> [tab] TypeScript
>
> Run the following code:
>
> ```typescript theme={"system"}
> const grown = await client.volumes.update({ name: "data", size: "20Gi" });
> console.log(grown.size);
> ```

> [tab] Python
>
> Run the following code:
>
> ```python theme={"system"}
> volume = client.volumes.update(name="data", size="20Gi")
> print(volume.size)
> ```

> [tab] Go
>
> Run the following code:
>
> ```go theme={"system"}
> volume, err = client.Volumes().Update(ctx, sandbox.VolumeUpdateOptions{
>     Name: "data",
>     Size: "20Gi",
> })
> if err != nil {
>     log.Fatal(err)
> }
> fmt.Println(volume.Size)
> ```

> [tab] CLI
>
> Run the following command:
>
> ```bash theme={"system"}
> baseten sandbox volume update --name data --size 20Gi
> ```

## Delete a volume

**To delete a volume and its files**:

First delete the sandboxes that mount the volume.

> [tab] TypeScript
>
> Run the following code:
>
> ```typescript theme={"system"}
> const deleted = await client.volumes.delete({ name: "data" });
> console.log(deleted.status);
> ```

> [tab] Python
>
> Run the following code:
>
> ```python theme={"system"}
> volume = client.volumes.delete(name="data")
> print(volume.status)
> ```

> [tab] Go
>
> Run the following code:
>
> ```go theme={"system"}
> volume, err = client.Volumes().Delete(ctx, sandbox.VolumeDeleteOptions{Name: "data"})
> if err != nil {
>     log.Fatal(err)
> }
> fmt.Println(volume.Status)
> ```

> [tab] CLI
>
> Run the following command and confirm when prompted:
>
> ```bash theme={"system"}
> baseten sandbox volume delete --name data
> ```
>
> Pass `--yes` to skip the prompt when scripting.

The sandbox volume CLI commands are pre-release, so their flags and output may
change.

For more information, see
[`baseten sandbox volume`](https://docs.baseten.co/reference/cli/baseten/sandbox#volume),
[Create a sandbox volume](https://docs.baseten.co/reference/management-api/sandboxes/create-a-sandbox-volume.md),
and [Sandbox lifecycle and expiration](https://docs.baseten.co/sandboxes/lifecycle.md).