rwx sandbox background

Start or replace a managed background process in an existing sandbox.

Usage

rwx sandbox background [config-file] --key <key> [options] -- <command>

Description

Sync local changes, then start a command that continues running in the sandbox after the CLI returns. Each process has a key. Starting another command with the same key replaces the existing process.

When you provide --port, the CLI forwards that sandbox port to your local machine, waits for it to accept connections, and prints a local preview URL.

To forward a port for an already-running process without replacing it, use rwx sandbox tunnel. The logs, restart, and stop subcommands also work with processes declared in the sandbox task's background-processes, using their configured keys.

An active sandbox is required. Start one with rwx sandbox start, or create one while executing a command with rwx sandbox exec.

Subcommands

  • logs - Show logs for a background process
  • restart - Sync changes and restart a background process
  • stop - Stop a background process

Arguments

[config-file]

The path to the sandbox configuration file used to select an existing sandbox. Defaults to .rwx/sandbox.yml. --id takes precedence.

<command>

(required) The command to run in the background. Must be preceded by --.

Options

--key <key>

(required) The key of the managed process. A key can contain letters, numbers, underscores, and hyphens, up to 255 bytes. The deprecated --name flag is an alias for --key; do not pass both.

--port <port>

The sandbox port to forward to your local machine. If omitted, the process starts without a local port forward, and any existing tunnel for this key is closed.

--local-port <port>

The local port for the forwarded connection. By default, the CLI allocates a port or reuses the existing one for this process. Requires --port.

--scheme <scheme>

The URL scheme to print for the forwarded port: http or https. Defaults to http. This option does not add TLS to the application. Requires --port.

--id <run-id>

Use a specific sandbox session.

Global options

--format <format>

Output format: text or json. Defaults to text.

--json

Output JSON data to stdout. Equivalent to --format json.

--access-token <token>

The access token for RWX. Defaults to the value of the $RWX_ACCESS_TOKEN environment variable.