PRE-RELEASE: Sandbox commands are not GA yet. Their arguments, flags, and output may change.
baseten sandbox exec, and delete it when done.
list
--limit. Filter by free-text --query or repeatable --status.
Options
Use a specific stored profile for this command, overriding BASETEN_PROFILE and the current profile
Only sandboxes with one of these statuses. Repeatable.One of:
archived, archiving, building, deactivated, deactivating, deleting, deployed, deploying, failed, terminated, unarchiving, uploadingTeam 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.
Examples
List sandboxesFilter 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
--show-secrets is passed.
Options
Use a specific stored profile for this command, overriding BASETEN_PROFILE and the current profile
Reveal secret environment variable values. Requires the workspace administrator role; other callers still see masked values.
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.
Examples
Describe a sandboxFilter 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
--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
Maximum memory the filesystem can use, as a percentage of memory (80%), a size (2Gi), or Mi (2048). Defaults to 50%.
Return the existing sandbox with this name instead of failing, or recreate it if it is failed, terminated, or being deleted.
Environment variable that is not secret, as KEY=VALUE, readable when read back. Repeatable.
Use a specific stored profile for this command, overriding BASETEN_PROFILE and the current profile
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.
How long to keep the sandbox’s record after it terminates, for log access, such as 1h or 7d. The server defaults to 5m.
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.
Examples
Create a sandbox with a generated name and server defaultsFilter 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
--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
Label as KEY=VALUE, replacing all of the sandbox’s labels. Repeatable. Cannot be combined with
--clear-labels.Environment variable that is not secret, as KEY=VALUE, readable when read back. Repeatable.
Use a specific stored profile for this command, overriding BASETEN_PROFILE and the current profile
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.
How long to keep the sandbox’s record after it terminates, for log access, such as 1h or 7d. The server defaults to 5m.
Examples
Replace a sandbox’s labelsFilter 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
Options
Use a specific stored profile for this command, overriding BASETEN_PROFILE and the current profile
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.
Examples
Delete a sandbox without the confirmation promptFilter 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
--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
Environment variable for the command as KEY=VALUE, on top of the sandbox’s own. Repeatable.
Use a specific stored profile for this command, overriding BASETEN_PROFILE and the current profile
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.
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.
Examples
Run a commandFilter 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.Options
Use a specific stored profile for this command, overriding BASETEN_PROFILE and the current profile
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.
Examples
Open a terminal to a sandboxOutput
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
--limit.
Options
Use a specific stored profile for this command, overriding BASETEN_PROFILE and the current profile
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.
Examples
List imagesFilter 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
Options
Use a specific stored profile for this command, overriding BASETEN_PROFILE and the current profile
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.
Examples
Describe an imageFilter 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
--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
Directory to build the image from, with a Dockerfile at its root.Mutually exclusive with other flags in group
image-source.Path to a Docker config.json with credentials for pulling
--registry-image from a private registry.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.
Use a specific stored profile for this command, overriding BASETEN_PROFILE and the current profile
Registry image reference to import, such as registry.example.com/app:v1.Mutually exclusive with other flags in group
image-source.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.
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.
Wait until the image is built. Exits non-zero if the build fails. Does not stop the build if interrupted.
Examples
Build an image from the current directory and wait for itFilter 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
Options
Use a specific stored profile for this command, overriding BASETEN_PROFILE and the current profile
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.
Examples
Delete an image without the confirmation promptFilter 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
Options
Use a specific stored profile for this command, overriding BASETEN_PROFILE and the current profile
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.
Examples
Print an image’s build logsFilter 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
--image name:tag.
Options
Use a specific stored profile for this command, overriding BASETEN_PROFILE and the current profile
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.
Examples
List an image’s tagsFilter 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
--image to ‘sandbox create’.
Options
Use a specific stored profile for this command, overriding BASETEN_PROFILE and the current profile
Examples
List the starter imagesFilter 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
--tail’ and wait for it with ‘sandbox process wait’.
Options
Environment variable for the command as KEY=VALUE, on top of the sandbox’s own. Repeatable.
Use a specific stored profile for this command, overriding BASETEN_PROFILE and the current profile
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.
Examples
Start a web server in the backgroundFilter 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
Options
Use a specific stored profile for this command, overriding BASETEN_PROFILE and the current profile
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.
Examples
List processes in a sandboxFilter 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
Options
Use a specific stored profile for this command, overriding BASETEN_PROFILE and the current profile
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.
Examples
Describe a process by nameFilter 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
--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
Use a specific stored profile for this command, overriding BASETEN_PROFILE and the current profile
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.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.
Examples
Print a process’s output so farFilter 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
--timeout is set; neither a timeout nor Ctrl+C stops the process.
Options
Use a specific stored profile for this command, overriding BASETEN_PROFILE and the current profile
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.
Examples
Wait for a process to exit, for up to an hourFilter 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
Options
Use a specific stored profile for this command, overriding BASETEN_PROFILE and the current profile
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.
Examples
Stop a process by nameOutput
Text mode (--output text): A confirmation line on stderr.
kill
Options
Use a specific stored profile for this command, overriding BASETEN_PROFILE and the current profile
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.
Examples
Kill a process by PIDOutput
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 fromsandbox preview token create.
list
--limit.
Options
Use a specific stored profile for this command, overriding BASETEN_PROFILE and the current profile
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.
Examples
List a sandbox’s previewsFilter 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
--show-secrets is passed.
Options
Use a specific stored profile for this command, overriding BASETEN_PROFILE and the current profile
Reveal request header values. Requires the workspace administrator role; other callers still see masked values.
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.
Examples
Describe a previewFilter 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
--public is passed. Port 80 and the sandbox’s reserved system ports are rejected, and port 443 must stay private.
Options
Delete the preview at this time. ISO 8601, local when no timezone is given. Cannot be combined with
--ttl.Use a specific stored profile for this command, overriding BASETEN_PROFILE and the current profile
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.
Header added to every response the preview serves, such as a CORS header, as KEY=VALUE. Repeatable.
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.
Examples
Expose port 3000 publicly for a dayFilter 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
--ttl or --expires-at replaces any previous expiration.
Options
Delete the preview at this time. ISO 8601, local when no timezone is given. Cannot be combined with
--ttl.Use a specific stored profile for this command, overriding BASETEN_PROFILE and the current profile
Header added to every request forwarded to the sandbox, as KEY=VALUE, replacing all of the preview’s request headers. Repeatable.
Header added to every response the preview serves, as KEY=VALUE, replacing all of the preview’s response headers. Repeatable.
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.
Examples
Make a preview privateFilter 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
Options
Use a specific stored profile for this command, overriding BASETEN_PROFILE and the current profile
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.
Examples
Delete a preview without the confirmation promptFilter 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
--expires-at.
Options
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.Use a specific stored profile for this command, overriding BASETEN_PROFILE and the current profile
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.
Examples
Create a token valid until a given timeFilter 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
Options
Use a specific stored profile for this command, overriding BASETEN_PROFILE and the current profile
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.
Examples
List a preview’s tokensFilter 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
Options
Use a specific stored profile for this command, overriding BASETEN_PROFILE and the current profile
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.
Examples
Delete a token without the confirmation promptOutput
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 withsandbox volume describe, then mount it when you create a sandbox:
list
--limit. Filter by free-text --query or repeatable --status. The table leaves labels out; read them with sandbox volume describe.
Options
Use a specific stored profile for this command, overriding BASETEN_PROFILE and the current profile
Only sandbox volumes with one of these statuses. Repeatable.One of:
deleting, deployed, deploying, failedTeam 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.
Examples
List only volumes that failed to deployFilter 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
Options
Use a specific stored profile for this command, overriding BASETEN_PROFILE and the current profile
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.
Examples
Describe a volume before mounting itFilter 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
DEPLOYING when the command returns; check it with sandbox volume describe before you mount the volume.
Options
Use a specific stored profile for this command, overriding BASETEN_PROFILE and the current profile
Region of the sandbox volume. Only sandboxes in the same region can mount it. Defaults to the default sandbox region.
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.
Examples
Create a 10 GiB volume in a specific region with labelsFilter 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
--label replaces all of its labels, and --clear-labels removes them all.
Options
Label as KEY=VALUE, replacing all of the sandbox volume’s labels. Repeatable. Cannot be combined with
--clear-labels.Use a specific stored profile for this command, overriding BASETEN_PROFILE and the current profile
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.
Examples
Grow a volume to 20 GiBFilter 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
--yes to skip the prompt. When stdin is not a terminal, --yes is required.
Options
Use a specific stored profile for this command, overriding BASETEN_PROFILE and the current profile
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.
Examples
Delete a volume without the confirmation promptFilter 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.