CLI Reference

The CLI is remote. rh is a shorter alias for the same binary; both keep working.

Anywhere a command takes <host>, you can give a sandbox's name or its id — and an id may be abbreviated to its first four or more characters, the way git takes a short commit. A value that matches more than one sandbox is refused rather than guessed, so nothing is ever deleted or attached to by accident.

Shared flags

Commands that create a sandbox — remote new, remote claude, and remote codex — all take these:

JSON output

Every command that reports data takes --json: ls, new, claude, codex, sleep, wake, extend, resize, rm, metrics, latency, and the three keys commands. Interactive commands (attach, ssh, the TUI) do not, and reject the flag rather than ignoring it.

The contract is worth relying on:

• stdout carries exactly one JSON document, or nothing at all. A list is an array — [] when empty, never a sentence. A single subject is an object.
• stderr carries every diagnostic, including one {"error": {...}} document when a command fails. That document keeps the API's own code (rate_limited, limit_reached, not_authenticated) and whatever it sent beside it, such as retryAfterSeconds.
• exit code is 0 on success and 1 on failure, so a caller knows which stream to parse before parsing it.

remote ls --json | jq -r '.[] | select(.status == "running") | .name'
remote metrics web --json | jq '.pressure.memory'

Without the flag, output is a table on a terminal and the same fields tab-separated when piped. Both are stable; --json exists because the tab line is meant to be read, not parsed — its values carry units (4 vCPU/8 GB/80 GB disk) and some fields contain spaces.

--json never opens a browser. If there is no stored session and no REMOTEHOST_TOKEN, it fails with not_authenticated instead of starting an interactive login.

remote

Run with no arguments to open the interactive TUI: orgs, projects, sandboxes, activity, and subscription info, with actions to create an org, project, or sandbox without leaving the terminal. Prompts you to log in first if you haven't already.

remote login

Starts the OAuth device flow: prints a short code and a URL, opens that URL in your browser if it can, and waits for you to approve the sign-in. Approving it in any browser on any device works — an SSH session on a machine with no browser signs in exactly like a laptop does.

Access tokens last an hour and refresh transparently, so signing in is a one-time step per machine.

remote logout

Clears the stored session on this machine.

remote plan [tier]

remote plan
remote plan pro [--org <org>]

Starts or changes your plan, opening Stripe Checkout in your browser. tier is starter, pro, or max; without it, the CLI shows the current plan and asks.

remote update

Re-runs the installer from https://remotehost.ai/install, replacing this CLI with the current release. Set REMOTEHOST_INSTALL_URL to update from somewhere else.

remote new [agent]

remote new [agent] [flags]

Creates a sandbox with an agent running in it and prints the row. agent defaults to claude; the accepted values are claude and codex. Takes all the shared flags.

It does not attach — remote attach is what puts you inside one.

remote claude / remote codex

remote claude [flags]
remote codex [flags]

Shorthand for remote new claude / remote new codex. Same shared flags.

remote ls

remote ls [-o, --org <org>] [--json]

Lists sandboxes across your orgs, or one org with --org. On a terminal this is a table whose columns are name, agent, profile, persistence policy, size, location, host, status, and SSH address; narrow windows drop columns from the least informative end, and never drop name or status. Piped, it is the same fields tab-separated with no header.

HOST is the orchestrator the sandbox is actually placed on, which is not always what LOCATION implies — a sandbox records the region it asked for and runs wherever it was placed.

remote attach

remote attach <host>

Attaches to a sandbox's terminal. Firecracker sandboxes use the RemoteHost envd tunnel that also powers the console terminal; direct-IP providers use SSH. Recent output is replayed on connect, so attaching to a session that has been running a while shows you where it got to rather than a blank screen.

Ctrl+G returns to the RemoteHost menu, leaving the remote shell and everything in it running (Ctrl+] still works too). Those two bytes are intercepted locally and never forwarded — every other key, Ctrl+C and Ctrl+D included, goes straight to the remote process, which is what makes this a real PTY rather than a wrapper.

remote ssh

remote ssh <host>
remote ssh <host> --command 'hostname && pwd'
remote ssh <host> --print

Opens a shell to a sandbox. Firecracker sandboxes route through the RemoteHost SSH gateway; direct-IP providers connect to the sandbox address directly. Uses the keypair generated on first sandbox creation (~/.config/remotehost/id_ed25519).

remote sleep

remote sleep <host> [--json]

Snapshots the sandbox, releases its machine, and stops machine-time billing immediately. Nothing is deleted — remote wake brings it back exactly where it was, processes and all. Ephemeral sandboxes have nothing to keep, so for them this ends the sandbox. remote stop is an alias.

sleep returns as soon as the sandbox is paused, which is immediate. Billing stops at that moment. Writing its memory to object storage takes as long as the working set needs — seconds for an idle box, longer for one that has been busy — and happens after the command has returned, with the sandbox showing saving until it is done.

A sandbox that is saving cannot be woken yet: a wake restores from exactly the snapshot still being written, so remote wake answers 409 with error.code snapshot_in_progress until it exists. It is seconds, and it resolves on its own.

remote wake

remote wake <host> [--json]

Restores a sleeping sandbox from its own snapshot. remote resume is an alias.

remote extend

remote extend <host> [--json]

Pushes the auto-stop deadline out by another full TTL window from now.

remote metrics

remote metrics <host> [--json]

Samples a running sandbox's CPU, memory, swap, and disk pressure, plus the guest's kernel stall information. Reports the current allocation, the recommendation, and — for auto sandboxes — the allocation queued for next resume. Fixed-size profiles report action=none.

A sandbox under memory pressure also gets a warning on stderr naming the remote resize that would fix it, so a piped metrics line stays clean.

remote latency

remote latency <host> [-n 20] [-w 1] [--json]

Measures interactive terminal round-trip latency against a Firecracker sandbox and reports min, p50, p95, max, and mean. -n/--samples sets how many to take (default 20) and -w/--warmup how many leading samples to discard (default 1).

remote resize

remote resize <host> --vcpu 4 --memory 8 --disk 80 [--json]

Sets an exact allocation. Sleeping sandboxes take it immediately. Running sandboxes apply it live only where the provider supports verified resource changes; otherwise it is queued for the next wake, and the output says which happened.

remote rm

remote rm <host> [--json]

Destroys a sandbox and everything in it. This is not recoverable — use remote sleep if you want the machine time to stop but the work to survive.

remote keys

Manages the API keys that scripts, CI, the MCP server, and anything built on the platform authenticate with.

remote keys create [--org <org>] [--name <name>] [--expires-in-days <days>] [--json]
remote keys list [--org <org>] [--json]
remote keys revoke <key-id> [--org <org>] [--json]

create prints the token once and stores only a hash of it, so a lost key is replaced rather than recovered. The key is named after this machine unless --name says otherwise, which is what makes remote keys list readable later.

remote mcp setup

remote mcp setup [--org <org>] [--name <name>] [--expires-in-days <days>]

The same mint as remote keys create, followed by the MCP client configuration to paste — a ready-made claude mcp add line and the equivalent JSON block.

Configuration