Manage sandboxes

Create sandboxes with the TypeScript, Python, or Go SDK, the Baseten CLI, or the dashboard, and inspect, update, and delete them.

Create a sandbox for an agent’s task, wait for it to deploy, and delete it when the work finishes. Use a Baseten SDK to manage sandboxes from your application. Each SDK creates and refreshes sandbox access tokens for you. Use the Baseten CLI or the dashboard to inspect and troubleshoot sandboxes by hand.

You need permission to create resources in your team.

Set up

Install the CLI or an SDK:

TypeScript

npm install @basetenlabs/sandbox undici

Python

pip install baseten "httpx[http2]"

Go

go get github.com/basetenlabs/baseten-go/sandbox

CLI

baseten auth login

The CLI examples use $SANDBOX_NAME for the sandbox name:

export SANDBOX_NAME="hello-world"

Sandbox commands are in pre-release. Arguments, flags, and output may change.

Create a sandbox

Creating a sandbox starts an isolated environment from an image. The new sandbox gets a name, an image, memory (which also sets its CPU allocation), and a region. Name, image, memory, and region can’t change after creation.

An organization can run up to 10 sandboxes at once. To raise this quota, contact Baseten support with your organization ID.

TypeScript

import { SandboxClient } from "@basetenlabs/sandbox";

const client = new SandboxClient({ apiKey: process.env.BASETEN_API_KEY! });
const sandbox = await client.create({
  name: "hello-world",
  labels: { purpose: "hello-world" },
});
console.log(sandbox.name);

The call waits until the sandbox is ready. To reuse a live sandbox with the same name, set createIfNotExists: true.

Python

import os

from baseten.sandbox import SandboxClient

with SandboxClient(api_key=os.environ["BASETEN_API_KEY"]) as client:
    sandbox = client.create(name="hello-world", labels={"purpose": "hello-world"})
    print(sandbox.name)

The call waits until the sandbox is ready. To reuse a live sandbox with the same name, pass create_if_not_exists=True.

Go

package main

import (
    "context"
    "fmt"
    "log"
    "os"

    "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)
    }
    sb, err := client.Create(ctx, sandbox.CreateOptions{
        Name:   "hello-world",
        Labels: map[string]string{"purpose": "hello-world"},
    })
    if err != nil {
        log.Fatal(err)
    }
    fmt.Println(sb.Name())
}

The call waits until the sandbox is ready. To reuse a live sandbox with the same name, set CreateIfNotExists: true.

CLI

baseten sandbox create --name "$SANDBOX_NAME" --label purpose=hello-world

The command waits until the sandbox is ready, then prints its record with status DEPLOYED, so you can run commands in it right away. Without flags, the sandbox uses Base Image, 4096 MiB, and the closest region. Change them with --image, --memory, or --region:

baseten sandbox create --name "$SANDBOX_NAME" --image baseten/base-image:latest --memory 8192 --region us-was-1

To reuse a live sandbox with the same name instead of failing on a name conflict, add --if-not-exists:

baseten sandbox create --name "$SANDBOX_NAME" --if-not-exists

UI

To create a sandbox:

1. Sign in to your workspace at app.baseten.co and choose Sandboxes in the sidebar.
2. Choose Create sandbox.
3. Choose Base Image, or another image with the software your task needs.
4. Enter a Name, for example, hello-world.
5. For Memory (MiB), keep the default or enter the memory the workload needs. More memory also means more CPU.
6. Choose a Region.
7. Optionally, for Time to live, choose how long the sandbox can run before Baseten deletes it.
8. If the form shows Team, choose the team that should own the sandbox.
9. Optionally, add environment variables.
10. Choose Create sandbox.

If the form reports an error, check the validation message next to each field. For common causes, see Handle a failed command.

Get a sandbox

A sandbox’s record shows its configuration, URL, and current status.

TypeScript

import { SandboxClient } from "@basetenlabs/sandbox";

const client = new SandboxClient({ apiKey: process.env.BASETEN_API_KEY! });
const info = await client.getInfo({ name: "hello-world" });
console.log(info.status);

To work with the sandbox, not just its record, use client.get({ name: "hello-world" }).

Python

import os

from baseten.sandbox import SandboxClient

with SandboxClient(api_key=os.environ["BASETEN_API_KEY"]) as client:
    info = client.get_info(name="hello-world")
    print(info.status)

To work with the sandbox, not just its record, use sandbox = client.get(name="hello-world").

Go

package main

import (
    "context"
    "fmt"
    "log"
    "os"

    "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)
    }
    info, err := client.GetInfo(ctx, sandbox.GetInfoOptions{Name: "hello-world"})
    if err != nil {
        log.Fatal(err)
    }
    fmt.Println(info.Status)
}

To work with the sandbox, not just its record, use client.Get(ctx, sandbox.GetOptions{Name: "hello-world"}).

CLI

Command

baseten sandbox describe --name "$SANDBOX_NAME"

To print only one field, add --jq:

Command

baseten sandbox describe --name "$SANDBOX_NAME" --jq '.status'

UI

In Sandboxes, choose the sandbox. Its detail page shows the same status.

If the status is FAILED, inspect the sandbox’s logs before retrying. For the deployment and deletion statuses, see Lifecycle and expiration.

Interact with a running sandbox

You can interact with a sandbox in two ways:

• Use the Management API, through the CLI or an SDK, to:
  • Create sandboxes.
  • List sandboxes.
  • Update sandboxes.
  • Delete sandboxes.
• Use the sandbox’s own API, served by a server inside each sandbox at the sandbox’s url field, to:
  • Run commands.
  • Read, write, and edit files.

The sandbox’s server URL is the url field the create or get call returns. Get the URL before connecting:

Python

Command

import os

from baseten.sandbox import SandboxClient

with SandboxClient(api_key=os.environ["BASETEN_API_KEY"]) as client:
    sandbox = client.get(name="hello-world")
    print(sandbox.url)

CLI

Command

baseten sandbox describe --name "$SANDBOX_NAME" --jq '.url'

Dashboard

To get the sandbox’s server URL:

1. Sign in to your workspace at app.baseten.co and choose Sandboxes in the sidebar, then choose the sandbox.
2. On Overview, choose Connect.
3. In the Connect to sandbox dialog, choose a tab and copy its value.

Use the URL exactly as the API returns it. Direct HTTP calls and MCP clients need it, and the CLI and SDKs look it up for you:

To connect to a sandbox:

Connect with an interactive terminal, direct HTTP calls, an SDK, or an MCP client:

Python

The SDK wraps the sandbox’s API with file and process methods:

import os

from baseten.sandbox import SandboxClient

with SandboxClient(api_key=os.environ["BASETEN_API_KEY"]) as client:
    sandbox = client.get(name="hello-world")
    sandbox.fs.write(path="/tmp/hello.txt", content="hello")
    result = sandbox.process.exec(
        command="cat /tmp/hello.txt", wait_for_completion=True
    )
    print(result.stdout)

For operations the SDK doesn’t wrap, sandbox.raw_api is the generated client, and client.sandbox_from_url(url=...) builds a sandbox from a URL you already have.

HTTP

Send requests to the sandbox’s url, authenticated with a sandbox access token as a bearer token:

curl --url "<sandbox-url>" \
  --header "Authorization: Bearer $SANDBOX_TOKEN"

The sandbox’s OpenAPI spec is at <sandbox-url>/v1/spec.

CLI

baseten sandbox connect --name "$SANDBOX_NAME"

Opens an interactive terminal in the sandbox. Press Ctrl+D to disconnect.

MCP server

Point an MCP client at the sandbox’s url followed by /mcp, authenticated with a sandbox access token as a bearer token:

https://<sandbox-url>/mcp
Authorization: Bearer <SANDBOX_TOKEN>

An MCP client connected to the sandbox gets ready-made tools for running commands and for reading, writing, and editing files.

Applications that need tighter control than the MCP server’s tools define their own functions instead. The sandbox’s MCP server is separate from the Baseten MCP, which manages deployments and models across your workspace.

Run commands in a sandbox

Run a single command in a deployed sandbox. Its output streams to your terminal, and its exit code becomes the command’s exit code.

TypeScript

import { SandboxClient } from "@basetenlabs/sandbox";

const client = new SandboxClient({ apiKey: process.env.BASETEN_API_KEY! });
const sandbox = await client.get({ name: "hello-world" });
const result = await sandbox.process.exec({
  command: "python3 --version",
  waitForCompletion: true,
});
console.log(result.stdout, result.exitCode);

To set extra environment variables for one command, set env:

const result = await sandbox.process.exec({
  command: "python3 worker.py",
  env: { LOG_LEVEL: "debug" },
  waitForCompletion: true,
});

Python

import os

from baseten.sandbox import SandboxClient

with SandboxClient(api_key=os.environ["BASETEN_API_KEY"]) as client:
    sandbox = client.get(name="hello-world")
    result = sandbox.process.exec(command="python3 --version", wait_for_completion=True)
    print(result.stdout, result.exit_code)

To set extra environment variables for one command, pass env:

result = sandbox.process.exec(
    command="python3 worker.py",
    env={"LOG_LEVEL": "debug"},
    wait_for_completion=True,
)

Go

package main

import (
    "context"
    "fmt"
    "log"
    "os"

    "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)
    }
    sb, err := client.Get(ctx, sandbox.GetOptions{Name: "hello-world"})
    if err != nil {
        log.Fatal(err)
    }
    process, err := sb.Process().Exec(ctx, sandbox.ProcessExecOptions{
        Command:           "python3 --version",
        WaitForCompletion: true,
    })
    if err != nil {
        log.Fatal(err)
    }
    fmt.Println(process.Stdout, process.ExitCode)
}

To set extra environment variables for one command, set Env:

process, err := sb.Process().Exec(ctx, sandbox.ProcessExecOptions{
    Command:           "python3 worker.py",
    Env:               map[string]string{"LOG_LEVEL": "debug"},
    WaitForCompletion: true,
})

CLI

Put the command after --:

Command

baseten sandbox exec --name "$SANDBOX_NAME" -- python3 --version

To set extra environment variables for one command, add --env KEY=VALUE before --:

baseten sandbox exec --name "$SANDBOX_NAME" --env LOG_LEVEL=debug -- python3 worker.py

For an interactive terminal, see Connect to a sandbox.

Set environment variables

Environment variables pass configuration, such as an output format or log level, to the processes in a sandbox, so one image can serve different tasks. Set them at creation. Names begin with a letter or underscore and contain only letters, digits, and underscores. Don’t put your Baseten API key in a sandbox’s environment.

TypeScript

import { SandboxClient } from "@basetenlabs/sandbox";

const client = new SandboxClient({ apiKey: process.env.BASETEN_API_KEY! });
const sandbox = await client.create({
  name: "hello-world",
  envs: {
    DB_PASSWORD: { value: "secret" },
    OUTPUT_FORMAT: { value: "json", secret: false },
  },
});
console.log(sandbox.name);

Set secret: false for a value you want to read back later.

Python

import os

from baseten.sandbox import SandboxClient, SandboxEnvValue

with SandboxClient(api_key=os.environ["BASETEN_API_KEY"]) as client:
    sandbox = client.create(
        name="hello-world",
        envs={
            "DB_PASSWORD": SandboxEnvValue(value="secret"),
            "OUTPUT_FORMAT": SandboxEnvValue(value="json", secret=False),
        },
    )
    print(sandbox.name)

Set secret=False for a value you want to read back later.

Go

package main

import (
    "context"
    "fmt"
    "log"
    "os"

    "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)
    }
    sb, err := client.Create(ctx, sandbox.CreateOptions{
        Name: "hello-world",
        Envs: map[string]sandbox.EnvValue{
            "DB_PASSWORD":   {Value: "secret"},
            "OUTPUT_FORMAT": {Value: "json", NonSecret: true},
        },
    })
    if err != nil {
        log.Fatal(err)
    }
    fmt.Println(sb.Name())
}

Set NonSecret: true for a value you want to read back later.

CLI

baseten sandbox create --name "$SANDBOX_NAME" --env DB_PASSWORD=secret --plain-env OUTPUT_FORMAT=json

--env marks the value secret; --plain-env leaves it readable. To verify a value after deployment, read the variable inside the sandbox:

Command

baseten sandbox exec --name "$SANDBOX_NAME" -- 'echo $OUTPUT_FORMAT'

UI

To set environment variables:

1. In Sandboxes, choose Create sandbox, then choose an image.
2. Under Environment variables, choose Add variable.
3. Type a name and value, such as OUTPUT_FORMAT and json.
4. Repeat steps 2 and 3 for each additional variable.

Values are secret by default. Secret values are masked as **** when you read them back, so use them for credentials and tokens. For configuration you’ll want to see later, such as LOG_LEVEL or OUTPUT_FORMAT, mark the value as not secret so it stays readable. A describe shows the difference:

[
  { "name": "DB_PASSWORD", "secret": true,  "value": "****" },
  { "name": "LOG_LEVEL",   "secret": false, "value": "info" }
]

To read a secret value back, add --show-secrets to describe, or read the variable inside the sandbox. Don’t pass --plain-env or secret: false for credentials; those values are stored and returned in plain text.

List sandboxes

TypeScript

import { SandboxClient } from "@basetenlabs/sandbox";

const client = new SandboxClient({ apiKey: process.env.BASETEN_API_KEY! });
for await (const sandbox of client.list({ query: "hello" })) {
  console.log(sandbox.name, sandbox.status);
}

Filter by status with statuses, such as statuses: ["DEPLOYED"].

Python

import os

from baseten.sandbox import SandboxClient

with SandboxClient(api_key=os.environ["BASETEN_API_KEY"]) as client:
    for sandbox in client.list(query="hello"):
        print(sandbox.name, sandbox.status)

Filter by status with statuses, such as statuses=["DEPLOYED"].

Go

package main

import (
    "context"
    "fmt"
    "log"
    "os"

    "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)
    }
    for info, err := range client.List(ctx, sandbox.ListOptions{Query: "hello"}) {
        if err != nil {
            log.Fatal(err)
        }
        fmt.Println(info.Name, info.Status)
    }
}

Filter by status with Statuses, such as Statuses: []sandbox.Status{sandbox.StatusDeployed}.

CLI

Command

baseten sandbox list

The output lists every sandbox in the team, except terminated ones. Narrow it with --status or search names and labels with --query:

baseten sandbox list --status deployed
baseten sandbox list --query docs

Manage a sandbox’s labels

Labels help you find and group sandboxes, such as marking every sandbox an agent creates with purpose=agent. This example changes the purpose label from hello-world to hello-universe:

TypeScript

import { SandboxClient } from "@basetenlabs/sandbox";

const client = new SandboxClient({ apiKey: process.env.BASETEN_API_KEY! });
const updated = await client.update({
  name: "hello-world",
  labels: { purpose: "hello-universe" },
});
console.log(updated.labels);

Python

import os

from baseten.sandbox import SandboxClient

with SandboxClient(api_key=os.environ["BASETEN_API_KEY"]) as client:
    info = client.update(name="hello-world", labels={"purpose": "hello-universe"})
    print(info.labels)

Go

package main

import (
    "context"
    "fmt"
    "log"
    "os"

    "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)
    }
    updated, err := client.Update(ctx, sandbox.UpdateOptions{
        Name:   "hello-world",
        Labels: map[string]string{"purpose": "hello-universe"},
    })
    if err != nil {
        log.Fatal(err)
    }
    fmt.Println(updated.Labels)
}

CLI

baseten sandbox update --name "$SANDBOX_NAME" --label purpose=hello-universe

The command prints the updated sandbox.

UI

To change a sandbox’s labels:

1. In Sandboxes, choose the sandbox.
2. Choose Sandbox settings.
3. Under Labels, add, change, or remove labels.
4. Choose Save changes.

Sandbox settings is unavailable while a sandbox is deleting or archived.

A supplied set of labels replaces all previous labels, so include every one you want to keep. Omitted fields leave their values unchanged. You can also update environment variables with envs.

The name, image, memory, and region can’t change after creation. To use a different image, create a new sandbox.

Delete a sandbox

Deletion stops the sandbox’s processes and permanently removes its files, so save the files you need first.

TypeScript

import { SandboxClient } from "@basetenlabs/sandbox";

const client = new SandboxClient({ apiKey: process.env.BASETEN_API_KEY! });
await client.delete({ name: "hello-world" });

Python

import os

from baseten.sandbox import SandboxClient

with SandboxClient(api_key=os.environ["BASETEN_API_KEY"]) as client:
    client.delete(name="hello-world")

Go

package main

import (
    "context"
    "log"
    "os"

    "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)
    }
    if _, err := client.Delete(ctx, sandbox.DeleteOptions{Name: "hello-world"}); err != nil {
        log.Fatal(err)
    }
}

CLI

baseten sandbox delete --name "$SANDBOX_NAME"

Confirm when prompted. In scripts, add --yes to skip the prompt:

baseten sandbox delete --name "$SANDBOX_NAME" --yes

UI

To delete a sandbox:

1. In Sandboxes, choose the sandbox.
2. Choose Delete sandbox.
3. Type the sandbox’s name to confirm, then choose Delete sandbox.

Deletion continues after the call returns. Stop sending work to the sandbox, then describe the sandbox until its status is TERMINATED. The sandbox reports TERMINATED for a few minutes, and then it’s no longer found. Don’t reuse the name until deletion completes.

Work in a team

If you belong to multiple teams, specify a team ID when you create an SDK client:

TypeScript

import { SandboxClient } from "@basetenlabs/sandbox";

const client = new SandboxClient({
  apiKey: process.env.BASETEN_API_KEY!,
  teamId: "<TEAM_ID>",
});

Python

import os

from baseten.sandbox import SandboxClient

client = SandboxClient(api_key=os.environ["BASETEN_API_KEY"], team_id="<TEAM_ID>")

Go

package main

import (
    "log"
    "os"

    "github.com/basetenlabs/baseten-go/sandbox"
)

func main() {
    _, err := sandbox.NewClient(sandbox.ClientOptions{
        APIKey: os.Getenv("BASETEN_API_KEY"),
        TeamID: "<TEAM_ID>",
    })
    if err != nil {
        log.Fatal(err)
    }
}

CLI

The CLI uses your organization’s default team. To use another team, first list your organization’s teams:

baseten org team list

Then pass the team’s ID to the sandbox command:

baseten sandbox list --team <TEAM_ID>

Use the same team for every command that manages a particular sandbox.

Handle a failed command

Use the error message to choose the next action:

Error	Check
Not authenticated	Run baseten auth status, then baseten auth login or set BASETEN_API_KEY.
Permission denied	Sandboxes access for your organization and your permissions in the team.
Invalid name on create	The name must be 1 to 49 lowercase letters, digits, or hyphens, and start and end with a letter or digit.
Name conflict on create	Choose an unused name, or add --if-not-exists to reuse the live sandbox.
Quota exceeded: 10/10 sandboxes on create	Your organization is at its sandbox quota. Delete sandboxes you no longer need, or contact Baseten support with your organization ID to raise it.
Conflict on delete	The sandbox is in use or conflicts with the request. Retry after its current operation finishes.
Invalid update	An immutable field or an invalid value.
Team required	For SDK clients, specify a team ID if you belong to multiple teams. For CLI commands, specify a team ID if your organization has no default team. See Work in a team for examples.

Next steps

Sandbox lifecycle and expiration

Track deployment status and set an expiration policy.

Manage sandbox images

Choose a built-in image, or create and version your own.