Skip to main content
PRE-RELEASE: Sandbox commands are not GA yet. Their arguments, flags, and output may change.
Images are what sandboxes are created from. Push one from a directory with a Dockerfile, or import one from a registry, then create sandboxes with —image name:latest.

​
list

Lists the team’s images, up to —limit.

​
Options

​
TEXT
Filter JSON output with a jq expression; implies —output json (or jsonl for streamed commands)
​
INTEGER
default:"1000"
Most images to list. 0 lists all.
​
TEXT
default:"text"
Output formatOne of: text, json, jsonl, none
​
TEXT
Use a specific stored profile for this command, overriding BASETEN_PROFILE and the current profile
​
TEXT
Team name or ID to list images of. Defaults to your only team; required if you belong to more than one. Run ‘baseten org team list’ to see teams.
​
BOOL
Enable verbose logging

​
Examples

List images

​
Filter output with --jq

Print every built image’s name

​
Output

Text mode (--output text): Table with columns: NAME, STATUS, TAGS, SIZE, CREATED. Prints “No sandbox images found.” to stderr when the list is empty, and a note to stderr when —limit left some out. JSON mode (--output json): Go output type cmd.SandboxImageList.

​
describe

Retrieves one image’s record: status, tag count, and size.

​
Options

​
TEXT
Filter JSON output with a jq expression; implies —output json (or jsonl for streamed commands)
​
TEXT
required
Name of the image.
​
TEXT
default:"text"
Output formatOne of: text, json, jsonl, none
​
TEXT
Use a specific stored profile for this command, overriding BASETEN_PROFILE and the current profile
​
TEXT
Team name or ID the image belongs to. Defaults to your only team; required if you belong to more than one. Run ‘baseten org team list’ to see teams.
​
BOOL
Enable verbose logging

​
Examples

Describe an image

​
Filter output with --jq

Print the image’s status

​
Output

Text mode (--output text): One field per line describing the image. Empty fields are left out. JSON mode (--output json): Go output type managementapi.SandboxImage.

​
push

Pushes a new version of an image, from exactly one source: —dir builds the directory, which must have a Dockerfile at its root, and —registry-image imports an image from a registry. Paths in —dir are left out as a .dockerignore at its root says. Without one, these are left out, as if the .dockerignore were: **/.blaxel **/.env.build **/.docker **/.git **/dist **/.venv **/venv **/node_modules */.env .env **/.next **/pycache A .dockerignore replaces these defaults, so copy any you still want into it. By default the command returns once the push is accepted and the build runs on; —wait waits until the image is built.

​
Options

​
TEXT
Directory to build the image from, with a Dockerfile at its root.Mutually exclusive with other flags in group image-source.
​
TEXT
Path to a Docker config.json with credentials for pulling —registry-image from a private registry.
​
TEXT
Filter JSON output with a jq expression; implies —output json (or jsonl for streamed commands)
​
INTEGER
Memory in MB, from 1 to 32768, of the temporary environment that builds or imports the image. 0, the default, uses the server’s size. Does not change the memory of sandboxes created from the image.
​
TEXT
required
Name of the image.
​
TEXT
default:"text"
Output formatOne of: text, json, jsonl, none
​
TEXT
Use a specific stored profile for this command, overriding BASETEN_PROFILE and the current profile
​
TEXT
Registry image reference to import, such as registry.example.com/app:v1.Mutually exclusive with other flags in group image-source.
​
TEXT
Team name or ID the image belongs to. Defaults to your only team; required if you belong to more than one. Run ‘baseten org team list’ to see teams.
​
INTEGER
Scratch disk in MB, from 0 to 131072, for the temporary environment that builds or imports the image. Set it for large images that run out of space while building. 0, the default, builds in memory. Teams with HIPAA compliance enabled accept only 0.
​
BOOL
Wait until the image is built. Exits non-zero if the build fails. Does not stop the build if interrupted.
​
BOOL
Enable verbose logging
To give the temporary build environment more memory and disk space, run:
Both values are in MB. They size the build environment, not sandboxes created from the image.

​
Examples

Build an image from the current directory and wait for it
Import an image from a private registry

​
Filter output with --jq

Push from a directory and print the image’s status

​
Output

Text mode (--output text): One field per line describing the image. Empty fields are left out. JSON mode (--output json): Go output type managementapi.SandboxImage.

​
delete

Deletes an image and every version of it. This cannot be undone.

​
Options

​
TEXT
Filter JSON output with a jq expression; implies —output json (or jsonl for streamed commands)
​
TEXT
required
Name of the image.
​
TEXT
default:"text"
Output formatOne of: text, json, jsonl, none
​
TEXT
Use a specific stored profile for this command, overriding BASETEN_PROFILE and the current profile
​
TEXT
Team name or ID the image belongs to. Defaults to your only team; required if you belong to more than one. Run ‘baseten org team list’ to see teams.
​
BOOL
Skip the interactive confirmation prompt. Required when stdin is not a terminal.
​
BOOL
Enable verbose logging

​
Examples

Delete an image without the confirmation prompt

​
Filter output with --jq

Delete an image and print its status

​
Output

Text mode (--output text): A confirmation line on stderr. JSON mode (--output json): Go output type managementapi.SandboxImage. The image’s record as deletion starts.

​
logs

Prints an image’s build logs, oldest first. At most the newest 11,000 lines in the time range are printed. Lines may take a short time to appear after they are written.

​
Options

​
TEXT
Latest log time to print, such as 2026-10-05T15:04:05Z.
​
TEXT
Filter JSON output with a jq expression; implies —output json (or jsonl for streamed commands)
​
TEXT
required
Name of the image.
​
TEXT
default:"text"
Output formatOne of: text, json, jsonl, none
​
TEXT
Use a specific stored profile for this command, overriding BASETEN_PROFILE and the current profile
​
TEXT
Earliest log time to print, such as 2026-10-05T15:04:05Z.
​
TEXT
Team name or ID the image belongs to. Defaults to your only team; required if you belong to more than one. Run ‘baseten org team list’ to see teams.
​
BOOL
Enable verbose logging

​
Examples

Print an image’s build logs

​
Filter output with --jq

Print only the messages

​
Output

Text mode (--output text): One line per log entry: timestamp and message. JSON mode (--output json): Go output type managementapi.SandboxImageBuildLog.

​
list-tags

Lists every tag of an image, one per pushed version. Create a sandbox from a specific version with —image name:tag.

​
Options

​
TEXT
Filter JSON output with a jq expression; implies —output json (or jsonl for streamed commands)
​
TEXT
required
Name of the image.
​
TEXT
default:"text"
Output formatOne of: text, json, jsonl, none
​
TEXT
Use a specific stored profile for this command, overriding BASETEN_PROFILE and the current profile
​
TEXT
Team name or ID the image belongs to. Defaults to your only team; required if you belong to more than one. Run ‘baseten org team list’ to see teams.
​
BOOL
Enable verbose logging

​
Examples

List an image’s tags

​
Filter output with --jq

Print every tag

​
Output

Text mode (--output text): Table with columns: TAG, SIZE, CREATED. Prints “No tags found.” to stderr when the list is empty. JSON mode (--output json): Go output type cmd.SandboxImageTagList.

​
list-library

Lists the platform’s starter images, which any sandbox can be created from without pushing anything. Pass an entry’s image as —image to ‘sandbox create’.

​
Options

​
TEXT
Filter JSON output with a jq expression; implies —output json (or jsonl for streamed commands)
​
TEXT
default:"text"
Output formatOne of: text, json, jsonl, none
​
TEXT
Use a specific stored profile for this command, overriding BASETEN_PROFILE and the current profile
​
BOOL
Enable verbose logging

​
Examples

List the starter images

​
Filter output with --jq

Print every starter image

​
Output

Text mode (--output text): Table with columns: NAME, IMAGE, MEMORY, CATEGORIES. Prints “No starter images found.” to stderr when the list is empty. JSON mode (--output json): Go output type cmd.SandboxImageLibraryList.