Manage sandboxes

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. For file, process, and network API definitions, see the Sandbox runtime API reference.

Set up

Install the CLI or an SDK:

TypeScript
Python
Go
CLI

To install the SDK:Run the following command:

npm install @basetenlabs/sandbox undici

Set BASETEN_API_KEY to a Baseten API key for SDK authentication.

To install the SDK:Run the following command:

pip install baseten "httpx[http2]"

Set BASETEN_API_KEY to a Baseten API key for SDK authentication.

To install the SDK:Run the following command:

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

Set BASETEN_API_KEY to a Baseten API key for SDK authentication.

To sign in:Install the Baseten CLI, then run the following command:

baseten auth login

Run the following command to set the sandbox name used by the CLI examples:

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
Python
Go
CLI
UI

To create a sandbox:Run the following code:

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.

To create a sandbox:Run the following code:

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.

To create a sandbox:Run the following code:

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.

To create a sandbox:Run the following command:

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. To use a different image, memory allocation, or region, run the following command:

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, run the following command:

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

To create a sandbox:

Sign in to your workspace at app.baseten.co and choose Sandboxes in the sidebar.
Choose Create sandbox.
Choose Base Image, or another image with the software your task needs.
Enter a Name, for example, hello-world.
For Memory (MiB), keep the default or enter the memory the workload needs. More memory also means more CPU.
Choose a Region.
Optionally, for Time to live, choose how long the sandbox can run before Baseten deletes it.
If the form shows Team, choose the team that should own the sandbox.
Optionally, add environment variables.
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
Python
Go
CLI
UI

To check a sandbox’s status:Run the following code:

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

To check a sandbox’s status:Run the following code:

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").

To check a sandbox’s status:Run the following code:

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

To check a sandbox’s status:Run the following command:

baseten sandbox describe --name "$SANDBOX_NAME"

Name:         hello-world
Status:       DEPLOYED
URL:          <SANDBOX_URL>
Image:        baseten/base-image:latest
Memory:       4096 MB
Region:       us-was-1
Labels:       purpose=hello-world
Ports:        8080
Created:      2026-10-07T17:28:19Z

To print only the sandbox’s status, run the following command:

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

"DEPLOYED"

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
CLI
Dashboard

To get the sandbox’s server URL:Run the following code:

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)

https://sbx-hello-world-abc123.us-pdx-1.b10.co/

To get the sandbox’s server URL:Run the following command:

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

"https://sbx-hello-world-abc123.us-pdx-1.b10.co"

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:

Anatomy of a sandbox server URL. In https://sbx-hello-world-abc123.us-pdx-1.b10.co, hello-world is the sandbox name, abc123 identifies the sandbox's team, and us-pdx-1 is the region.

To connect to a sandbox: Connect with an interactive terminal, direct HTTP calls, an SDK, or an MCP client:

Python
HTTP
CLI
MCP server

To write and read a file through the SDK:Run the following code:

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.

To send an authenticated request to the sandbox:Request a sandbox access token, then run the following command:

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

Set SANDBOX_URL to the url returned by the create or get request. To retrieve the sandbox’s OpenAPI spec, run the following command with the same sandbox access token:

curl --url "${SANDBOX_URL%/}/swagger/doc.json" \
  --header "Authorization: Bearer $SANDBOX_TOKEN"

The spec describes the API inside that sandbox, including file and process operations.

To open an interactive terminal in the sandbox:Run the following command:

baseten sandbox connect --name "$SANDBOX_NAME"

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

To connect an MCP client to the sandbox:Request a sandbox access token, then configure your MCP client with the following endpoint and authorization header:

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
Python
Go
CLI

To check the sandbox’s Python version:Run the following code:

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 add environment variables for one command:Replace worker.py with the path to your script in the sandbox, then update the example as follows:

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

To check the sandbox’s Python version:Run the following code:

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 add environment variables for one command:Replace worker.py with the path to your script in the sandbox, then update the example as follows:

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

To check the sandbox’s Python version:Run the following code:

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 add environment variables for one command:Replace worker.py with the path to your script in the sandbox, then update the example as follows:

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

To check the sandbox’s Python version:Run the following command:

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

Python 3.12.15

To add environment variables for one command:Replace worker.py with the path to your script in the sandbox, then run the following command:

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

For an interactive terminal, see Connect to a sandbox.

Access an HTTP service

Start an HTTP service in a sandbox, then send requests through the sandbox API server’s /port/<PORT>/ route. The service must be listening before you send the request. Use a running hello-world sandbox created from an image that includes Python, such as Base Image. Set up your SDK or CLI. For the SDK examples, set BASETEN_API_KEY. For every tab, request a sandbox access token and set SANDBOX_TOKEN in your local environment. Direct HTTP requests need this token even when an SDK starts the service.

TypeScript
Python
Go
CLI and cURL

To call an HTTP service:Run the following code to start the server, wait until it listens on port 8000, send a request, and stop the server:

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

const client = new SandboxClient({ apiKey: process.env.BASETEN_API_KEY! });
const sandbox = await client.get({ name: "hello-world" });
await sandbox.process.exec({
  command: "python3 -m http.server 8000",
  name: "web",
  waitForPorts: [8000],
});
try {
  const response = await fetch(`${sandbox.url.replace(/\/$/, "")}/port/8000/`, {
    headers: { Authorization: `Bearer ${process.env.SANDBOX_TOKEN}` },
  });
  console.log(await response.text());
} finally {
  await sandbox.process.stop({ identifier: "web" });
}

<!DOCTYPE HTML>
<html lang="en">
<head>
<meta charset="utf-8">
<title>Directory listing for /</title>
...

To call an HTTP service:Run the following code to start the server, wait until it listens on port 8000, send a request, and stop the server:

import os
from urllib.request import Request, urlopen

from baseten.sandbox import SandboxClient

with SandboxClient(api_key=os.environ["BASETEN_API_KEY"]) as client:
    sandbox = client.get(name="hello-world")
    sandbox.process.exec(
        command="python3 -m http.server 8000",
        name="web",
        wait_for_ports=[8000],
    )
    try:
        request = Request(
            f"{sandbox.url.rstrip('/')}/port/8000/",
            headers={"Authorization": f"Bearer {os.environ['SANDBOX_TOKEN']}"},
        )
        with urlopen(request) as response:
            print(response.read().decode())
    finally:
        sandbox.process.stop(identifier="web")

<!DOCTYPE HTML>
<html lang="en">
<head>
<meta charset="utf-8">
<title>Directory listing for /</title>
...

To call an HTTP service:Run the following code to start the server, wait until it listens on port 8000, send a request, and stop the server:

package main

import (
    "context"
    "io"
    "log"
    "net/http"
    "os"
    "strings"

    "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)
    }
    _, err = sb.Process().Exec(ctx, sandbox.ProcessExecOptions{
        Command:      "python3 -m http.server 8000",
        Name:         "web",
        WaitForPorts: []int{8000},
    })
    if err != nil {
        log.Fatal(err)
    }
    defer sb.Process().Stop(ctx, sandbox.ProcessStopOptions{Identifier: "web"})

    request, err := http.NewRequestWithContext(ctx, http.MethodGet, strings.TrimRight(sb.URL(), "/")+"/port/8000/", nil)
    if err != nil {
        log.Print(err)
        return
    }
    request.Header.Set("Authorization", "Bearer "+os.Getenv("SANDBOX_TOKEN"))
    response, err := http.DefaultClient.Do(request)
    if err != nil {
        log.Print(err)
        return
    }
    defer response.Body.Close()
    if _, err := io.Copy(os.Stdout, response.Body); err != nil {
        log.Print(err)
    }
}

<!DOCTYPE HTML>
<html lang="en">
<head>
<meta charset="utf-8">
<title>Directory listing for /</title>
...

To call an HTTP service:Set SANDBOX_NAME to hello-world and SANDBOX_URL to its returned url before running these commands.

Run the following command to start the server and wait until it listens on port 8000:

baseten sandbox process start --name "$SANDBOX_NAME" \
  --process-name web --wait-for-port 8000 -- python3 -m http.server 8000

Run the following command to request the server’s directory listing:

curl --url "${SANDBOX_URL%/}/port/8000/" \
  --header "Authorization: Bearer $SANDBOX_TOKEN"

<!DOCTYPE HTML>
<html lang="en">
<head>
<meta charset="utf-8">
<title>Directory listing for /</title>
...

When you’re finished, run the following command to stop the server:

baseten sandbox process stop --name "$SANDBOX_NAME" --process-name web

A successful request returns HTTP 200 with Python’s directory listing. Requests without the sandbox access token return HTTP 401.

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
Python
Go
CLI
UI

To create a sandbox with environment variables:Run the following code:

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.

To create a sandbox with environment variables:Run the following code:

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.

To create a sandbox with environment variables:Run the following code:

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.

To create a sandbox with environment variables:Run the following command:

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, run the following command:

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

json

To set environment variables:

In Sandboxes, choose Create sandbox, then choose an image.
Under Environment variables, choose Add variable.
Type a name and value, such as OUTPUT_FORMAT and json.
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" }
]

Secret masking protects values in ordinary configuration responses. Code running inside the sandbox can read the actual values, including an agent that can run commands. Only provide credentials that you’re willing to make available to that code. To reveal secret values in the configuration, run the following command:

baseten sandbox describe --name "$SANDBOX_NAME" --show-secrets

Don’t include this output in logs or agent prompts. Don’t pass --plain-env or secret: false for credentials; those values remain readable in ordinary configuration responses.

Replace environment variables

Include every variable you want to keep when you update envs, including existing secrets and their actual values. SDK and API updates replace the entire environment variable set. The CLI’s --env and --plain-env update flags do the same. Don’t copy masked **** values from a configuration response. Omitting envs leaves the existing set unchanged. Set DB_PASSWORD in your local shell, then run the following command to replace the sandbox’s environment variables with one secret and one plain-text variable:

baseten sandbox update --name "$SANDBOX_NAME" \
  --env "DB_PASSWORD=$DB_PASSWORD" --plain-env OUTPUT_FORMAT=json

The update removes any sandbox variables you omit from the command.

List sandboxes

TypeScript
Python
Go
CLI

To list sandboxes:Run the following code:

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"].

To list sandboxes:Run the following code:

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"].

To list sandboxes:Run the following code:

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

To list sandboxes:Run the following command:

baseten sandbox list

NAME         STATUS    REGION    CREATED
hello-world  DEPLOYED  us-was-1  2026-10-07T17:28:19Z

The output lists every sandbox in the team, except terminated ones. To filter by status or search names and labels, run the following commands:

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
Python
Go
CLI
UI

To change a sandbox’s labels:Run the following code:

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

To change a sandbox’s labels:Run the following code:

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)

To change a sandbox’s labels:Run the following code:

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

To change a sandbox’s labels:Run the following command:

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

The command prints the updated sandbox.

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
Python
Go
CLI
UI

To delete a sandbox:Run the following code:

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

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

To delete a sandbox:Run the following code:

import os

from baseten.sandbox import SandboxClient

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

To delete a sandbox:Run the following code:

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

To delete a sandbox:Run the following command:

baseten sandbox delete --name "$SANDBOX_NAME"

Confirm when prompted. For unattended scripts, --yes skips confirmation.

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
Python
Go
CLI

To select a team for SDK requests:Replace <TEAM_ID> with your team’s ID, then configure the client as follows:

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

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

To select a team for SDK requests:Replace <TEAM_ID> with your team’s ID, then configure the client as follows:

import os

from baseten.sandbox import SandboxClient

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

To select a team for SDK requests:Replace <TEAM_ID> with your team’s ID, then configure the client as follows:

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

To manage sandboxes in another team:The CLI uses your organization’s default team. Run the following command to list your organization’s teams:

baseten org team list

Replace <TEAM_ID> with the selected team’s ID, then run the following 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.

Get started

Model APIs

Inference

Frontier Gateway

Training

Sandboxes

Development

Deployment

Engines

Model Labs

Organization

Hosting options

Observability

Troubleshooting

Manage sandboxes

Set up

Create a sandbox

Get a sandbox

Interact with a running sandbox

Run commands in a sandbox

Access an HTTP service

Set environment variables

Replace environment variables

List sandboxes

Manage a sandbox’s labels

Delete a sandbox

Work in a team

Handle a failed command

Next steps

Sandbox lifecycle and expiration

Manage sandbox images

​Set up

​Create a sandbox

​Get a sandbox

​Interact with a running sandbox

​Run commands in a sandbox

​Access an HTTP service

​Set environment variables

​Replace environment variables

​List sandboxes

​Manage a sandbox’s labels

​Delete a sandbox

​Work in a team

​Handle a failed command

​Next steps

Sandbox lifecycle and expiration

Manage sandbox images

Set up

Create a sandbox

Get a sandbox

Interact with a running sandbox

Run commands in a sandbox

Access an HTTP service

Set environment variables

Replace environment variables

List sandboxes

Manage a sandbox’s labels

Delete a sandbox

Work in a team

Handle a failed command

Next steps