Skip to main content
Each organization can run up to 10 sandboxes at once. To raise this limit, contact support.
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. Baseten ships these built-in images: The catalog in the dashboard and baseten sandbox image list-library always show the current list.
To list the built-in images:Run the following command:
To create a sandbox from a built-in image:Replace the example image reference with your selection, then run the following command:
To run Docker in a sandbox, create it from the Docker in Sandbox image, baseten/docker-in-sandbox:latest. The image starts Docker Engine and Docker Compose when the sandbox boots. Images and containers use the sandbox’s memory-backed storage, so size the sandbox’s memory to fit them.

Create a custom image

A custom image packages the dependencies and starting files your tasks need. Build one with an SDK’s ImageBuilder or from a Dockerfile with the CLI, 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.

Build an image

Every sandbox image must include the sandbox API server and start it as the entrypoint. An SDK’s ImageBuilder creates a Dockerfile and its build context, and adds the sandbox API binary and entrypoint unless you supply them yourself. With the CLI, your Dockerfile copies the binary from the sandbox API image. The SDK examples pass the new image as my-image:latest. The dashboard catalog shows custom images with a sandbox/ prefix, so the same image appears there as sandbox/my-image:latest, the reference the CLI examples use. Before running the SDK code, set up your SDK and API key. To build and check a custom image:
  1. Save the following code as build_image.mts:
    build_image.mts
  2. Run the script. The .mts extension makes Node treat the file as an ES module, which top-level await requires:
    The push waits until the image is built. The script prints BUILT, then hello from the image, and deletes the test sandbox.
Each example keeps my-image for future sandboxes. If a step fails after creating image-check, delete the sandbox before trying 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

The source image must include and start the sandbox API server, as the built-in images do. To import an image from a registry:
  1. Set a name for the new image:
  2. Set the source image’s full registry reference, including the registry hostname:
  3. Import the image and wait for the import to finish:
    To import from a private registry, pass a Docker config.json that contains the registry credentials:
    Without --wait, the command returns once Baseten accepts the import.

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:Run the following command:
To check the image’s status:Run the following command:
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:Run the following command:
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:
  1. Change the image’s source, then push it again with the same IMAGE_NAME. For a directory build, run the following command from the build directory:
  2. 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 the sandbox in the team that owns the custom image.
To create a sandbox from a custom image:Run the following command:
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>. 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 an image:Run the following command:
The command asks for confirmation; pass --yes to skip it when scripting.The CLI can’t delete a single version. Use the dashboard instead.
To remove every unused version across the team, including versions kept for future sandboxes, call Clean up unused images. To choose what to remove, delete a specific image or tag instead. For more information, see List sandbox images, Get a sandbox image, Push a sandbox image, and Delete a sandbox image.