HostSSH — User Documentation

HostSSH is the control plane for any machine you run — cloud VPS, bare metal, office hardware, GPU rental. One agent turns a box into a full platform: push-to-deploy, managed databases, HTTPS proxy, monitoring, full-server backup / clone / relocate, and an OpenAI-compatible inference path over your capacity — dashboard, CLI, and MCP for agents.

Promises: onboard any hardware · backup any · restore any · move any · cloud + AI enabled.
Line: servers (and GPUs) that can't be held hostage — your data, your bucket, your exit.

Canonical vision (for product narrative): planning/PRODUCT-VISION.md.

---

Start here

If you want to…	Read
Understand the words we use (Node, Slot, Fleet, App…)	Concepts & vocabulary
Get a server running in 10 minutes	Getting started
Install the agent on a box	Install
Join a home/office box with no public IP	Tunnel-first join
Ship an app from Git or a local folder	Deploying apps
Put a real domain + HTTPS on an app	Domains & TLS
Hand your app its secrets safely	Secrets & environment
Size and pack apps onto a box	Slots & capacity
Back up, restore, and rebuild a whole box	Backups & recovery
Get a root shell from your browser	Web-SSH
Watch uptime and get paged when things break	Monitoring & alerts
Lock a box down	Hardening
Move off Coolify / Vercel / Heroku	Migrating to HostSSH
Move a WordPress site	WordPress migration
Store creds for R2 / S3 / Cloudflare	Connections (BYOK)
Turn on email, DNS tools, webhooks, the AI copilot	Add-ons
GPU nodes and inference workloads	GPU workloads
Understand keys, seats, and billing	Licensing
Look up any command	CLI reference
Fix something that's broken	Troubleshooting
Product vision (any hardware · AI)	PRODUCT-VISION · Inference platform

---

The three things HostSSH does

1. Deploys your apps. Push code (or point at a Git repo, or hand it a Docker image) and HostSSH builds it, runs it in a resource-capped container, and routes a domain to it over automatic HTTPS. No YAML to hand-write, no proxy to configure. See Deploying apps.

2. Protects your data. Every box captures itself — the platform's own state, every database, every volume, and OS config — into one encrypted .hsi image in your object storage (Cloudflare R2, S3, or bring-your-own). Nightly on a schedule, verified monthly by a real restore-drill. See Backups & recovery.

3. Sets your data free. The same capture engine can restore to a brand-new VPS with the IP rewritten for you, clone a box for staging, or stream one box directly to another. No provider can trap you. See Migrating to HostSSH.

---

How the pieces fit

                 ┌───────────────── Control Plane (app.hostssh.com) ─────────────────┐
                 │  Your dashboard · licensing · deploy queue · monitors · alerts     │
                 │  fleet map · recovery console · billing · AI copilot · MCP         │
                 └───▲───────────────────────▲───────────────────────▲───────────────┘
       license + telemetry (mTLS)     job queue (deploy/…)      heartbeat (metrics)
                     │                        │                        │
          ┌──────────┴─────────┐   ┌──────────┴─────────┐   ┌──────────┴─────────┐
          │  Node (your VPS)    │   │  Node (your VPS)   │   │  Node (your VPS)   │
          │  ┌───────────────┐  │   │  ┌──────────────┐  │   │  ┌──────────────┐  │
          │  │ HostSSH Agent │  │   │  │ Agent        │  │   │  │ Agent        │  │
          │  │ + managed     │  │   │  │ + Postgres   │  │   │  │ + your apps  │  │
          │  │   proxy (TLS) │  │   │  │   (Data node)│  │   │  │   in Slots   │  │
          │  │ + your apps   │  │   │  └──────────────┘  │   │  └──────────────┘  │
          │  └───────────────┘  │   └────────────────────┘   └────────────────────┘
          └─────────────────────┘         (all joined by a private WireGuard Mesh)

• Control Plane — the SaaS brain you log into. It never touches your app traffic; it hands your Agents signed jobs and reads their telemetry.
• Agent — a single dependency-free Go binary on each box. It builds and runs your apps, manages the proxy, runs backups, and reports health. It keeps working even if the control plane is unreachable.
• Managed proxy — a Traefik instance the agent runs for you; terminates HTTPS, gets Let's Encrypt certificates automatically, and routes each domain to the right container.
• Mesh — a private WireGuard network that links your nodes so apps reach the database without exposing it to the internet.

Read Concepts & vocabulary next — it defines every term precisely.

---

Conventions in these docs

• Commands you run on a box start with $ and assume you're root (or using sudo).
• Commands you run through the dashboard are described as buttons/fields, not shell.
• HSSH-XXXX-XXXX-XXXX is a placeholder for your license key.
• app.example.com is a placeholder for your domain.
• Anything destructive is flagged with a ⚠ and tells you the rollback before the risk.

If a step here doesn't match what you see, tell us — the docs track the product commit by commit, and drift is a bug.