Each organization can run up to 10 sandboxes at once. To raise this limit, contact support.
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 asbaseten/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.
- CLI
- UI
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’sImageBuilder 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’sImageBuilder 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:
- TypeScript
- Python
- Go
- CLI
-
Save the following code as
build_image.mts:build_image.mts -
Run the script. The
.mtsextension makes Node treat the file as an ES module, which top-levelawaitrequires:The push waits until the image is built. The script printsBUILT, thenhello from the image, and deletes the test sandbox.
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:-
Set a name for the new image:
-
Set the source image’s full registry reference, including the registry
hostname:
-
Import the image and wait for the import to finish:
To import from a private registry, pass a Docker
config.jsonthat 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 andbaseten sandbox image list list only your team’s custom images, not built-in
images.
- CLI
- UI
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.- CLI
- UI
To list an image’s versions:Run the following command:
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:-
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: - List the image’s versions and confirm a new tag appears.
Use an image in a sandbox
Create the sandbox in the team that owns the custom image.- CLI
- UI
To create a sandbox from a custom image:Run the following command:
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.
- CLI
- UI
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.