> ## 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.
# Manage sandbox images
> Choose a built-in image or create your own, then list, version, and delete your team's sandbox images.
An *image* is the blueprint for a sandbox: the software and files it starts
with. Start from a built-in image, such as **Base Image** with Python, or create
a *custom image* that packages the dependencies and starting files your agent
needs every time. For what an image contains and how versions work, see
[How sandbox images work](/sandboxes/overview#how-sandbox-images-work).
## Prerequisites
* Permission to create resources in your team.
* For the CLI procedures, the [Baseten CLI](/sandboxes/manage#set-up-the-cli),
signed in.
## Choose a built-in image
The image catalog lists built-in environments for languages, browsers, web
applications, and desktops, plus the custom images built by teams you can
access. Each image has an **Image** reference, such as
`baseten/base-image:latest`, that you use to
[create a sandbox](/sandboxes/manage#create-a-sandbox).
**To choose a built-in image**:
1. Sign in to your workspace at [app.baseten.co](https://app.baseten.co)
and choose **Sandboxes** in the sidebar.
2. Choose **Create sandbox**.
3. To narrow the catalog, type a runtime or image name in
**Search images**, or select a workload under **Category**. Clear
category filters to include **Base Image**, which has no category.
4. Choose an image card, then review its **Image**, **Default memory**,
and **Ports**.
**To list the built-in images**:
```bash Command theme={"system"}
baseten sandbox image list-library
```
```txt Output theme={"system"}
NAME IMAGE MEMORY CATEGORIES
Base Image baseten/base-image:latest 4096 MB
Astro baseten/astro:latest 4096 MB web
Chromium baseten/chromium:latest 4096 MB browser
CUA XFCE Desktop baseten/cua-xfce:latest 4096 MB computer-use
...
```
Pass an image's reference, including its tag, to `--image`:
```bash theme={"system"}
baseten sandbox create --image baseten/base-image:latest
```
## Create a custom image
A custom image packages the dependencies and starting files your tasks need.
Build one from a Dockerfile or import one from a registry, using the CLI.
**To build a custom image**:
1. Set a new repository name, then create and enter a build directory:
```bash theme={"system"}
export IMAGE_NAME="my-image"
cd "$(mktemp -d)"
```
2. Create a Dockerfile. A sandbox image must include the sandbox API server
and start it as the entrypoint, so copy it from the sandbox API image. This
example starts from the same base as **Base Image** (Alpine Linux with
Node.js, Python, Git, and Bash), adds a package and a starting file:
```bash theme={"system"}
cat > Dockerfile <<'EOF'
FROM node:24-alpine3.21
COPY --from=ghcr.io/blaxel-ai/sandbox:latest /sandbox-api /usr/local/bin/sandbox-api
RUN apk add --no-cache bash git python3 jq
COPY hello.txt /hello.txt
ENTRYPOINT ["/usr/local/bin/sandbox-api"]
EOF
printf 'hello from the image\n' > hello.txt
```
3. Push the directory and wait for the image to build. Don't include
credentials in the directory:
```bash Command theme={"system"}
baseten sandbox image push --name "$IMAGE_NAME" --dir . --wait
```
```txt Output theme={"system"}
Name: my-image
Status: BUILT
Tags: 1
Size: 419.1 MiB
Created: 2026-10-07T17:28:52Z
```
4. Create a sandbox from the image, and check that the package and the
starting file are there:
```bash Command theme={"system"}
baseten sandbox create --name image-check --image "sandbox/${IMAGE_NAME}:latest"
baseten sandbox exec --name image-check -- 'jq --version && python3 --version && cat /hello.txt'
```
```txt Output theme={"system"}
jq-1.7.1
Python 3.12.15
hello from the image
```
**To import an image from a registry**:
1. Set a new repository name and the source image's full registry reference,
including the registry hostname. The source image must include and start
the sandbox API server, as the built-in images do:
```bash theme={"system"}
export IMAGE_NAME="my-image"
export REGISTRY_IMAGE="/:"
```
2. Push the image:
```bash theme={"system"}
baseten sandbox image push --name "$IMAGE_NAME" --registry-image "$REGISTRY_IMAGE"
```
The CLI returns once the import is accepted. Add `--wait` to wait until the
import finishes:
```bash theme={"system"}
baseten sandbox image push --name "$IMAGE_NAME" --registry-image "$REGISTRY_IMAGE" --wait
```
To import from a private registry, pass a Docker `config.json` with its
credentials:
```bash theme={"system"}
baseten sandbox image push --name "$IMAGE_NAME" --registry-image "$REGISTRY_IMAGE" \
--docker-config ~/.docker/config.json
```
## List images
Check a custom image's build status before using it. The **Images** tab and
`baseten sandbox image list` list only your team's custom images, not built-in
images.
**To list your team's images**:
1. In **Sandboxes**, choose **Images**.
2. For **Find by image name or tag**, type the image name.
3. Review the matching row's **Latest size**, **Sandboxes**, **Updated**,
and **Status** values.
For a failed build, see the
[image build logs](/sandboxes/logs#inspect-image-build-logs).
**To list your team's images**:
```bash Command theme={"system"}
baseten sandbox image list
```
```txt Output theme={"system"}
NAME STATUS TAGS SIZE CREATED
my-image BUILT 1 419.1 MiB 2026-10-07T17:28:52Z
```
**To check the image's status**:
```bash Command theme={"system"}
baseten sandbox image describe --name "$IMAGE_NAME"
```
```txt Output theme={"system"}
Name: my-image
Status: BUILT
Tags: 1
Size: 419.1 MiB
Created: 2026-10-07T17:28:52Z
```
While the status is `UPLOADING` or `BUILDING`, repeat the command, with a
bounded timeout in automation. Continue when it's `BUILT`. On `FAILED`,
inspect the [image build logs](/sandboxes/logs#inspect-image-build-logs).
## List versions
An image groups its versions under one repository name. Each version has a
*tag* that Baseten assigns; you can't choose or rename it. List the tags to
pin a sandbox to one version.
**To list an image's versions**:
1. In **Sandboxes** > **Images**, choose the image.
2. Review the tags table on its **Overview**, with each version's **Tag**,
**Size**, **Created**, and **Updated** values.
**To list an image's versions**:
```bash Command theme={"system"}
baseten sandbox image list-tags --name "$IMAGE_NAME"
```
```txt Output theme={"system"}
TAG SIZE CREATED
bd5596b7133f6fa8068cd 419.1 MiB 2026-10-07T17:31:51Z
```
To use a version, [select its tag in the image reference](#use-an-image-in-a-sandbox).
## Add a version
Add a version when your image's dependencies or starting files change. Pushing
changed source to an existing repository name adds a version with a new tag,
and `sandbox/:latest` resolves to it. Pushing identical source
doesn't add a version. Existing versions stay available, so sandboxes that use
a specific tag keep their version.
**To add a version**:
1. Run `baseten sandbox image push` again with the same `IMAGE_NAME`,
following [Create a custom image](#create-a-custom-image).
2. [List the image's versions](#list-versions) and confirm a new
tag appears.
If other pushes to the same name overlap, the status alone doesn't show which
build finished. To check a build independently, use a new repository name.
## Use an image in a sandbox
[Create a sandbox](/sandboxes/manage#create-a-sandbox) from the image in the
dashboard, or pass its reference to `--image`:
```bash theme={"system"}
baseten sandbox create --image "sandbox/${IMAGE_NAME}:latest"
```
For a custom image, the catalog selects `sandbox/:latest`.
`latest` always resolves to the newest version and doesn't appear in the tag
list, so it can point to a different version after your next build. To keep
new sandboxes on one version, pin a tag from
`baseten sandbox image list-tags` or the dashboard in your application's
configuration, such as `sandbox/:`, and create the
sandbox in the team that owns the image.
## Delete an image or a version
Deleting a sandbox doesn't delete its image. Delete an image or a version
separately when you no longer need it.
Deleting a tag removes that version, and deleting the repository removes all
its versions. Keep any version you plan to create more sandboxes from.
Deletion fails if an active sandbox uses a version you would remove. Save
needed files, [delete the dependent sandboxes](/sandboxes/manage#delete-a-sandbox),
and confirm their termination before retrying.
**To delete a version**:
1. In **Sandboxes** > **Images**, choose the image.
2. In the tags table, open the actions menu on the version's row.
3. Choose **Delete tag**, then choose **Delete tag** again to confirm.
**To delete an image**:
1. In **Sandboxes** > **Images**, open the actions menu on the image's row.
2. Choose **Delete image**.
3. Type the image's name, then choose **Delete image**.
**Delete image** is unavailable while any sandbox uses the image.
**To delete an image**:
```bash theme={"system"}
baseten sandbox image delete --name "$IMAGE_NAME"
```
Confirm when prompted. In scripts, add `--yes` to skip the prompt:
```bash theme={"system"}
baseten sandbox image delete --name "$IMAGE_NAME" --yes
```
To delete a single version, use the dashboard.
[Clean up unused images](/reference/management-api/sandboxes/clean-up-unused-images)
removes unused versions across the whole team, including versions you may have
kept for future sandboxes. Use targeted deletion to remove a specific image or
version.