baseten sandbox process

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

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

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

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)

BOOL

Keep the sandbox from going to sleep while the process runs.

INTEGER

Most restarts with —restart-on-failure.

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

Restart the process when it exits with a failure.

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 (repeatable)

Return only once the process listens on this port. Repeatable.

TEXT

Directory to run the command in.

BOOL

Enable verbose logging

Examples

Start a web server in the background

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

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

baseten sandbox process list [OPTIONS]

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

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

List processes in a sandbox

baseten sandbox process list --name my-sandbox

Filter output with `--jq`

Print every running process’s PID

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

baseten sandbox process describe [OPTIONS]

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

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

PID of the process.Mutually exclusive with other flags in group process-ref.

TEXT

Name the process was started with.Mutually exclusive with other flags in group process-ref.

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

Describe a process by name

baseten sandbox process describe --name my-sandbox --process-name web

Filter output with `--jq`

Print a process’s standard error

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

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

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

PID of the process.Mutually exclusive with other flags in group process-ref.

TEXT

Name the process was started with.Mutually exclusive with other flags in group process-ref.

TEXT

Use a specific stored profile for this command, overriding BASETEN_PROFILE and the current profile

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.

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

Print a process’s output so far

baseten sandbox process logs --name my-sandbox --pid 42

Follow a process’s output until it exits

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

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

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

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

PID of the process.Mutually exclusive with other flags in group process-ref.

TEXT

Name the process was started with.Mutually exclusive with other flags in group process-ref.

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.

TEXT

Fail if the process has not exited after this long, such as 30m. The process keeps running.

BOOL

Enable verbose logging

Examples

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

baseten sandbox process wait --name my-sandbox --pid 42 --timeout 1h

Filter output with `--jq`

Wait for a process and print its output

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

baseten sandbox process stop [OPTIONS]

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

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

PID of the process.Mutually exclusive with other flags in group process-ref.

TEXT

Name the process was started with.Mutually exclusive with other flags in group process-ref.

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

Stop a process by name

baseten sandbox process stop --name my-sandbox --process-name web

Output

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

kill

baseten sandbox process kill [OPTIONS]

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

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

PID of the process.Mutually exclusive with other flags in group process-ref.

TEXT

Name the process was started with.Mutually exclusive with other flags in group process-ref.

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

Kill a process by PID

baseten sandbox process kill --name my-sandbox --pid 42

Output

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

​start

​Options

​Examples

​Filter output with --jq

​Output

​list

​Options

​Examples

​Filter output with --jq

​Output

​describe

​Options

​Examples

​Filter output with --jq

​Output

​logs

​Options

​Examples

​Filter output with --jq

​Output

​wait

​Options

​Examples

​Filter output with --jq

​Output

​stop

​Options

​Examples

​Output

​kill

​Options

​Examples

​Output

start

Options

Examples

Filter output with `--jq`

Output

list

Options

Examples

Filter output with `--jq`

Output

describe

Options

Examples

Filter output with `--jq`

Output

logs

Options

Examples

Filter output with `--jq`

Output

wait

Options

Examples

Filter output with `--jq`

Output

stop

Options

Examples

Output

kill

Options

Examples

Output