CLI reference

The hostssh binary is the Agent and the CLI in one. On a Node you use it to deploy apps, manage databases and the proxy, run backups, and open shells. Most day-to-day work happens in the dashboard, but every action is available on the box.

hostssh <command> [flags]

Add --json to read commands for machine-readable output.

---

Licensing: what's gated and what isn't

A Node does not function without a valid license (past a generous offline grace window): the two commands that make a box actually serve — the agent daemon and the proxy — are gated, along with deploy, db, mcp, clone, migrate, transfer, provision, and ssh. Using a gated command without a license exits with code 12.

Recovery is never gated. capture, restore, license, status, doctor, firewall, and version always work — so a box can never be bricked or held hostage, and you can always get your data out. This is a deliberate, load-bearing design choice.

---

Command index

Command	What it does
status	Show agent + license status.
doctor	Check local prerequisites and env wiring.
license activate	Activate a license key against the control plane.
deploy	Build → run → route an app.
db create	Provision a managed database.
proxy	Manage the edge proxy (Traefik + TLS).
firewall	One-click host firewall / hardening.
logs	Stream a container's logs.
capture	Capture this server to an encrypted .hsi image.
restore	Restore this server from a .hsi image.
drill	Run a restore-drill (verify recoverability).
retention	Show/preview/apply image-retention policy.
prune	Reclaim disk — image + build-cache GC.
audit	Show/verify the tamper-evident action log.
fleet	List the license's fleet (servers, backup health).
clone / migrate	Clone or relocate this server to another machine.
transfer	Generate a one-time peer transfer key.
provision	Provision a new VPS (resold or BYO).
ssh / access	Open a Web-SSH / gateway session.
mcp	Run the MCP server (stdio) for AI agents.
agent	Run the daemon (used by the systemd service).
version	Print version.

---

status

$ hostssh status

Prints the Agent version, license state (active / grace / expired), fingerprint, and whether the daemon and proxy are running.

doctor

$ hostssh doctor [--json]

A non-mutating preflight. Checks config, control-plane TLS pins, license public key, mTLS client identity, Docker/HostPack/BuildKit availability, reachability (public vs private/CGNAT), cloudflared (named tunnel + service, for inbound expose), engine scripts, and cleanup-policy env. Missing cloudflared is a warn, never a fail — a Node that only heartbeats does not need it. Home/office join: tunnel-first.

license

$ hostssh license activate --key HSSH-XXXX-XXXX-XXXX [--api https://app.hostssh.com] [--config /etc/hostssh/agent.toml]

Activates a license against the control plane, receiving a signed token (and, when enrolled, an mTLS client certificate) the Agent uses for all later calls. See Licensing.

deploy

$ hostssh deploy --name <app> [--source ./path|git-url] [--ref branch] \
    [--builder hostpack|dockerfile|image] [--image-limit-mb 4096] \
    [--domain x.com --port 3000 --readiness-path /healthz] \
    [--command 'pnpm worker'] [--slot rack1/3 --slot-size m] \
    [--env K=V] [--env-file f] [--volume name:/container/path]

Builds an app (HostPack/Docker), runs it as a capped container, and routes a domain to it. Full walkthrough in Deploying apps.

Flag	Meaning
--name	App name (required).
--source	Local path or Git URL (default .).
--ref	Branch, tag, or commit SHA.
--builder	hostpack | dockerfile | image.
--image-limit-mb	Fail if the built image exceeds this (default 4096).
--domain --port	Public host + container listen port.
--readiness-path	HTTP path probed before success — and the path the proxy healthchecks from then on. Give it something cheap (/api/version), not your homepage. Defaults to /.
--command	Override start command → marks a worker (no proxy/port).
--slot --slot-size	Place in a Slot with s/m/l/xl caps.
--env --env-file	Build + runtime env (--env overrides the file). The file must be valid KEY=VALUE lines — a line that isn't fails the deploy, and the loaded count is printed so you can check nothing went missing.
--volume	Named volume that survives redeploys (repeatable).

db

$ hostssh db create --engine <postgres|mariadb|redis> --name <db> [--network hostssh] [--version v]

Provisions a managed database container on this Node, on the private Mesh network so apps reach it without public exposure.

proxy

$ hostssh proxy up            # ensure the managed proxy is running (idempotent)
$ hostssh proxy up --force    # recreate it — clears a stuck ACME backoff
$ hostssh proxy down          # stop it
$ hostssh proxy status        # is it running?

Manages the Traefik edge proxy that terminates HTTPS and issues Let's Encrypt certs. See Domains & TLS.

firewall

$ hostssh firewall up [--tcp 80,443] [--udp 51820] [--reset]
$ hostssh firewall status

One-click host firewall: default-deny inbound, SSH-safe, allowing the ports you list (80/443 by default; add 51820 for WireGuard). Uses nftables or ufw, whichever is present. Never gated — you can always harden a box. See Hardening.

logs

$ hostssh logs <app> [--follow] [--tail N]

Streams a running container's logs. --follow tails live; --tail N shows the last N lines.

capture

$ hostssh capture [--tag clone-name] [--note NOTE] [box-name [note]]

Captures the whole box — platform state, every database, named-volume data, and config — into one encrypted .hsi image in your object storage. Never gated. See Backups & recovery.

restore

$ hostssh restore --snapshot <id|latest> --tag <clone-name> [--new-ip <ip>]

Restores the box from a .hsi image. With --new-ip it rewrites the public IP for a relocate. Never gated.

drill

$ hostssh drill

Runs a restore-drill — actually verifies that images are recoverable, not just that a job completed. This is the "a backup you haven't restored isn't a backup" check.

retention

$ hostssh retention <get|set|preview|apply> [--tag T] [--keep-last N] [--keep-daily N] [--keep-all]

Views or changes how many images are kept. Default is keep-all — HostSSH never silently deletes your history.

prune

$ hostssh prune [--dry-run] [--keep-last N] [--builder-gb N] [--builder-until-hours N]

Reclaims disk safely: keeps the newest N image versions per app, removes dangling images, and bounds the build cache. --dry-run previews without deleting. It never touches volumes, running containers, rollback tags, .hsi images, or user data.

audit

$ hostssh audit

Shows and verifies the tamper-evident local action log (hash-chained).

fleet

$ hostssh fleet servers [--json]
$ hostssh fleet backups [--server host] [--json]

Lists the fleet as the control plane sees it — every Node, status, and backup health.

clone / migrate

$ hostssh clone --new-ip <ip>       # duplicate this box onto another machine
$ hostssh migrate --new-ip <ip>     # relocate this box to a fresh VPS, rewriting the IP

The relocate/clone engine. migrate is the "move to a new box, new IP, one click" operation.

transfer

$ hostssh transfer --new-key
$ hostssh transfer --serve --resumable [--stage-dir /var/lib/hostssh/transfer-stage]

Generates a one-time peer transfer key (or serves a resumable transfer) for streaming one box directly to another without an intermediate download.

provision

$ hostssh provision …

Provisions a new VPS through a connected provider (e.g. Hostinger) or registers a BYO box.

ssh / access

$ hostssh ssh <node-fingerprint> [--config <path>] [--relay <wss://…>]
$ hostssh access connect --relay wss://relay.host --sid <session-id> --token <token> [--shell /bin/bash]

Opens a browser/gateway root shell to a Node through the relay, presenting the Agent's mTLS client certificate. See Web-SSH.

mcp

$ hostssh mcp

Runs the Model Context Protocol server over stdio, exposing platform tools so an AI agent (Claude, etc.) can drive HostSSH. See Add-ons.

agent

$ hostssh agent

Runs the long-lived daemon: heartbeat, job drain, security reconcile, Web-SSH poll, and the daily reaper. This is what the hostssh-agent systemd service runs — you don't normally call it directly.

version

$ hostssh version

Prints the Agent version (e.g. 0.4.20).

---

Exit codes

Code	Meaning
0	Success.
12	A gated command was run without an active license (past grace).
non-zero	Command-specific failure — read the message.