Skip to main content
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 is an isolated environment where an agent runs commands and works with files. Create one for each user or project in your agentic application, and your agent loop runs its tool calls there, such as writing and running the code for a website or downloading and analyzing research sources.

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.
The SDKs and the Baseten CLI call both APIs for you. The sandbox API server handles their requests, direct HTTP requests, and MCP clients that connect to the sandbox. For the runtime API’s operations, see the Sandbox runtime API reference.

Sandbox URLs

A sandbox’s URL is the url field that the create and get requests return. Use it exactly as the API returns it: 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. 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 get a sandbox’s URL, see Get the sandbox URL.

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 as python: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

  1. Install the Baseten CLI, then run the following command to sign in:
  2. 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.
  3. Run the following command to print a message from inside the sandbox:
  4. When you’re finished, run the following command to delete the sandbox and permanently remove its files:
    Confirm when prompted. Pass --yes to skip the prompt when scripting.
For SDK, API, and dashboard procedures, see Create a sandbox.

Access a sandbox

A sandbox is ready for work when its status is DEPLOYED. 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 with baseten 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.
For each interface, see Run commands and work with files.
Deleting a sandbox, including when it expires, permanently removes its files. See Local data.

Reference

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.