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.
Sandbox APIs
You work with sandboxes through two APIs:- The Management API, at
https://api.baseten.co, creates, lists, updates, and deletes sandboxes, and manages their images, previews, and volumes. - The sandbox runtime API runs commands and reads, writes, and edits files inside one sandbox. Each sandbox serves it at its own URL through the sandbox API server, a process that runs inside the sandbox.
Sandbox URLs
A sandbox’s URL is theurl field that the create and get requests return.
Use it exactly as the API returns it:
How sandbox images work
Each sandbox starts from an image, the blueprint for its environment: the operating system, language runtimes, tools, and starting files your tasks use. An image also includes the sandbox API server, so a general-purpose container image, such aspython:3.12, needs it added before a sandbox can use it.
Start from a built-in image maintained by Baseten, such as Base Image with
Python, or build a custom image from a Dockerfile. Each successful build
creates a new tagged version of the image, and each sandbox starts from a copy
of one version. Files that a sandbox creates or changes while it runs don’t
change its image. For built-in images, custom
images, and versions, see Manage sandbox images.
Run your first command
-
Install the Baseten CLI, then run
the following command to sign in:
-
Run the following command to create a sandbox from the default image:
The command waits for status
DEPLOYED. If you belong to more than one team, select a team with--team. -
Run the following command to print a message from inside the sandbox:
-
When you’re finished, run the following command to delete the sandbox
and permanently remove its files:
Confirm when prompted. Pass
--yesto skip the prompt when scripting.
Access a sandbox
A sandbox is ready for work when its status isDEPLOYED. Your application or
agent can then work in it through any of these:
- SDK: run commands and work with files from your application’s code.
- CLI: run commands with
baseten sandbox exec, or open a terminal withbaseten sandbox connect. - HTTP: call the sandbox runtime API at the sandbox’s URL with a sandbox access token.
- MCP: connect an MCP client to the sandbox for ready-made command and file tools.
Deleting a sandbox, including when it
expires, permanently removes
its files. See Local data.
Reference
- Sandboxes API reference: Management API operations for sandboxes, images, previews, and volumes.
- Sandbox runtime API reference: file, process, and network operations inside a sandbox.
baseten sandbox: CLI commands for sandboxes and everything they use.
Next steps
Create and manage sandboxes
Create sandboxes with an SDK, the CLI, the API, or the dashboard, then inspect, update, and delete them.
Configure sandboxes
Choose memory and vCPUs, and set environment variables and labels.
Run commands and work with files
Run commands, start background processes, work with files, and call HTTP services.
Sandbox lifecycle and expiration
Understand standby and deployment status, and set an expiration policy.
Manage sandbox images
Choose a built-in image, or create and version your own.
Preview a sandbox application
Open a running web application through a public or private HTTPS URL.
Sandbox volumes
Keep files across sandboxes with persistent volumes.
Create a sandbox access token
Authenticate sandbox requests and MCP connections without your API key.
Inspect sandbox logs
Read command output, runtime logs, and image build logs.
Inspect sandbox metrics
Track a sandbox’s requests, error rate, CPU, and memory.