Manage 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.

Prerequisites

Permission to create resources in your team.
For the CLI procedures, the Baseten 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.

To choose a built-in image:

Sign in to your workspace at app.baseten.co and choose Sandboxes in the sidebar.
Choose Create sandbox.
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.
Choose an image card, then review its Image, Default memory, and Ports.

To list the built-in images:Run the following command:

baseten sandbox image list-library

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
...

To create a sandbox from the selected image, replace the example image reference with your selection and run the following command:

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 with the CLI, use an SDK’s ImageBuilder, or import an image from a registry. Base Image includes wget, but it doesn’t include curl. Install any additional tools your task needs in a custom image. To build a custom image:

Run the following commands to set a new image name and create a build directory:
export IMAGE_NAME="my-image" cd "$(mktemp -d)"
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) and adds a package and a starting file. Run the following commands to create the Dockerfile and starting file:
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 curl COPY hello.txt /hello.txt ENTRYPOINT ["/usr/local/bin/sandbox-api"] EOF printf 'hello from the image\n' > hello.txt

Keep credentials out of the build directory. Run the following command to push the directory and wait for the image to build:

baseten sandbox image push --name "$IMAGE_NAME" --dir . --wait

Name:           my-image
Status:         BUILT
Tags:           1
Size:           419.1 MiB
Created:        2026-10-07T17:28:52Z

Run the following commands to create a sandbox from the image and check its installed tools and starting file:

baseten sandbox create --name image-check --image "sandbox/${IMAGE_NAME}:latest"
baseten sandbox exec --name image-check -- 'jq --version && python3 --version && cat /hello.txt'

jq-1.7.1
Python 3.12.15
hello from the image

Build with an SDK

An ImageBuilder creates a Dockerfile and its build context. It adds the sandbox API binary and entrypoint unless you supply them yourself. Set up your SDK and API key before running the code.

Python
TypeScript
Go

To build and check a custom image:Run the following code:

import os

from baseten.sandbox import ImageBuilder, SandboxClient

builder = (
    ImageBuilder.from_registry("node:24-alpine3.21")
    .run_commands("apk add --no-cache bash git python3 jq curl")
    .add_file("/hello.txt", "hello from the image\n")
)
with SandboxClient(api_key=os.environ["BASETEN_API_KEY"]) as client:
    image = client.images.push(name="my-image", builder=builder)
    print(image.status)
    sandbox = client.create(name="image-check", image="my-image:latest")
    result = sandbox.process.exec(
        command="cat /hello.txt", wait_for_completion=True
    )
    print(result.stdout)
    client.delete(name="image-check")

To build and check a custom image:Run the following code:

import { ImageBuilder, SandboxClient } from "@basetenlabs/sandbox";

const client = new SandboxClient({ apiKey: process.env.BASETEN_API_KEY! });
const builder = ImageBuilder.fromRegistry("node:24-alpine3.21")
  .runCommands("apk add --no-cache bash git python3 jq curl")
  .addFile("/hello.txt", "hello from the image\n");
const image = await client.images.push({ name: "my-image", builder });
console.log(image.status);
const sandbox = await client.create({ name: "image-check", image: "my-image:latest" });
const result = await sandbox.process.exec({
  command: "cat /hello.txt",
  waitForCompletion: true,
});
console.log(result.stdout);
await client.delete({ name: "image-check" });

To build and check a custom image:Run the following code:

package main

import (
    "context"
    "fmt"
    "log"
    "os"

    "github.com/basetenlabs/baseten-go/sandbox"
)

func main() {
    ctx := context.Background()
    client, err := sandbox.NewClient(sandbox.ClientOptions{
        APIKey: os.Getenv("BASETEN_API_KEY"),
    })
    if err != nil {
        log.Fatal(err)
    }
    builder := sandbox.NewImageBuilder("node:24-alpine3.21").
        RunCommands("apk add --no-cache bash git python3 jq curl").
        AddFile("/hello.txt", []byte("hello from the image\n"))
    image, err := client.Images().Push(ctx, sandbox.ImagePushOptions{
        Name:          "my-image",
        SourceBuilder: builder,
    })
    if err != nil {
        log.Fatal(err)
    }
    fmt.Println(image.Status)
    sb, err := client.Create(ctx, sandbox.CreateOptions{
        Name:  "image-check",
        Image: "my-image:latest",
    })
    if err != nil {
        log.Fatal(err)
    }
    result, err := sb.Process().Exec(ctx, sandbox.ProcessExecOptions{
        Command:           "cat /hello.txt",
        WaitForCompletion: true,
    })
    if err != nil {
        log.Fatal(err)
    }
    fmt.Print(result.Stdout)
    if _, err := client.Delete(ctx, sandbox.DeleteOptions{Name: "image-check"}); err != nil {
        log.Fatal(err)
    }
}

Pass my-image:latest to the SDK. The catalog shows the same custom image as sandbox/my-image:latest. The push call waits until the image is BUILT. The command then prints hello from the image, confirming that the sandbox contains the starting file. The examples then delete the test sandbox and keep the image for future sandboxes. If a request fails after creating image-check, delete the sandbox before running the code again. Delete my-image separately if you no longer need it.

For repeatable builds, pin the sandbox API image to a tested tag or digest instead of ghcr.io/blaxel-ai/sandbox:latest. Set the reference in a Dockerfile’s COPY --from, or use sandbox_api_image with Python’s from_registry(), sandboxApiImage with TypeScript’s fromRegistry(), or SandboxAPIImage with Go’s NewImageBuilderWithOptions().

Import an image from a registry

To import an image from a registry:

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. Run the following commands to set the image name and registry reference:
export IMAGE_NAME="my-image" export REGISTRY_IMAGE="<REGISTRY_HOST>/<REPOSITORY>:<TAG>"

Run the following command to import the image:

baseten sandbox image push --name "$IMAGE_NAME" --registry-image "$REGISTRY_IMAGE"

The CLI returns once the import is accepted. To wait for the import to finish, run the following command:

baseten sandbox image push --name "$IMAGE_NAME" --registry-image "$REGISTRY_IMAGE" --wait

To import from a private registry, run the following command with a Docker config.json containing the registry credentials:

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:

In Sandboxes, choose Images.
For Find by image name or tag, type the image name.
Review the matching row’s Latest size, Sandboxes, Updated, and Status values.

For a failed build, see the image build logs.

To list your team’s images:Run the following command:

baseten sandbox image list

NAME      STATUS  TAGS  SIZE       CREATED
my-image  BUILT       1  419.1 MiB  2026-10-07T17:28:52Z

To check the image’s status:Run the following command:

baseten sandbox image describe --name "$IMAGE_NAME"

Name:           my-image
Status:         BUILT
Tags:           1
Size:           419.1 MiB
Created:        2026-10-07T17:28:52Z

Repeat the command while the status is UPLOADING or BUILDING. In automation, set a timeout for polling. Use the image when it’s BUILT. If the build fails, inspect the image build logs.

List versions

List an image’s version tags to choose which version a sandbox uses. Baseten assigns the tags; you can’t set or rename them.

To list an image’s versions:

In Sandboxes > Images, choose the image.
On Overview, review each version’s Tag, Size, Created, and Updated values in the tags table.

To list an image’s versions:Run the following command:

baseten sandbox image list-tags --name "$IMAGE_NAME"

TAG                      SIZE       CREATED
bd5596b7133f6fa8068cd  419.1 MiB  2026-10-07T17:31:51Z

To use a version, select its tag in the image reference.

Add a version

Push changed source to an existing image name to add a version. Pushing identical source doesn’t create a version, and existing versions stay available. To add a version:

Run baseten sandbox image push again with the same IMAGE_NAME, following Create a custom image.
List the image’s versions and confirm a new tag appears.

If pushes to the same image name overlap, its status doesn’t identify which build finished. Use a separate image name to track a build independently.

Use an image in a sandbox

Create a sandbox in the team that owns the custom image. Choose the image in the dashboard, or run the following command:

baseten sandbox create --image "sandbox/${IMAGE_NAME}:latest"

The catalog uses latest when you select a custom image. This tag tracks the newest version and doesn’t appear in the version list. To keep new sandboxes on one version, choose a tag from List versions and replace latest in the image reference with that tag, such as sandbox/<IMAGE_NAME>:<TAG_NAME>. Sandboxes already using a specific tag keep their version.

Delete an image or a version

Deleting a sandbox leaves its image available. Delete the image or individual versions separately when you no longer need them.

Deleting an image removes all its versions. Delete a single tag to remove only that version.

Deletion fails while an active sandbox uses the image or version. Save the files you need, delete those sandboxes, and wait for them to terminate before retrying.

To delete a version:

In Sandboxes > Images, choose the image.
In the tags table, open the actions menu on the version’s row.
Choose Delete tag, then choose Delete tag again to confirm.

To delete an image:

In Sandboxes > Images, open the actions menu on the image’s row.
Choose Delete image.
Type the image’s name, then choose Delete image.

Delete image is unavailable while any sandbox uses the image.

To delete an image:Run the following command:

baseten sandbox image delete --name "$IMAGE_NAME"

Confirm when prompted. For unattended scripts, --yes skips confirmation.To delete a single version, use the dashboard.

Clean up unused images removes unused versions across the team, including ones kept for future sandboxes. Delete a specific image or tag when you want to choose what to remove.

Get started

Model APIs

Inference

Frontier Gateway

Training

Sandboxes

Development

Deployment

Engines

Model Labs

Organization

Hosting options

Observability

Troubleshooting

Manage sandbox images

Prerequisites

Choose a built-in image

Create a custom image

Build with an SDK

Import an image from a registry

List images

List versions

Add a version

Use an image in a sandbox

Delete an image or a version

​Prerequisites

​Choose a built-in image

​Create a custom image

​Build with an SDK

​Import an image from a registry

​List images

​List versions

​Add a version

​Use an image in a sandbox

​Delete an image or a version

Prerequisites

Choose a built-in image

Create a custom image

Build with an SDK

Import an image from a registry

List images

List versions

Add a version

Use an image in a sandbox

Delete an image or a version