Skip to main content
Each organization can run up to 10 sandboxes at once. To raise this limit, contact support.
Create a sandbox for an agent’s task, check that it’s deployed, and delete it when the work finishes. To choose a sandbox’s memory, vCPUs, environment variables, and labels, see Configure sandboxes. To run commands and work with files in a running sandbox, see Run commands and work with files.

Set up

Use an 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.
To install the SDK:Run the following command:
Set BASETEN_API_KEY to a Baseten API key for SDK authentication.
Run the following command to set the sandbox name used by the CLI and API examples:
If you belong to more than one team, select a team in each request.
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. You need permission to create resources in your team. A sandbox’s name, image, memory, vCPUs, and region can’t change after creation.
An organization can run up to 10 sandboxes at once. To raise this quota, Contact us with your organization ID.
To create a sandbox:Run the following code:
The call waits until the sandbox is ready. To reuse a live sandbox with the same name, set createIfNotExists: true.
To delete the sandbox automatically, set an expiration policy when you create it. To keep files across sandboxes, see Mount a volume.

Get a sandbox

A sandbox’s record shows its configuration, URL, and current status.
To check a sandbox’s status:Run the following code:
To work with the sandbox, not just its record, use client.get({ name: "hello-world" }).
For what each status means, see Deployment status. To connect to the sandbox, run commands in it, or call an HTTP service in it, see Run commands and work with files.

List sandboxes

The list includes every sandbox in the team except terminated ones.
To list sandboxes:Run the following code:
Filter by status with statuses, such as statuses: ["DEPLOYED"].

Update a sandbox

After creation, you can change a sandbox’s labels, environment variables, and expiration policy. Its name, image, memory, vCPUs, and region can’t change; to use different values, create a new sandbox. For every field you can change, see Update a sandbox.

Delete a sandbox

Deletion stops the sandbox’s processes and permanently removes its files. For how to keep files, see Local data.
To delete a sandbox:Run the following code:
Deletion continues after the call returns. Stop sending work to the sandbox, then get 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.

Troubleshoot sandbox requests

Use the error message to choose the next action:

Next steps

Configure sandboxes

Choose memory and vCPUs, and set environment variables and labels.

Run commands and work with files

Run commands, start background processes, and read and write files.

Sandbox lifecycle and expiration

Track deployment status and set an expiration policy.