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

> Manage sandbox previews (PRE-RELEASE)

> [!NOTE]
>
> PRE-RELEASE: Sandbox commands are not GA yet. Their arguments, flags, and output may change.

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

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

Lists a sandbox's previews, up to `--limit`.

### Options

**-q, --jq** `TEXT`

Filter JSON output with a jq expression; implies --output json (or jsonl for streamed commands)

**--limit** `INTEGER` (default: 1000)

Most previews to list. 0 lists all.

**--name** `TEXT` *required*

Name of the sandbox.

**-o, --output** `TEXT` (default: text)

Output format

One of: `text`, `json`, `jsonl`, `none`

**--profile** `TEXT`

Use a specific stored profile for this command, overriding BASETEN\_PROFILE and the current profile

**--team** `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.

**-v, --verbose** `BOOL`

Enable verbose logging

### Examples

List a sandbox's previews

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

### Filter output with `--jq`

Print every preview's URL

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

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

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

### Options

**-q, --jq** `TEXT`

Filter JSON output with a jq expression; implies --output json (or jsonl for streamed commands)

**--name** `TEXT` *required*

Name of the sandbox.

**-o, --output** `TEXT` (default: text)

Output format

One of: `text`, `json`, `jsonl`, `none`

**--preview-name** `TEXT` *required*

Name of the preview.

**--profile** `TEXT`

Use a specific stored profile for this command, overriding BASETEN\_PROFILE and the current profile

**--show-secrets** `BOOL`

Reveal request header values. Requires the workspace administrator role; other callers still see masked values.

**--team** `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.

**-v, --verbose** `BOOL`

Enable verbose logging

### Examples

Describe a preview

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

### Filter output with `--jq`

Print the preview's URL

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

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

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

**--expires-at** `TEXT`

Delete the preview at this time. ISO 8601, local when no timezone is given. Cannot be combined with --ttl.

**--if-not-exists** `BOOL`

Return the existing preview with this name, unchanged, instead of failing.

**-q, --jq** `TEXT`

Filter JSON output with a jq expression; implies --output json (or jsonl for streamed commands)

**--name** `TEXT` *required*

Name of the sandbox.

**-o, --output** `TEXT` (default: text)

Output format

One of: `text`, `json`, `jsonl`, `none`

**--port** `INTEGER` *required*

Sandbox port to expose.

**--preview-name** `TEXT`

Name of the preview, unique within the sandbox. The server generates one when omitted.

**--profile** `TEXT`

Use a specific stored profile for this command, overriding BASETEN\_PROFILE and the current profile

**--public** `BOOL`

Make the URL reachable without a token.

**--request-header** `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.

**--response-header** `TEXT (repeatable)`

Header added to every response the preview serves, such as a CORS header, as KEY=VALUE. Repeatable.

**--team** `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.

**--ttl** `TEXT`

Delete the preview this long from now, such as 24h or 7d. Cannot be combined with --expires-at.

**-v, --verbose** `BOOL`

Enable verbose logging

### Examples

Expose port 3000 publicly for a day

```sh theme={"system"}
baseten sandbox preview create --name my-sandbox --port 3000 --public --ttl 24h
```

Expose port 8000 privately, adding a CORS header to every response

```sh theme={"system"}
baseten sandbox preview create --name my-sandbox --port 8000 --preview-name api --response-header Access-Control-Allow-Origin='*'
```

### Filter output with `--jq`

Create a preview and print its URL

```sh theme={"system"}
baseten sandbox preview create --name my-sandbox --port 3000 --public --jq '.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

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

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

**--expires-at** `TEXT`

Delete the preview at this time. ISO 8601, local when no timezone is given. Cannot be combined with --ttl.

**-q, --jq** `TEXT`

Filter JSON output with a jq expression; implies --output json (or jsonl for streamed commands)

**--name** `TEXT` *required*

Name of the sandbox.

**-o, --output** `TEXT` (default: text)

Output format

One of: `text`, `json`, `jsonl`, `none`

**--preview-name** `TEXT` *required*

Name of the preview.

**--private** `BOOL`

Require a token to reach the URL. Cannot be combined with --public.

**--profile** `TEXT`

Use a specific stored profile for this command, overriding BASETEN\_PROFILE and the current profile

**--public** `BOOL`

Make the URL reachable without a token. Cannot be combined with --private.

**--request-header** `TEXT (repeatable)`

Header added to every request forwarded to the sandbox, as KEY=VALUE, replacing all of the preview's request headers. Repeatable.

**--response-header** `TEXT (repeatable)`

Header added to every response the preview serves, as KEY=VALUE, replacing all of the preview's response headers. Repeatable.

**--team** `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.

**--ttl** `TEXT`

Delete the preview this long from now, such as 24h or 7d. Cannot be combined with --expires-at.

**-v, --verbose** `BOOL`

Enable verbose logging

### Examples

Make a preview private

```sh theme={"system"}
baseten sandbox preview update --name my-sandbox --preview-name web --private
```

### Filter output with `--jq`

Make a preview public and print whether it is

```sh theme={"system"}
baseten sandbox preview update --name my-sandbox --preview-name web --public --jq '.public'
```

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

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

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

### Options

**-q, --jq** `TEXT`

Filter JSON output with a jq expression; implies --output json (or jsonl for streamed commands)

**--name** `TEXT` *required*

Name of the sandbox.

**-o, --output** `TEXT` (default: text)

Output format

One of: `text`, `json`, `jsonl`, `none`

**--preview-name** `TEXT` *required*

Name of the preview.

**--profile** `TEXT`

Use a specific stored profile for this command, overriding BASETEN\_PROFILE and the current profile

**--team** `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.

**--yes** `BOOL`

Skip the interactive confirmation prompt. Required when stdin is not a terminal.

**-v, --verbose** `BOOL`

Enable verbose logging

### Examples

Delete a preview without the confirmation prompt

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

### Filter output with `--jq`

Delete a preview and print its status

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