Skip to main content
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:
  1. Sign in to your workspace at 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.

​
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:
  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:
  3. Push the directory and wait for the image to build. Don’t include credentials in the directory:
  4. Create a sandbox from the image, and check that the package and the starting file are there:
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:
  2. Push the image:
    The CLI returns once the import is accepted. Add --wait to wait until the import finishes:
    To import from a private registry, pass a Docker config.json with its credentials:

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

​
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 use a version, select its tag in the image reference.

​
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/<IMAGE_NAME>: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.
  2. List the image’s 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 from the image in the dashboard, or pass its reference to --image:
For a custom image, the catalog selects sandbox/<IMAGE_NAME>: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/<IMAGE_NAME>:<TAG_NAME>, 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, 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.
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.