Skip to main content
PRE-RELEASE: Sandbox commands are not GA yet. Their arguments, flags, and output may change.
Sandboxes run arbitrary commands in isolated environments. Create one, run commands in it with baseten sandbox exec, and delete it when done.

list

Lists the team’s sandboxes, up to --limit. Filter by free-text --query or repeatable --status.

Options

TEXT
Filter JSON output with a jq expression; implies --output json (or jsonl for streamed commands)
INTEGER
default:"1000"
Most sandboxes 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
Free-text search over sandbox names and labels.
TEXT (repeatable)
Only sandboxes with one of these statuses. Repeatable.One of: archived, archiving, building, deactivated, deactivating, deleting, deployed, deploying, failed, terminated, unarchiving, uploading
TEXT
Team name or ID to list sandboxes 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 sandboxes
List only deployed sandboxes

Filter output with --jq

Print every sandbox’s URL

Output

Text mode (--output text): Table with columns: NAME, STATUS, REGION, CREATED. Prints “No sandboxes 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.SandboxList.

describe

Retrieves one sandbox’s record: status, URL, image, memory, CPU, region, mounted volumes, labels, and environment variables. Secret environment variable values are masked unless --show-secrets is passed.

Options

TEXT
Filter JSON output with a jq expression; implies --output json (or jsonl for streamed commands)
TEXT
required
Name of the sandbox.
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
Reveal secret environment variable values. Requires the workspace administrator role; other callers still see masked values.
TEXT
Team name or ID the sandbox 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 a sandbox

Filter output with --jq

Print the sandbox’s URL

Output

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

create

Creates a sandbox and prints its record. Only the flags passed go into the request; the server applies its defaults to the rest. Environment variables from --env are secret, so their values are masked when read back; use --plain-env for values that are not. Mount a persistent disk with --volume as NAME:MOUNT_PATH, appending :ro to mount it read-only. The volume must be in the sandbox’s region and no other sandbox may have it mounted. --filesystem-max-memory-usage caps how much of the sandbox’s memory its filesystem may use, as a percentage, a size such as 2Gi, or a number of Mi.

Options

INTEGER
Number of vCPUs, from 1 to 32. Defaults to an allocation derived from memory.
TEXT (repeatable)
Secret environment variable as KEY=VALUE, masked when read back. Repeatable.
TEXT
Delete the sandbox at this time. ISO 8601, local when no timezone is given.
TEXT
Maximum memory the filesystem can use, as a percentage of memory (80%), a size (2Gi), or Mi (2048). Defaults to 50%.
TEXT
Delete the sandbox after it has been idle this long, such as 30m or 2d.
BOOL
Return the existing sandbox with this name instead of failing, or recreate it if it is failed, terminated, or being deleted.
TEXT
Image to create the sandbox from, including its tag, such as my-image:latest.
TEXT
Filter JSON output with a jq expression; implies --output json (or jsonl for streamed commands)
TEXT (repeatable)
Label as KEY=VALUE. Repeatable.
TEXT
Delete the sandbox once it is this old, such as 12h or 7d.
INTEGER
Memory in MB. When --cpu is not set, also determines the CPU allocation.
TEXT
Unique name of the sandbox. The server generates one when omitted.
TEXT
default:"text"
Output formatOne of: text, json, jsonl, none
TEXT (repeatable)
Environment variable that is not secret, as KEY=VALUE, readable when read back. Repeatable.
TEXT
Use a specific stored profile for this command, overriding BASETEN_PROFILE and the current profile
TEXT
Region to create the sandbox in.
TEXT
Team name or ID to create the sandbox in. Defaults to your only team; required if you belong to more than one. Run ‘baseten org team list’ to see teams.
TEXT
How long to keep the sandbox’s record after it terminates, for log access, such as 1h or 7d. The server defaults to 5m.
TEXT (repeatable)
Sandbox volume to mount, as NAME:MOUNT_PATH, with :ro appended to mount it read-only, such as data:/data or data:/data:ro. It must be in the sandbox’s region and not mounted elsewhere. Repeatable, though at most one is currently supported.
BOOL
Enable verbose logging
To delete an idle sandbox after 30 minutes and retain its record for a day, run:

Examples

Create a sandbox with a generated name and server defaults
Create a named sandbox, or get it back if it already exists
Create one in a specific region with more CPU and memory
Create one with environment variables and labels
Create one with a volume mounted read-only

Filter output with --jq

Create a sandbox and print its generated name

Output

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

update

Updates a sandbox’s environment variables, labels, or lifecycle. Omitted flags leave their fields unchanged. Any --env or --plain-env replaces all of the sandbox’s environment variables, any --label replaces all of its labels, and --clear-labels removes every label.

Options

BOOL
Remove all of the sandbox’s labels. Cannot be combined with --label.
TEXT (repeatable)
Secret environment variable as KEY=VALUE, masked when read back. Repeatable.
TEXT
Delete the sandbox at this time. ISO 8601, local when no timezone is given.
TEXT
Delete the sandbox after it has been idle this long, such as 30m or 2d.
TEXT
Filter JSON output with a jq expression; implies --output json (or jsonl for streamed commands)
TEXT (repeatable)
Label as KEY=VALUE, replacing all of the sandbox’s labels. Repeatable. Cannot be combined with --clear-labels.
TEXT
Delete the sandbox once it is this old, such as 12h or 7d.
TEXT
required
Name of the sandbox.
TEXT
default:"text"
Output formatOne of: text, json, jsonl, none
TEXT (repeatable)
Environment variable that is not secret, as KEY=VALUE, readable when read back. Repeatable.
TEXT
Use a specific stored profile for this command, overriding BASETEN_PROFILE and the current profile
TEXT
Team name or ID the sandbox belongs to. Defaults to your only team; required if you belong to more than one. Run ‘baseten org team list’ to see teams.
TEXT
How long to keep the sandbox’s record after it terminates, for log access, such as 1h or 7d. The server defaults to 5m.
BOOL
Enable verbose logging
Setting any lifecycle flag replaces the entire lifecycle configuration, including expiration policies and terminated retention. Include every policy you want to keep. To set both idle and maximum-age limits, run:

Examples

Replace a sandbox’s labels

Filter output with --jq

Replace a sandbox’s labels and print them

Output

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

delete

Deletes a sandbox and everything in it. This cannot be undone. Deletion continues after this command returns.

Options

TEXT
Filter JSON output with a jq expression; implies --output json (or jsonl for streamed commands)
TEXT
required
Name of the sandbox.
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 sandbox 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 a sandbox without the confirmation prompt

Filter output with --jq

Delete a sandbox and print its status

Output

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

exec

Runs a command in a sandbox and waits for it to exit. This is basically ‘sandbox process start’ followed by ‘sandbox process wait’, except that the command’s output streams as it arrives and --stdin is available. The command’s exit code becomes the CLI’s exit code. Put the command after a literal —, and every flag before it. One argument is the whole command line, passed to the sandbox’s shell as is, so its quoting, variables, pipes, and redirects are interpreted there. Several arguments are quoted so each stays one argument.

Options

TEXT (repeatable)
Environment variable for the command as KEY=VALUE, on top of the sandbox’s own. Repeatable.
TEXT
Filter JSON output with a jq expression; implies --output json (or jsonl for streamed commands)
TEXT
required
Name of the sandbox.
TEXT
default:"text"
Output formatOne of: text, json, jsonl, none
TEXT
Name for the process, to find it later with --process-name.
TEXT
Use a specific stored profile for this command, overriding BASETEN_PROFILE and the current profile
BOOL
Send this command’s standard input to the sandbox command, closing it at end of input. Output then arrives a line at a time, so a prompt without a newline shows once its line ends.
TEXT
Team name or ID the sandbox belongs to. Defaults to your only team; required if you belong to more than one. Run ‘baseten org team list’ to see teams.
TEXT
Stop the command if it runs longer than this, such as 10m.
TEXT
Directory to run the command in.
BOOL
Enable verbose logging

Examples

Run a command
Run a shell pipeline as one argument
Pipe a local file into a command
Run a command in a directory with an extra environment variable

Filter output with --jq

Run a command and print its exit code

Output

Text mode (--output text): The command’s standard output on stdout and standard error on stderr, as they arrive. JSON mode (--output json): Go output type sandboxapi.ProcessResponse. The process record once the command exits, with its captured output, and nothing streamed.

connect

If the connection drops, the next keystroke reconnects to the same shell session. Press Ctrl+C or Ctrl+D to quit instead.
Opens an interactive shell in a sandbox, like SSH: full terminal output, resize handling, and interactive programs. Each connect is a new shell. Exit the shell or press Ctrl+D to disconnect. Requires an interactive terminal for both input and output; fails at once, before connecting, when either is redirected.

Options

TEXT
Filter JSON output with a jq expression; implies --output json (or jsonl for streamed commands)
TEXT
required
Name of the sandbox.
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 sandbox 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

Open a terminal to a sandbox

Output

Text mode (--output text): The sandbox’s terminal, until the shell exits.

image

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.

process

Processes are commands running, or that ran, in a sandbox. baseten sandbox process start runs one in the background; the other commands find one by --pid or by the name it was started with, --process-name.

start

Starts a command in a sandbox and returns right away, leaving it running. The argument rules of ‘sandbox exec’ apply. Follow it with ‘sandbox process logs --tail’ and wait for it with ‘sandbox process wait’.

Options

TEXT (repeatable)
Environment variable for the command as KEY=VALUE, on top of the sandbox’s own. Repeatable.
TEXT
Filter JSON output with a jq expression; implies --output json (or jsonl for streamed commands)
BOOL
Keep the sandbox from going to sleep while the process runs.
INTEGER
Most restarts with --restart-on-failure.
TEXT
required
Name of the sandbox.
TEXT
default:"text"
Output formatOne of: text, json, jsonl, none
TEXT
Name for the process, to find it later with --process-name.
TEXT
Use a specific stored profile for this command, overriding BASETEN_PROFILE and the current profile
BOOL
Restart the process when it exits with a failure.
TEXT
Team name or ID the sandbox belongs to. Defaults to your only team; required if you belong to more than one. Run ‘baseten org team list’ to see teams.
TEXT
Stop the command if it runs longer than this, such as 10m.
TEXT (repeatable)
Return only once the process listens on this port. Repeatable.
TEXT
Directory to run the command in.
BOOL
Enable verbose logging

Examples

Start a web server in the background

Filter output with --jq

Start a process and print its PID

Output

Text mode (--output text): The started process’s PID and how to follow its output. JSON mode (--output json): Go output type sandboxapi.ProcessResponse. The process record as of the start.

list

Lists every process the sandbox knows about, running and exited.

Options

TEXT
Filter JSON output with a jq expression; implies --output json (or jsonl for streamed commands)
TEXT
required
Name of the sandbox.
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 sandbox 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 processes in a sandbox

Filter output with --jq

Print every running process’s PID

Output

Text mode (--output text): Table with columns: PID, NAME, STATUS, EXIT, STARTED, COMMAND. Prints “No processes found.” to stderr when the list is empty. JSON mode (--output json): Go output type cmd.SandboxProcessList.

describe

Retrieves one process’s record, including its captured standard output and standard error as separate fields.

Options

TEXT
Filter JSON output with a jq expression; implies --output json (or jsonl for streamed commands)
TEXT
required
Name of the sandbox.
TEXT
default:"text"
Output formatOne of: text, json, jsonl, none
TEXT
PID of the process.Mutually exclusive with other flags in group process-ref.
TEXT
Name the process was started with.Mutually exclusive with other flags in group process-ref.
TEXT
Use a specific stored profile for this command, overriding BASETEN_PROFILE and the current profile
TEXT
Team name or ID the sandbox 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 a process by name

Filter output with --jq

Print a process’s standard error

Output

Text mode (--output text): One field per line describing the process, without its output. Empty fields are left out. JSON mode (--output json): Go output type sandboxapi.ProcessResponse.

logs

Prints one process’s output so far, both standard output and standard error. With --tail, prints its output from the start and then follows it until the process exits, with each line marked by its stream in JSON. For standard output and standard error as separate fields, use ‘sandbox process describe --output json’.

Options

TEXT
Filter JSON output with a jq expression; implies --output json (or jsonl for streamed commands)
TEXT
required
Name of the sandbox.
TEXT
default:"text"
Output formatOne of: text, json, jsonl, none
TEXT
PID of the process.Mutually exclusive with other flags in group process-ref.
TEXT
Name the process was started with.Mutually exclusive with other flags in group process-ref.
TEXT
Use a specific stored profile for this command, overriding BASETEN_PROFILE and the current profile
BOOL
Print the process’s output from the start, then follow it until the process exits or you interrupt with Ctrl-C. For machine-readable streaming, prefer --output jsonl over --output json.
TEXT
Team name or ID the sandbox 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 a process’s output so far
Follow a process’s output until it exits

Filter output with --jq

Print only a process’s standard error as it arrives

Output

Text mode (--output text): The process’s output lines. With --tail, standard error lines go to stderr. JSON mode (--output json): Go output type cmd.SandboxProcessLogLine. One record per line. stream is stdout or stderr with --tail, and left out otherwise, since the output so far does not say which stream a line came from.

wait

Waits for a process to exit and prints its record. The process’s exit code becomes the CLI’s exit code. Waits with no limit unless --timeout is set; neither a timeout nor Ctrl+C stops the process.

Options

TEXT
Filter JSON output with a jq expression; implies --output json (or jsonl for streamed commands)
TEXT
required
Name of the sandbox.
TEXT
default:"text"
Output formatOne of: text, json, jsonl, none
TEXT
PID of the process.Mutually exclusive with other flags in group process-ref.
TEXT
Name the process was started with.Mutually exclusive with other flags in group process-ref.
TEXT
Use a specific stored profile for this command, overriding BASETEN_PROFILE and the current profile
TEXT
Team name or ID the sandbox belongs to. Defaults to your only team; required if you belong to more than one. Run ‘baseten org team list’ to see teams.
TEXT
Fail if the process has not exited after this long, such as 30m. The process keeps running.
BOOL
Enable verbose logging

Examples

Wait for a process to exit, for up to an hour

Filter output with --jq

Wait for a process and print its output

Output

Text mode (--output text): One field per line describing the exited process, without its output. Empty fields are left out. JSON mode (--output json): Go output type sandboxapi.ProcessResponse.

stop

Requests that a process stop gracefully. Use ‘sandbox process kill’ to force it.

Options

TEXT
Filter JSON output with a jq expression; implies --output json (or jsonl for streamed commands)
TEXT
required
Name of the sandbox.
TEXT
default:"text"
Output formatOne of: text, json, jsonl, none
TEXT
PID of the process.Mutually exclusive with other flags in group process-ref.
TEXT
Name the process was started with.Mutually exclusive with other flags in group process-ref.
TEXT
Use a specific stored profile for this command, overriding BASETEN_PROFILE and the current profile
TEXT
Team name or ID the sandbox 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

Stop a process by name

Output

Text mode (--output text): A confirmation line on stderr.

kill

Requests that a process be killed at once. Use ‘sandbox process stop’ to stop it gracefully.

Options

TEXT
Filter JSON output with a jq expression; implies --output json (or jsonl for streamed commands)
TEXT
required
Name of the sandbox.
TEXT
default:"text"
Output formatOne of: text, json, jsonl, none
TEXT
PID of the process.Mutually exclusive with other flags in group process-ref.
TEXT
Name the process was started with.Mutually exclusive with other flags in group process-ref.
TEXT
Use a specific stored profile for this command, overriding BASETEN_PROFILE and the current profile
TEXT
Team name or ID the sandbox 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

Kill a process by PID

Output

Text mode (--output text): A confirmation line on stderr.

preview

Previews expose a port of a sandbox on an HTTPS URL. A public preview is reachable by anyone with the URL. A private preview, the default, needs a token from sandbox preview token create.

list

Lists a sandbox’s previews, up to --limit.

Options

TEXT
Filter JSON output with a jq expression; implies --output json (or jsonl for streamed commands)
INTEGER
default:"1000"
Most previews to list. 0 lists all.
TEXT
required
Name of the sandbox.
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 sandbox 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 a sandbox’s previews

Filter output with --jq

Print every preview’s URL

Output

Text mode (--output text): Table with columns: NAME, PORT, PUBLIC, STATUS, URL, EXPIRES. Prints “No previews found.” to stderr when the list is empty, and a note to stderr when --limit left some out. JSON mode (--output json): payload type cmd.SandboxPreviewList.

describe

Retrieves one preview’s record: URL, port, status, and headers. Request header values are masked unless --show-secrets is passed.

Options

TEXT
Filter JSON output with a jq expression; implies --output json (or jsonl for streamed commands)
TEXT
required
Name of the sandbox.
TEXT
default:"text"
Output formatOne of: text, json, jsonl, none
TEXT
required
Name of the preview.
TEXT
Use a specific stored profile for this command, overriding BASETEN_PROFILE and the current profile
BOOL
Reveal request header values. Requires the workspace administrator role; other callers still see masked values.
TEXT
Team name or ID the sandbox 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 a preview

Filter output with --jq

Print the preview’s URL

Output

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

create

Exposes a port of a sandbox on an HTTPS URL. The preview is private unless --public is passed. Port 80 and the sandbox’s reserved system ports are rejected, and port 443 must stay private.

Options

TEXT
Delete the preview at this time. ISO 8601, local when no timezone is given. Cannot be combined with --ttl.
BOOL
Return the existing preview with this name, unchanged, instead of failing.
TEXT
Filter JSON output with a jq expression; implies --output json (or jsonl for streamed commands)
TEXT
required
Name of the sandbox.
TEXT
default:"text"
Output formatOne of: text, json, jsonl, none
INTEGER
required
Sandbox port to expose.
TEXT
Name of the preview, unique within the sandbox. The server generates one when omitted.
TEXT
Use a specific stored profile for this command, overriding BASETEN_PROFILE and the current profile
BOOL
Make the URL reachable without a token.
TEXT (repeatable)
Header added to every request forwarded to the sandbox, such as an Authorization header the app expects, as KEY=VALUE. Masked when read back. Repeatable.
TEXT (repeatable)
Header added to every response the preview serves, such as a CORS header, as KEY=VALUE. Repeatable.
TEXT
Team name or ID the sandbox belongs to. Defaults to your only team; required if you belong to more than one. Run ‘baseten org team list’ to see teams.
TEXT
Delete the preview this long from now, such as 24h or 7d. Cannot be combined with --expires-at.
BOOL
Enable verbose logging

Examples

Expose port 3000 publicly for a day
Expose port 8000 privately, adding a CORS header to every response

Filter output with --jq

Create a preview and print its URL

Output

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

update

Changes a preview’s access, headers, or expiration. The URL does not change. Unset flags leave their fields unchanged. --ttl or --expires-at replaces any previous expiration.

Options

TEXT
Delete the preview at this time. ISO 8601, local when no timezone is given. Cannot be combined with --ttl.
TEXT
Filter JSON output with a jq expression; implies --output json (or jsonl for streamed commands)
TEXT
required
Name of the sandbox.
TEXT
default:"text"
Output formatOne of: text, json, jsonl, none
TEXT
required
Name of the preview.
BOOL
Require a token to reach the URL. Cannot be combined with --public.
TEXT
Use a specific stored profile for this command, overriding BASETEN_PROFILE and the current profile
BOOL
Make the URL reachable without a token. Cannot be combined with --private.
TEXT (repeatable)
Header added to every request forwarded to the sandbox, as KEY=VALUE, replacing all of the preview’s request headers. Repeatable.
TEXT (repeatable)
Header added to every response the preview serves, as KEY=VALUE, replacing all of the preview’s response headers. Repeatable.
TEXT
Team name or ID the sandbox belongs to. Defaults to your only team; required if you belong to more than one. Run ‘baseten org team list’ to see teams.
TEXT
Delete the preview this long from now, such as 24h or 7d. Cannot be combined with --expires-at.
BOOL
Enable verbose logging

Examples

Make a preview private

Filter output with --jq

Make a preview public and print whether it is

Output

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

delete

Deletes a preview and its tokens. The URL stops serving at once.

Options

TEXT
Filter JSON output with a jq expression; implies --output json (or jsonl for streamed commands)
TEXT
required
Name of the sandbox.
TEXT
default:"text"
Output formatOne of: text, json, jsonl, none
TEXT
required
Name of the preview.
TEXT
Use a specific stored profile for this command, overriding BASETEN_PROFILE and the current profile
TEXT
Team name or ID the sandbox 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 a preview without the confirmation prompt

Filter output with --jq

Delete a preview and print its status

Output

Text mode (--output text): A confirmation line on stderr. JSON mode (--output json): payload type managementapi.SandboxPreview. The preview’s record as of deletion.

preview token

Tokens grant access to a private preview until they expire. Append one to the preview URL as ?preview_token=<token>; the first request sets a cookie so a browser can keep navigating without it.

create

Creates a token granting access to a private preview until --expires-at.

Options

TEXT
required
Time the token stops working. ISO 8601, local when no timezone is given.
BOOL
Return an existing unexpired token of the preview that stays valid at least until --expires-at, instead of creating one. A token created moments before may not be found yet, so a new one may be created anyway.
TEXT
Filter JSON output with a jq expression; implies --output json (or jsonl for streamed commands)
TEXT
required
Name of the sandbox.
TEXT
default:"text"
Output formatOne of: text, json, jsonl, none
TEXT
required
Name of the preview.
TEXT
Use a specific stored profile for this command, overriding BASETEN_PROFILE and the current profile
TEXT
Team name or ID the sandbox 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

Create a token valid until a given time

Filter output with --jq

Create a token and print it

Output

Text mode (--output text): One field per line describing the token, then the preview URL with the token appended. JSON mode (--output json): payload type managementapi.SandboxPreviewToken.

list

Lists a private preview’s tokens, including expired ones until they are removed. A public preview has no tokens.

Options

TEXT
Filter JSON output with a jq expression; implies --output json (or jsonl for streamed commands)
TEXT
required
Name of the sandbox.
TEXT
default:"text"
Output formatOne of: text, json, jsonl, none
TEXT
required
Name of the preview.
TEXT
Use a specific stored profile for this command, overriding BASETEN_PROFILE and the current profile
TEXT
Team name or ID the sandbox 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 a preview’s tokens

Filter output with --jq

Print every unexpired token’s name

Output

Text mode (--output text): Table with columns: NAME, EXPIRES, EXPIRED. Prints “No tokens found.” to stderr when the list is empty. JSON mode (--output json): payload type cmd.SandboxPreviewTokenList.

delete

Revokes a token. Requests using it are rejected at once.

Options

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

Examples

Delete a token without the confirmation prompt

Output

Text mode (--output text): A confirmation line on stderr.

volume

A sandbox volume is a persistent disk that keeps its data after the sandboxes that mounted it are gone. The volume belongs to one region. Only sandboxes in that region can mount it, and one sandbox mounts it at a time. A volume can grow but never shrink. Create a volume, check that it is ready with sandbox volume describe, then mount it when you create a sandbox:

list

Lists the team’s volumes, newest first, up to --limit. Filter by free-text --query or repeatable --status. The table leaves labels out; read them with sandbox volume describe.

Options

TEXT
Filter JSON output with a jq expression; implies --output json (or jsonl for streamed commands)
INTEGER
default:"1000"
Most sandbox volumes 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
Search over sandbox volume names.
TEXT (repeatable)
Only sandbox volumes with one of these statuses. Repeatable.One of: deleting, deployed, deploying, failed
TEXT
Team name or ID to list sandbox volumes 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 only volumes that failed to deploy

Filter output with --jq

Print the name of every volume that no sandbox mounts

Output

Text mode (--output text): Table with columns: NAME, STATUS, SIZE, REGION, ATTACHED TO, CREATED. Prints “No sandbox volumes 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.SandboxVolumeList.

describe

Retrieves one volume’s record: status, size, region, the sandbox it is mounted in, and labels.

Options

TEXT
Filter JSON output with a jq expression; implies --output json (or jsonl for streamed commands)
TEXT
required
Name of the sandbox volume.
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 sandbox volume 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 a volume before mounting it

Filter output with --jq

Print the sandbox the volume is mounted in

Output

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

create

Creates a volume and prints its record. Provisioning runs in the background, so the status may still be DEPLOYING when the command returns; check it with sandbox volume describe before you mount the volume.

Options

TEXT
Filter JSON output with a jq expression; implies --output json (or jsonl for streamed commands)
TEXT (repeatable)
Label as KEY=VALUE. Repeatable.
TEXT
Unique name of the sandbox volume. The server generates one when omitted.
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
Region of the sandbox volume. Only sandboxes in the same region can mount it. Defaults to the default sandbox region.
TEXT
required
Capacity, as a size (10Gi) or Mi (10240). It can grow later but never shrink.
TEXT
Team name or ID to create the sandbox volume in. 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

Create a 10 GiB volume in a specific region with labels

Filter output with --jq

Create a volume and print its status

Output

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

update

Grows a volume or replaces its labels. Omitted flags leave their fields unchanged. A volume can grow but never shrink. Any --label replaces all of its labels, and --clear-labels removes them all.

Options

BOOL
Remove all of the sandbox volume’s labels. Cannot be combined with --label.
TEXT
Filter JSON output with a jq expression; implies --output json (or jsonl for streamed commands)
TEXT (repeatable)
Label as KEY=VALUE, replacing all of the sandbox volume’s labels. Repeatable. Cannot be combined with --clear-labels.
TEXT
required
Name of the sandbox volume.
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
New capacity, as a size (20Gi) or Mi (20480), no less than the current capacity.
TEXT
Team name or ID the sandbox volume 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

Grow a volume to 20 GiB

Filter output with --jq

Grow a volume and print its size

Output

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

delete

Deletes a volume and all of its data. The command fails while a sandbox mounts the volume, and deletion continues after it returns. Prompts for yes/no confirmation. Pass --yes to skip the prompt. When stdin is not a terminal, --yes is required.

Options

TEXT
Filter JSON output with a jq expression; implies --output json (or jsonl for streamed commands)
TEXT
required
Name of the sandbox volume.
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 sandbox volume 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 a volume without the confirmation prompt

Filter output with --jq

Print the status of the volume as deletion starts

Output

Text mode (--output text): A confirmation line on stderr. JSON mode (--output json): Go output type managementapi.SandboxVolume, holding the volume’s record as deletion starts.