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 ‘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, region, 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.

​
Options

​
TEXT (repeatable)
Secret environment variable as KEY=VALUE, masked when read back. Repeatable.
​
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.
​
INTEGER
Memory in MB, which also sets 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.
​
BOOL
Enable verbose logging

​
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 memory
Create one with environment variables and labels

​
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 or labels. Omitted flags leave their fields unchanged. Any —env or —plain-env replaces all of the sandbox’s environment variables, and any —label replaces all of its labels.

​
Options

​
TEXT (repeatable)
Secret environment variable as KEY=VALUE, masked when read back. Repeatable.
​
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.
​
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.
​
BOOL
Enable verbose logging

​
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

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.