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

> Manage sandboxes (PRE-RELEASE)

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

Sandboxes run arbitrary commands in isolated environments. Create one, run commands in it with 'sandbox exec', and delete it when done.

## list

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

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

### 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 sandboxes 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="--query" type="TEXT">
  Free-text search over sandbox names and labels.
</ParamField>

<ParamField body="--status" type="TEXT (repeatable)">
  Only sandboxes with one of these statuses. Repeatable.

  One of: `archived`, `archiving`, `building`, `deactivated`, `deactivating`, `deleting`, `deployed`, `deploying`, `failed`, `terminated`, `unarchiving`, `uploading`
</ParamField>

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

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

### Examples

List sandboxes

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

List only deployed sandboxes

```sh theme={"system"}
baseten sandbox list --status deployed
```

### Filter output with `--jq`

Print every sandbox's URL

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

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

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

<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 sandbox.
</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="--show-secrets" type="BOOL">
  Reveal secret environment variable values. Requires the workspace administrator role; other callers still see masked values.
</ParamField>

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

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

### Examples

Describe a sandbox

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

### Filter output with `--jq`

Print the sandbox's URL

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

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

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

<ParamField body="--env" type="TEXT (repeatable)">
  Secret environment variable as KEY=VALUE, masked when read back. Repeatable.
</ParamField>

<ParamField body="--if-not-exists" type="BOOL">
  Return the existing sandbox with this name instead of failing, or recreate it if it is failed, terminated, or being deleted.
</ParamField>

<ParamField body="--image" type="TEXT">
  Image to create the sandbox from, including its tag, such as my-image:latest.
</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="--label" type="TEXT (repeatable)">
  Label as KEY=VALUE. Repeatable.
</ParamField>

<ParamField body="--memory" type="INTEGER">
  Memory in MB, which also sets the CPU allocation.
</ParamField>

<ParamField body="--name" type="TEXT">
  Unique name of the sandbox. The server generates one when omitted.
</ParamField>

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

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

<ParamField body="--plain-env" type="TEXT (repeatable)">
  Environment variable that is not secret, as KEY=VALUE, readable when read back. Repeatable.
</ParamField>

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

<ParamField body="--region" type="TEXT">
  Region to create the sandbox in.
</ParamField>

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

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

### Examples

Create a sandbox with a generated name and server defaults

```sh theme={"system"}
baseten sandbox create
```

Create a named sandbox, or get it back if it already exists

```sh theme={"system"}
baseten sandbox create --name my-sandbox --if-not-exists
```

Create one in a specific region with more memory

```sh theme={"system"}
baseten sandbox create --name my-sandbox --region us-was-1 --memory 8192
```

Create one with environment variables and labels

```sh theme={"system"}
baseten sandbox create --name worker --env API_TOKEN=secret --plain-env WORKERS=4 --label team=cli
```

### Filter output with `--jq`

Create a sandbox and print its generated name

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

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

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

<ParamField body="--env" type="TEXT (repeatable)">
  Secret environment variable as KEY=VALUE, masked when read back. Repeatable.
</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="--label" type="TEXT (repeatable)">
  Label as KEY=VALUE, replacing all of the sandbox's labels. Repeatable.
</ParamField>

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

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

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

<ParamField body="--plain-env" type="TEXT (repeatable)">
  Environment variable that is not secret, as KEY=VALUE, readable when read back. Repeatable.
</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 sandbox 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

Replace a sandbox's labels

```sh theme={"system"}
baseten sandbox update --name my-sandbox --label env=dev
```

### Filter output with `--jq`

Replace a sandbox's labels and print them

```sh theme={"system"}
baseten sandbox update --name my-sandbox --label env=dev --jq '.labels'
```

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

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

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

### 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 sandbox.
</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 sandbox 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 a sandbox without the confirmation prompt

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

### Filter output with `--jq`

Delete a sandbox and print its status

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

```sh theme={"system"}
baseten sandbox exec [OPTIONS] -- COMMAND [ARGS...]
```

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

<ParamField body="--env" type="TEXT (repeatable)">
  Environment variable for the command as KEY=VALUE, on top of the sandbox's own. Repeatable.
</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 sandbox.
</ParamField>

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

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

<ParamField body="--process-name" type="TEXT">
  Name for the process, to find it later with --process-name.
</ParamField>

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

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

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

<ParamField body="--timeout" type="TEXT">
  Stop the command if it runs longer than this, such as 10m.
</ParamField>

<ParamField body="--working-dir" type="TEXT">
  Directory to run the command in.
</ParamField>

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

### Examples

Run a command

```sh theme={"system"}
baseten sandbox exec --name my-sandbox -- ls -la /tmp
```

Run a shell pipeline as one argument

```sh theme={"system"}
baseten sandbox exec --name my-sandbox -- 'ps aux | grep python'
```

Pipe a local file into a command

```sh theme={"system"}
baseten sandbox exec --name my-sandbox --stdin -- wc -l < data.csv
```

Run a command in a directory with an extra environment variable

```sh theme={"system"}
baseten sandbox exec --name my-sandbox --working-dir /app --env DEBUG=1 -- python main.py
```

### Filter output with `--jq`

Run a command and print its exit code

```sh theme={"system"}
baseten sandbox exec --name my-sandbox --jq '.exitCode' -- false
```

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

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

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

<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 sandbox.
</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 sandbox 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

Open a terminal to a sandbox

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

### Output

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