Skip to main content
Sandboxes is in Private Preview. Contact Baseten to request access.
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.

​
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.
Baseten permanently removes a sandbox’s local data when it deletes the sandbox, including when the sandbox expires. Save results outside the sandbox first.

​
Next steps

Manage sandboxes

Create sandboxes in the dashboard or CLI, then inspect, update, and delete them.

Manage sandbox images

Choose a built-in image, or create and version your own.

Create a sandbox access token

Authenticate sandbox requests and MCP connections without your API key.

Sandbox lifecycle and expiration

Track deployment status and set an expiration policy.