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

> Run and inspect processes in a sandbox (PRE-RELEASE)

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

Processes are commands running, or that ran, in a 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

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

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

<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="--keep-alive" type="BOOL">
  Keep the sandbox from going to sleep while the process runs.
</ParamField>

<ParamField body="--max-restarts" type="INTEGER">
  Most restarts with --restart-on-failure.
</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="--restart-on-failure" type="BOOL">
  Restart the process when it exits with a failure.
</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="--wait-for-port" type="TEXT (repeatable)">
  Return only once the process listens on this port. Repeatable.
</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

Start a web server in the background

```sh theme={"system"}
baseten sandbox process start --name my-sandbox --process-name web --wait-for-port 8000 -- python -m http.server 8000
```

### Filter output with `--jq`

Start a process and print its PID

```sh theme={"system"}
baseten sandbox process start --name my-sandbox --jq '.pid' -- sleep 60
```

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

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

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

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

List processes in a sandbox

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

### Filter output with `--jq`

Print every running process's PID

```sh theme={"system"}
baseten sandbox process list --name my-sandbox --jq '.items[] | select(.status == "running") | .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

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

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

### 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="--pid" type="TEXT">
  PID of the process.

  Mutually exclusive with other flags in group `process-ref`.
</ParamField>

<ParamField body="--process-name" type="TEXT">
  Name the process was started with.

  Mutually exclusive with other flags in group `process-ref`.
</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

Describe a process by name

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

### Filter output with `--jq`

Print a process's standard error

```sh theme={"system"}
baseten sandbox process describe --name my-sandbox --pid 42 --jq '.stderr'
```

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

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

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

<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="--pid" type="TEXT">
  PID of the process.

  Mutually exclusive with other flags in group `process-ref`.
</ParamField>

<ParamField body="--process-name" type="TEXT">
  Name the process was started with.

  Mutually exclusive with other flags in group `process-ref`.
</ParamField>

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

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

Print a process's output so far

```sh theme={"system"}
baseten sandbox process logs --name my-sandbox --pid 42
```

Follow a process's output until it exits

```sh theme={"system"}
baseten sandbox process logs --name my-sandbox --process-name web --tail
```

### Filter output with `--jq`

Print only a process's standard error as it arrives

```sh theme={"system"}
baseten sandbox process logs --name my-sandbox --pid 42 --tail --jq 'select(.stream == "stderr") | .text'
```

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

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

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

<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="--pid" type="TEXT">
  PID of the process.

  Mutually exclusive with other flags in group `process-ref`.
</ParamField>

<ParamField body="--process-name" type="TEXT">
  Name the process was started with.

  Mutually exclusive with other flags in group `process-ref`.
</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="--timeout" type="TEXT">
  Fail if the process has not exited after this long, such as 30m. The process keeps running.
</ParamField>

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

### Examples

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

```sh theme={"system"}
baseten sandbox process wait --name my-sandbox --pid 42 --timeout 1h
```

### Filter output with `--jq`

Wait for a process and print its output

```sh theme={"system"}
baseten sandbox process wait --name my-sandbox --pid 42 --jq '.logs'
```

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

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

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

### 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="--pid" type="TEXT">
  PID of the process.

  Mutually exclusive with other flags in group `process-ref`.
</ParamField>

<ParamField body="--process-name" type="TEXT">
  Name the process was started with.

  Mutually exclusive with other flags in group `process-ref`.
</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

Stop a process by name

```sh theme={"system"}
baseten sandbox process stop --name my-sandbox --process-name web
```

### Output

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

## kill

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

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

### 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="--pid" type="TEXT">
  PID of the process.

  Mutually exclusive with other flags in group `process-ref`.
</ParamField>

<ParamField body="--process-name" type="TEXT">
  Name the process was started with.

  Mutually exclusive with other flags in group `process-ref`.
</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

Kill a process by PID

```sh theme={"system"}
baseten sandbox process kill --name my-sandbox --pid 42
```

### Output

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