> ## Documentation Index
> Fetch the complete documentation index at: https://docs.baseten.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Sandboxes

> Give each user or project in your agentic application an isolated environment where an agent can build software, run research, and work with files.

<Note>
  Sandboxes is in **Private Preview**. [Contact Baseten](mailto:support@baseten.co)
  to request access.
</Note>

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](/sandboxes/manage-images#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](/sandboxes/manage-images#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](/sandboxes/manage#run-commands-in-a-sandbox).

<Note>
  Baseten permanently removes a sandbox's local data when it deletes the
  sandbox, including when the sandbox [expires](/sandboxes/lifecycle). Save
  results outside the sandbox first.
</Note>

## Next steps

<CardGroup cols={2}>
  <Card title="Manage sandboxes" icon="server" href="/sandboxes/manage">
    Create sandboxes in the dashboard or CLI, then inspect, update, and delete them.
  </Card>

  <Card title="Manage sandbox images" icon="box" href="/sandboxes/manage-images">
    Choose a built-in image, or create and version your own.
  </Card>

  <Card title="Create a sandbox access token" icon="key" href="/sandboxes/authentication">
    Authenticate sandbox requests and MCP connections without your API key.
  </Card>

  <Card title="Sandbox lifecycle and expiration" icon="clock" href="/sandboxes/lifecycle">
    Track deployment status and set an expiration policy.
  </Card>
</CardGroup>