ssh cli commands

The management CLI runs over SSH — nothing to install, and your SSH key is your identity. The reserved username cli spawns no box; every command is scoped to the boxes owned by your key's fingerprint.

ssh cli@host <command>

Commands

Command	Description
ls (ps, list)	List your boxes: WORKSPACE BOX NAME IMAGE STATE AGE, grouped by workspace. STATE is one of starting / running / suspended / pinned / kept / ephemeral (see box status).
ws create <name>	Create a workspace (a group of boxes with their own /wrk, homes, and secrets).
ws ls	List your workspaces + box counts.
ws rm <name> (--force)	Remove a workspace; refused if it has boxes unless --force.
up <[ws/]name[:image[:flavor]][^ttl]> (spawn)	Start a box without attaching a shell. ^ttl (30m, 2h) gives it a hard deadline — it is destroyed then, whatever it is doing.
rm <name|id> (delete, destroy)	Remove one of your boxes (owner-checked).
suspend <box>	Snapshot a running box to disk now (microVM only; other backends report it's unsupported).
resume <box>	Wake a suspended box without connecting.
rename <box> <new> (mv)	Rename a box; its persistent home follows. Refused if the new name is already yours.
durable <box> on|off	Mark a box durable — it persists (never idle-reaped) but still auto-suspends when idle. Turning it on needs a verified account; off is always allowed.
share <box> [--ttl 24h] [--label "n"]	Mint a share link for a box: prints ssh hbxs_<token>@<host> (shown once) that gives any holder a shell in that box. --ttl sets expiry (default 24h; 0 = never). Needs a verified account.
shares [<box>]	List your active share links (ID · BOX · LABEL · EXPIRES · LAST USED); never the token. Optional box ref filters to one box.
unshare <id>	Revoke a share link by id; its hbxs_<token> stops working immediately.
ready <box> (wait)	Block until the box is running with its agent connected (30s timeout, non-zero exit on timeout) — for scripts.
clone <src> <dst> (fork)	Fork a box's persistent home into a new box on the same image (needs --homes-dir).
snapshot <box> [name]	Capture a box's disk state (microVM). Name defaults to a timestamp.
snapshot ls <box>	List a box's snapshots: SNAPSHOT SIZE AGE.
snapshot fork <src> <name> <new>	Create a new box that boots from <src>'s snapshot (CoW, cheap).
snapshot restore <box> <name>	Roll a box back to a snapshot (it reboots into that state). Persistent-tier boxes.
snapshot rm <box> <name>	Delete a snapshot.
apikeys create <name>	Mint an HTTP API key (hbx_…), printed once.
apikeys ls	List your API keys: NAME · CREATED · LAST USED (never the secret).
apikeys rm <name> (revoke)	Revoke an API key.
acc · acc register <handle>	Show / create your account (verification, quotas).
mcp	Serve your per-key MCP plane over this SSH connection — point an MCP client at ssh cli@host mcp.
secret set [-w <ws>] [-b <box>] <NAME>	Store a secret (value read from stdin). Scope: none = account (all boxes), -w <ws> = a workspace, -w <ws> -b <box> (or --box <ws>/<box>) = one box. Appears as $NAME; NAME is env-var-shaped, non-HOPBOX_. A box sees them layered, box > workspace > account.
secret ls [-w <ws>] [-b <box>]	List secret names + scope (never the values); filters to a tier.
secret rm [-w <ws>] [-b <box>] <NAME>	Delete a secret at a scope.
asks	List questions your agents are blocked on: ID BOX KIND QUESTION OPTIONS.
answer <id> <choice>	Answer a pending ask — unblocks the agent with your choice (free text allowed).
help	Usage banner. Bare ssh cli@host prints the banner and your fleet.

ssh cli@box.hopbox.dev ls
ssh cli@box.hopbox.dev up proj:python:big   # start, don't attach
ssh cli@box.hopbox.dev ready proj           # block until it's up (scripts)
ssh cli@box.hopbox.dev rename proj api      # its home follows
ssh cli@box.hopbox.dev suspend proj         # snapshot to disk now (microVM)
ssh cli@box.hopbox.dev rm proj
ssh cli@box.hopbox.dev            # banner + your boxes

Snapshots copy the box's copy-on-write disk with the device briefly frozen for a consistent image (they live beside the box and are lost when it's destroyed — restore + fork-from-snapshot are coming).

Notes

• Key = identity. A different SSH key is a different owner and sees none of your boxes. There is no signup and no separate login.
• Spawn by connecting. There's no create command — you make a box just by connecting to a name: ssh <name>@host. See SSH & the front door.
• For AIs, the same fleet is driven programmatically over the MCP plane (fleet_get, box_delegate, fleet_apply).

See also

• SSH & the front door — spawning boxes and the username grammar.
• The AI-control plane — the MCP twin of these commands.