CLI Reference - Run Cloud

This is the reference for the latest runcloud command-line interface. Install it from npm:

npm install -g runcloud

Use runcloud --version to print the installed version and runcloud <command> --help to inspect the exact options supported by that version.

Authentication

Command	Description
`runcloud login`	Sign in through the browser and save the CLI credential.
`runcloud logout`	Delete the saved CLI credential.
`runcloud account`	Show account access, organizations, balance, and metering status.

Use runcloud login --manual when the browser cannot return to the local callback automatically. runcloud account --json returns machine-readable output.

Mobile sessions

The iOS and Android command groups share the same lifecycle:

Command	Description
`runcloud ios create`	Create an iOS simulator session.
`runcloud ios list`	List active iOS sessions. Pass `--all` to include released sessions.
`runcloud ios get <id>`	Get one iOS session.
`runcloud ios open-url <url> --id <id>`	Open an HTTP URL or deep link.
`runcloud ios delete <id>`	Release an iOS session.
`runcloud android create`	Create an Android emulator session.
`runcloud android list`	List active Android sessions. Pass `--all` to include released sessions.
`runcloud android get <id>`	Get one Android session.
`runcloud android open-url <url> --id <id>`	Open an HTTP URL or deep link.
`runcloud android delete <id>`	Release an Android session.

ios create and android create accept:

Option	Description
`--model <model>`	Select a device model.
`--region <region>`	Request a fleet region.
`--display-name <name>`	Add a human-readable session name.
`--label <key=value>`	Attach a label. Repeat the option for multiple labels.
`--install <file>`	Upload and install a local app artifact. Repeat for multiple artifacts.
`--install-asset <name-or-id>`	Install a previously uploaded asset.
`--inactivity-timeout <duration>`	Release an idle session after a duration such as `60s` or `3m`; use `none` to disable.
`--hard-timeout <duration>`	Set the maximum session lifetime, such as `10m` or `1h`.
`--codec <auto\|mjpeg\|webrtc>`	Select the viewer stream codec.
`--rm`	Release the session when the command exits.
`--json`	Return JSON instead of formatted terminal output.

iOS sessions also support runcloud ios tunnel <id> and runcloud ios tunnel-status for connecting a local development service to the remote simulator. See Run an iOS Simulator for the full workflow.

Assets and samples

Command	Description
`runcloud asset push <file>`	Upload an app artifact for later installation.
`runcloud asset list`	List uploaded assets.
`runcloud asset pull <id>`	Download an uploaded asset.
`runcloud asset delete <id>`	Delete an uploaded asset.
`runcloud sample download ios`	Download the checksum-verified iOS onboarding app.
`runcloud sample download android`	Download the checksum-verified Android onboarding app.

asset also accepts the plural alias assets; sample accepts samples.

Sandboxes

Sandboxes are the single compute noun. Persistence and a stable public hostname are capabilities you turn on — not a separate product:

Command	Description
`runcloud sandbox create`	Create a microVM sandbox.
`runcloud sandbox list`	List sandboxes; exposed ones show their hostname.
`runcloud sandbox get <id>`	Inspect a sandbox, including its public hostname when exposed.
`runcloud sandbox expose <id>`	Publish a guest port at a stable hostname, or change the published port.
`runcloud sandbox exec <id> <command...>`	Run a command through `/bin/sh -c`.
`runcloud sandbox shell <id>`	Open an interactive shell; paused sandboxes resume automatically.
`runcloud sandbox pause <id>`	Pause a sandbox so it can be resumed later. `stop` is an alias.
`runcloud sandbox resume <id>`	Resume a paused sandbox. `start` is an alias.
`runcloud sandbox logs <id>`	Show recent sandbox logs.
`runcloud sandbox rm <id>`	Permanently destroy a sandbox and its public hostname. `kill` and `terminate` are aliases.
`runcloud sandbox snapshot create <id>`	Capture a restorable snapshot.
`runcloud sandbox snapshot list`	List snapshots.
`runcloud sandbox snapshot rm <id>`	Delete a snapshot.
`runcloud sandbox restore <snapshot-id>`	Create a sandbox from a snapshot.
`runcloud sandbox setup-ssh <sandbox>`	Install a dedicated key and add the exposed sandbox to SSH config.
`runcloud sandbox ssh <sandbox> [command...]`	Open a shell or run a command over SSH.
`runcloud sandbox cp <sandbox> <source> <destination>`	Copy files with SCP; prefix the remote path with `:`.
`runcloud sandbox code <sandbox> [path]`	Open the exposed sandbox with VS Code Remote SSH.
`runcloud sandbox domain add\|list\|status\|rm`	Manage custom domains on an exposed sandbox.

sandbox create accepts:

Option	Description
`--image <ref>`	Select the base image. Defaults to `runcloud/agent-base`, or `runcloud/box` with `--expose`.
`--region <region>`	Request a placement region.
`--name <name>`	Add a human-readable name. With `--expose`, it is the hostname prefix `<name>-box.run.cloud`.
`--org <id>`	Select the owning and billing organization.
`--cpu <cores>`	Set the vCPU allocation; fractional values such as `0.5` are supported.
`--memory <mb>`	Set the memory allocation in MiB.
`--disk <gb>`	Set root disk capacity in GiB.
`--idle-pause <seconds>`	Pause after inactivity; use `0` to keep the sandbox running.
`--timeout <seconds>`	Set the maximum sandbox lifetime. Defaults to `300`; use `0` to disable.
`--persistent`	Never pause when idle. Same as `--idle-pause 0`; also disables the default lifetime unless `--timeout` is explicit.
`--expose <port>`	Publish a guest port at `<name>-box.run.cloud`. Implies `--persistent` and requires `--name`.
`--no-wait`	Return after scheduling instead of waiting for the sandbox to finish building and starting.
`--json`	Return JSON instead of formatted terminal output.

sandbox expose accepts --port <port> (default 3000), --name <name> for a first exposure (defaults to the sandbox name), and --reconcile to retry hostname routing. See Persistent Sandboxes for creation and routing examples.

Images

Command	Description
`runcloud image create --ref <ref>`	Register (build-once) an OCI image ref, wait until ready, and exit non-zero if the build fails or times out.
`runcloud image create --ref <ref> --no-wait`	Schedule the build and return immediately with the registration row.
`runcloud image list`	List images your organization has registered, with state and digest.
`runcloud image refresh <ref>`	Move a tag’s pin to its current upstream digest; prints `old_digest`/`new_digest`.

See Custom Images for the full workflow, including CI pre-baking.

Deprecated: `runcloud box`

Earlier releases modeled an exposed persistent sandbox as a separate box noun. Every runcloud box … command still works as a deprecated alias and prints a pointer to its sandbox equivalent:

Deprecated	Use instead
`runcloud box create <name>`	`runcloud sandbox create --expose <port> --name <name>`
`runcloud box create <name> --sandbox <id>`	`runcloud sandbox expose <id> --name <name>`
`runcloud box list`	`runcloud sandbox list`
`runcloud box get <id>`	`runcloud sandbox get <sandbox-id>`
`runcloud box port <id> <port>`	`runcloud sandbox expose <sandbox-id> --port <port>`
`runcloud box route <id>`	`runcloud sandbox expose <sandbox-id> --reconcile`
`runcloud box rm <id>`	`runcloud sandbox rm <sandbox-id>`
`runcloud box setup-ssh\|ssh\|cp\|code\|domain …`	The same verb under `runcloud sandbox …`

SSH config blocks written by older releases keep connecting: the box proxy transport remains supported, and re-running setup-ssh rewrites the block to the current form.

Demos and agent skills

Command	Description
`runcloud demo run [name]`	Run a bundled demo. The default is `eight-device-mosaic`.
`runcloud demo init [name] [directory]`	Scaffold a standalone demo project.
`runcloud skills install`	Install the run.cloud skill for supported coding agents.

Available demos are eight-device-mosaic and live-camera-relay. Pass --open to open the viewer automatically.

Automation

Commands that return structured data accept --json. A typical shell workflow captures IDs rather than copying placeholders:

SANDBOX_ID=$(runcloud sandbox create --json | jq -r '.id')
trap 'runcloud sandbox rm "$SANDBOX_ID"' EXIT

runcloud sandbox exec "$SANDBOX_ID" "echo hello"

See the CLI quickstart for complete runnable examples.

​Authentication

​Mobile sessions

​Assets and samples

​Sandboxes

​Images

​Deprecated: runcloud box

​Demos and agent skills

​Automation