Sandboxes

A sandbox is an isolated environment where an agent runs commands and works with files. Use sandboxes to build agentic applications: when a user starts a project, create a sandbox for it, and your application’s agent loop runs its tool calls there. An agent that builds a website for a user can write and run the code in that user’s sandbox. An agent that researches a topic can download sources, run analysis, and collect the results in its own sandbox. Each sandbox is a separate environment, so you can give every user or project its own, and create and delete sandboxes as users come and go.

​

How sandbox images work

Each sandbox starts from an image, the blueprint for its environment. An image is a container image that includes:

• Base environment: the operating system and language runtimes, such as Python or Node.js.
• Tools: packages and command-line tools your tasks use.
• Starting files: code, data, and configuration copied into the image.
• Defaults: the memory a new sandbox gets and the ports it exposes.
• Sandbox API server: the process that runs commands and file operations for MCP tools. A general-purpose container image, such as python:3.12, doesn’t include it, so a custom image adds it in its Dockerfile.

Use a built-in image or create your own:

• Built-in images: ready-made environments maintained by Baseten, such as Base Image with Python. See Choose a built-in image.
• Custom images: images you build from a Dockerfile or import from a registry, versioned per team. See Create a custom image.

Baseten builds and versions a custom image before a sandbox can use it:

1. Build: you upload a Dockerfile and source files, or import an existing container image from a registry.
2. Version: when the build succeeds, the image gets a new version with a tag, and its status becomes BUILT.
3. Use: each sandbox you create from the image starts from a copy of that version.

Files that a sandbox creates or changes while it runs don’t change its image. Use file operations for task-specific inputs and outputs instead.

​

Run your first command

1. Install the Baseten CLI, then run the following command to sign in:
   baseten auth login
   
2. If you belong to multiple teams, choose a team before running sandbox commands. Run the following command to create a sandbox from the default image:
   baseten sandbox create --name hello-world
   
   The command waits for status DEPLOYED.
3. Run the following command to print a message from inside the sandbox:
   Command

   Output

   baseten sandbox exec --name hello-world -- 'printf "hello from the sandbox\n"'
   
4. When you’re finished, run the following command to delete the sandbox and permanently remove its local files:
   baseten sandbox delete --name hello-world
   
   Confirm when prompted. For unattended scripts, --yes skips confirmation.

For SDK and dashboard procedures, see Create a sandbox.

​

Access a sandbox

After you create a sandbox from an image, it’s ready for work when its status is DEPLOYED. Run commands in it with baseten sandbox exec, or open an interactive terminal with baseten sandbox connect. To have your coding agent work in it, let the agent run the same CLI commands. For more information, see Run commands in a sandbox.

​

Next steps