CLI Reference
Every rh command, its flags, and what it does
The CLI binary is rh (also installed as remotehost). Commands that create a sandbox share
the same flags:
| Flag | Description |
|---|---|
-o, --org <org> | Org id or name |
-p, --project <project> | Project id or name |
-n, --name <name> | Sandbox name |
-r, --repo <repository> | Repository name |
-b, --branch <branch> | Git branch |
--profile <profile> | auto, agent-small, agent-standard, build-heavy, browser-heavy, repo-large, or long-running |
-m, --machine-size <size> | small, default, or large (overrides the profile's initial machine tier) |
rh
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.
rh login
Starts the login flow: opens the console's /cli-login page in your browser, then prompts
you to paste the token it shows back into the terminal. See Getting Started.
rh new [agent]
rh new [agent] [flags]Creates a sandbox and launches an agent in it. agent defaults to claude if omitted; the
only accepted values are claude and codex. Accepts all the shared flags
above.
rh claude / rh codex
rh claude [flags]
rh codex [flags]Shorthand for rh new claude / rh new codex — launches the named agent directly. Accepts the
same shared flags.
rh ls
rh ls [-o, --org <org>]Lists sandboxes across your org(s). With --org, lists only that org's
sandboxes. Output is one line per sandbox: name, agent, profile, allocation, status, repository,
and SSH address.
rh attach
rh attach <host>Connects to a sandbox over SSH, identified by name or id. Fails if the sandbox has no public
address yet (still provisioning, or stopped). Uses the keypair generated on first sandbox
creation (~/.config/remotehost/id_ed25519).
rh stop
rh stop <host>Stops a sandbox by name or id. Billing for that sandbox's machine time stops immediately; stopping does not delete it.
rh metrics
rh metrics <host>Samples a running Firecracker sandbox's CPU, memory, and disk pressure by name or id. Output
includes the current allocation, recommendation, and pending next allocation for auto sandboxes.
rh resize
rh resize <host> --vcpu 4 --memory 8 --disk 80Sets an exact allocation target by name or id. Stopped sandboxes update immediately. Running sandboxes apply live only when the provider supports verified resource changes; otherwise the target is queued for the next resume.
rh rm
rh rm <host>Reserved for removing a sandbox entirely. Not yet implemented — currently returns an error.
Configuration
| Config file | ~/.config/remotehost/config.json (mode 0600) |
| SSH keypair | ~/.config/remotehost/id_ed25519 / id_ed25519.pub, generated on first use |
REMOTEHOST_TOKEN | Overrides the stored access token — useful in CI or headless environments |
REMOTEHOST_API_URL | API base URL (defaults to http://localhost:8787 in development) |
REMOTEHOST_CONSOLE_URL | Console base URL used to build the /cli-login link |