> ## Documentation Index
> Fetch the complete documentation index at: https://docs.baseten.co/llms.txt
> Use this file to discover all available pages before exploring further.

# baseten sandbox image

> Manage sandbox images (PRE-RELEASE)

<Note>
  PRE-RELEASE: Sandbox commands are not GA yet. Their arguments, flags, and output may change.
</Note>

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

```sh theme={"system"}
baseten sandbox image list [OPTIONS]
```

Lists the team's images, up to --limit.

### Options

<ParamField body="-q, --jq" type="TEXT">
  Filter JSON output with a jq expression; implies --output json (or jsonl for streamed commands)
</ParamField>

<ParamField body="--limit" type="INTEGER" default="1000">
  Most images to list. 0 lists all.
</ParamField>

<ParamField body="-o, --output" type="TEXT" default="text">
  Output format

  One of: `text`, `json`, `jsonl`, `none`
</ParamField>

<ParamField body="--profile" type="TEXT">
  Use a specific stored profile for this command, overriding BASETEN\_PROFILE and the current profile
</ParamField>

<ParamField body="--team" type="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.
</ParamField>

<ParamField body="-v, --verbose" type="BOOL">
  Enable verbose logging
</ParamField>

### Examples

List images

```sh theme={"system"}
baseten sandbox image list
```

### Filter output with `--jq`

Print every built image's name

```sh theme={"system"}
baseten sandbox image list --jq '.items[] | select(.status == "BUILT") | .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

```sh theme={"system"}
baseten sandbox image describe [OPTIONS]
```

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

### Options

<ParamField body="-q, --jq" type="TEXT">
  Filter JSON output with a jq expression; implies --output json (or jsonl for streamed commands)
</ParamField>

<ParamField body="--name" type="TEXT" required>
  Name of the image.
</ParamField>

<ParamField body="-o, --output" type="TEXT" default="text">
  Output format

  One of: `text`, `json`, `jsonl`, `none`
</ParamField>

<ParamField body="--profile" type="TEXT">
  Use a specific stored profile for this command, overriding BASETEN\_PROFILE and the current profile
</ParamField>

<ParamField body="--team" type="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.
</ParamField>

<ParamField body="-v, --verbose" type="BOOL">
  Enable verbose logging
</ParamField>

### Examples

Describe an image

```sh theme={"system"}
baseten sandbox image describe --name my-image
```

### Filter output with `--jq`

Print the image's status

```sh theme={"system"}
baseten sandbox image describe --name my-image --jq '.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

```sh theme={"system"}
baseten sandbox image push [OPTIONS]
```

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

<ParamField body="--dir" type="TEXT">
  Directory to build the image from, with a Dockerfile at its root.

  Mutually exclusive with other flags in group `image-source`.
</ParamField>

<ParamField body="--docker-config" type="TEXT">
  Path to a Docker config.json with credentials for pulling --registry-image from a private registry.
</ParamField>

<ParamField body="-q, --jq" type="TEXT">
  Filter JSON output with a jq expression; implies --output json (or jsonl for streamed commands)
</ParamField>

<ParamField body="--name" type="TEXT" required>
  Name of the image.
</ParamField>

<ParamField body="-o, --output" type="TEXT" default="text">
  Output format

  One of: `text`, `json`, `jsonl`, `none`
</ParamField>

<ParamField body="--profile" type="TEXT">
  Use a specific stored profile for this command, overriding BASETEN\_PROFILE and the current profile
</ParamField>

<ParamField body="--registry-image" type="TEXT">
  Registry image reference to import, such as registry.example.com/app:v1.

  Mutually exclusive with other flags in group `image-source`.
</ParamField>

<ParamField body="--team" type="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.
</ParamField>

<ParamField body="--wait" type="BOOL">
  Wait until the image is built. Exits non-zero if the build fails. Does not stop the build if interrupted.
</ParamField>

<ParamField body="-v, --verbose" type="BOOL">
  Enable verbose logging
</ParamField>

### Examples

Build an image from the current directory and wait for it

```sh theme={"system"}
baseten sandbox image push --name my-image --dir . --wait
```

Import an image from a private registry

```sh theme={"system"}
baseten sandbox image push --name my-image --registry-image registry.example.com/app:v1 --docker-config ~/.docker/config.json
```

### Filter output with `--jq`

Push from a directory and print the image's status

```sh theme={"system"}
baseten sandbox image push --name my-image --dir . --jq '.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

```sh theme={"system"}
baseten sandbox image delete [OPTIONS]
```

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

### Options

<ParamField body="-q, --jq" type="TEXT">
  Filter JSON output with a jq expression; implies --output json (or jsonl for streamed commands)
</ParamField>

<ParamField body="--name" type="TEXT" required>
  Name of the image.
</ParamField>

<ParamField body="-o, --output" type="TEXT" default="text">
  Output format

  One of: `text`, `json`, `jsonl`, `none`
</ParamField>

<ParamField body="--profile" type="TEXT">
  Use a specific stored profile for this command, overriding BASETEN\_PROFILE and the current profile
</ParamField>

<ParamField body="--team" type="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.
</ParamField>

<ParamField body="--yes" type="BOOL">
  Skip the interactive confirmation prompt. Required when stdin is not a terminal.
</ParamField>

<ParamField body="-v, --verbose" type="BOOL">
  Enable verbose logging
</ParamField>

### Examples

Delete an image without the confirmation prompt

```sh theme={"system"}
baseten sandbox image delete --name my-image --yes
```

### Filter output with `--jq`

Delete an image and print its status

```sh theme={"system"}
baseten sandbox image delete --name my-image --yes --jq '.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

```sh theme={"system"}
baseten sandbox image logs [OPTIONS]
```

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

<ParamField body="--end" type="TEXT">
  Latest log time to print, such as 2026-10-05T15:04:05Z.
</ParamField>

<ParamField body="-q, --jq" type="TEXT">
  Filter JSON output with a jq expression; implies --output json (or jsonl for streamed commands)
</ParamField>

<ParamField body="--name" type="TEXT" required>
  Name of the image.
</ParamField>

<ParamField body="-o, --output" type="TEXT" default="text">
  Output format

  One of: `text`, `json`, `jsonl`, `none`
</ParamField>

<ParamField body="--profile" type="TEXT">
  Use a specific stored profile for this command, overriding BASETEN\_PROFILE and the current profile
</ParamField>

<ParamField body="--start" type="TEXT">
  Earliest log time to print, such as 2026-10-05T15:04:05Z.
</ParamField>

<ParamField body="--team" type="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.
</ParamField>

<ParamField body="-v, --verbose" type="BOOL">
  Enable verbose logging
</ParamField>

### Examples

Print an image's build logs

```sh theme={"system"}
baseten sandbox image logs --name my-image
```

### Filter output with `--jq`

Print only the messages

```sh theme={"system"}
baseten sandbox image logs --name my-image --jq '.message'
```

### Output

**Text mode (`--output text`):** One line per log entry: timestamp and message.

**JSON mode (`--output json`):** Go output type `managementapi.SandboxImageBuildLog`.

## list-tags

```sh theme={"system"}
baseten sandbox image list-tags [OPTIONS]
```

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

### Options

<ParamField body="-q, --jq" type="TEXT">
  Filter JSON output with a jq expression; implies --output json (or jsonl for streamed commands)
</ParamField>

<ParamField body="--name" type="TEXT" required>
  Name of the image.
</ParamField>

<ParamField body="-o, --output" type="TEXT" default="text">
  Output format

  One of: `text`, `json`, `jsonl`, `none`
</ParamField>

<ParamField body="--profile" type="TEXT">
  Use a specific stored profile for this command, overriding BASETEN\_PROFILE and the current profile
</ParamField>

<ParamField body="--team" type="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.
</ParamField>

<ParamField body="-v, --verbose" type="BOOL">
  Enable verbose logging
</ParamField>

### Examples

List an image's tags

```sh theme={"system"}
baseten sandbox image list-tags --name my-image
```

### Filter output with `--jq`

Print every tag

```sh theme={"system"}
baseten sandbox image list-tags --name my-image --jq '.items[].name'
```

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

```sh theme={"system"}
baseten sandbox image list-library [OPTIONS]
```

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

<ParamField body="-q, --jq" type="TEXT">
  Filter JSON output with a jq expression; implies --output json (or jsonl for streamed commands)
</ParamField>

<ParamField body="-o, --output" type="TEXT" default="text">
  Output format

  One of: `text`, `json`, `jsonl`, `none`
</ParamField>

<ParamField body="--profile" type="TEXT">
  Use a specific stored profile for this command, overriding BASETEN\_PROFILE and the current profile
</ParamField>

<ParamField body="-v, --verbose" type="BOOL">
  Enable verbose logging
</ParamField>

### Examples

List the starter images

```sh theme={"system"}
baseten sandbox image list-library
```

### Filter output with `--jq`

Print every starter image

```sh theme={"system"}
baseten sandbox image list-library --jq '.items[].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`.