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

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. Set up your SDK or the CLI 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.

TypeScript
Python
Go
CLI

Run the following code, which waits until the volume is ready:

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);

Run the following code, which waits until the volume is ready:

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)

Run the following code, which waits until the volume is ready:

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)
}

Run the following command to create a 10 GiB volume named data:

baseten sandbox volume create --name data --size 10Gi

Run the following command to check the volume’s status and region:
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.

TypeScript
Python
Go
CLI

Run the following code with the same client:

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.

Add SandboxVolumeMount to the baseten.sandbox import, then run the following code inside the same with block:

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.

Run the following code with the same client:

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.

Replace <VOLUME_REGION> with the region from describe, then run the following command:

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:

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:

TypeScript
Python
Go
CLI

Run the following code:

const grown = await client.volumes.update({ name: "data", size: "20Gi" });
console.log(grown.size);

Run the following code:

volume = client.volumes.update(name="data", size="20Gi")
print(volume.size)

Run the following code:

volume, err = client.Volumes().Update(ctx, sandbox.VolumeUpdateOptions{
    Name: "data",
    Size: "20Gi",
})
if err != nil {
    log.Fatal(err)
}
fmt.Println(volume.Size)

Run the following command:

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.

TypeScript
Python
Go
CLI

Run the following code:

const deleted = await client.volumes.delete({ name: "data" });
console.log(deleted.status);

Run the following code:

volume = client.volumes.delete(name="data")
print(volume.status)

Run the following code:

volume, err = client.Volumes().Delete(ctx, sandbox.VolumeDeleteOptions{Name: "data"})
if err != nil {
    log.Fatal(err)
}
fmt.Println(volume.Status)

Run the following command and confirm when prompted:

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, Create a sandbox volume, and Sandbox lifecycle and expiration.

Get started

Model APIs

Baseten Grid

Inference

Frontier Gateway

Training

Sandboxes

Development

Deployment

Engines

Model Labs

Organization

Hosting options

Observability

Troubleshooting

Sandbox volumes

Create a volume

Mount a volume

Grow a volume

Delete a volume

​Create a volume

​Mount a volume

​Grow a volume

​Delete a volume

Create a volume

Mount a volume

Grow a volume

Delete a volume