Concepts & vocabulary

HostSSH borrows a few words and gives them exact meanings. Learn these and the rest of the docs read easily. Product story: any hardware · backup · restore · move · cloud · AI (vision).

---

The core set

Node

A single machine running the HostSSH Agent — cloud VPS, bare metal, office PC, or GPU rental. A Node may have a public IP or only a private/tunnel path; it has CPU/RAM/disk (and optional GPUs), and a stable fingerprint (hardware+key identity across reboots and rebuilds).

When you "add a server," you add a Node. Deploys pinned to a Node run on that exact box — not "somewhere in the fleet."

App

A deployable unit. One website, API, or worker. An App has a name, a source (a Git repo, a local folder, or a prebuilt image), an optional domain, environment variables, and a lifecycle (queued → building → deploying → running, or failed/stopped). An App keeps its identity and its environment across redeploys — the row survives; only the container is replaced.

An App is what you deploy. Size is the envelope it runs in. Don't confuse them.

Size

The envelope an App is allowed to use on a Node. Four sizes, each with a CPU share (the billed baseline), a CPU burst ceiling (4× share, never more than that Node's cores), hard memory, and a process cap:

Size	Share	Burst (8-core Node)	Memory	PIDs
s	0.5	2.0	512 MB	256
m	1.0	4.0	1 GB	512
l	2.0	8.0	2 GB	1024
xl	4.0	8.0	4 GB	2048

CPU policy (per Node)

How Size CPU is applied. Memory never bursts.

• Cap — --cpus = share. No spare cores.
• Throttle — --cpu-shares from share, --cpus = burst. Idle cores are used; busy boxes share fairly.
• No throttle — no CPU flags. Memory and PIDs still apply when a Size is set.

Existing Nodes default to No throttle so live uncapped apps stay that way until you flip the control. Flipping the control live-updates sized running apps (docker update); unslotted apps are never touched. See Capacity.

Capacity board

A Node seen as fillable space. Same machine as the Node. The Capacity page shows how full the box is and which Apps occupy it, plus the CPU policy control.

Mesh

The private network that links your Nodes. HostSSH builds a WireGuard overlay so your Nodes can talk to each other over private IPs (for example, an App on one Node reaching Postgres on another) without ever exposing those services to the public internet. The Mesh page shows peer links and their health.

Fleet

All of your Nodes together. The Fleet is the collective — the thing the dashboard's Fleet map shows: every Node, its status, its Apps, its backup health, its disk pressure. "Fleet-wide" means "across every box you own."

Control Plane

The SaaS brain at app.hostssh.com (or your own self-hosted instance). It licenses your Nodes, queues deploy/backup/restore jobs for the Agents to run, ingests their heartbeats, draws the Fleet map, delivers alerts, hosts the AI copilot, and (via the Inference surface) helps you mint keys and model routes for the ai-gateway. Crucially, it never handles your app traffic — it only tells Agents what to do and reads what they report. If it goes down, your Apps keep serving; you just can't push new changes until it's back.

Inference gateway

The OpenAI-compatible API face of your fleet capacity. Apps send sealed bearer tokens and model names; the gateway routes to CPU nodes, office GPUs, or rentals. Apps never talk to a box IP or a raw ComfyUI URL. See GPU workloads and INFERENCE-PLATFORM.md.

---

Supporting terms

Agent

The single Go binary installed on every Node. Zero third-party dependencies. It:

• builds and runs your Apps (the deploy pipeline),
• runs the managed proxy for HTTPS,
• runs backups and restores,
• enforces hardening (firewall, container caps),
• reports health via a heartbeat,
• and refuses to run workloads or serve traffic without a valid license (recovery is never gated, so you can always get your data out).

Job

A unit of work the control plane hands an Agent. Every deploy, redeploy, stop, remove, database provision, backup restore, firewall apply, disk cleanup (prune), and public-expose is a Job with a kind, a spec, and a live log you can watch. Jobs are pinned to a Node's fingerprint and claimed by that Agent. The Jobs/Recovery views show them running.

Heartbeat

The Agent's periodic report to the control plane (every ~60s): version, uptime, CPU/memory/disk, container states, backup health, and access-session health. Heartbeats are what make the Fleet map live. A Node that stops heartbeating goes degraded (>3 min) then offline (>15 min).

Managed proxy

The Traefik instance the Agent runs (hostssh-proxy). It owns ports 80/443, terminates TLS, requests Let's Encrypt certificates automatically (HTTP-01 by default, DNS-01 for zero-downtime cutovers and wildcards), and routes each domain to the right App container based on labels the Agent stamps. You never configure it by hand. See Domains & TLS.

Builder

How source becomes a runnable image. Three choices per App:

• hostpack — zero-config detection (HostPack, our Railpack-based builder). You point at a repo, it figures out the language/framework and builds it. Best default.
• dockerfile — you ship a Dockerfile; the Agent runs docker build. Full control.
• image — you already have a built image; the Agent just runs it. Fastest.

Sealed secret

An environment value encrypted at rest and in transit. Secret env values are sealed by the control plane (AES-GCM) and only ever decrypted inside the Agent at deploy time — they never sit in plaintext in the job queue, logs, or the database. See Secrets & environment.

.hsi image

A HostSSH Image: the encrypted capture of a box (or an App) — the platform brain, databases, volumes, and config — written to your object storage. It's what a restore, clone, or relocate reads from. See Backups & recovery.

License

Your entitlement to run the platform, expressed as a signed key (HSSH-XXXX-XXXX-XXXX). One license activates one or more Node seats. The Agent verifies the license signature offline (it embeds the public key) and keeps a grace clock so a brief control-plane outage never takes your box down. See Licensing.

Cutover

The moment you point a real domain's DNS at a HostSSH Node. HostSSH pre-issues the TLS certificate before the cutover (via DNS-01) so there's zero HTTPS downtime, then flips the DNS record and lights up an uptime monitor automatically. See Migrating to HostSSH.

---

A worked example, in vocabulary

You own three VPSes (a Fleet of three Nodes), joined by a WireGuard Mesh. On the first Node, its Rack has four Slots free. You deploy an App called shop from a Git repo, using the hostpack builder, into an m Slot, with a sealed DATABASE_URL pointing over the Mesh at Postgres on the second Node. The managed proxy gets a Let's Encrypt cert for shop.example.com and routes to it. A Job ran the deploy; the Agent reports the new container in its heartbeat; the Control Plane draws it green on the Fleet map and starts an uptime monitor. That night the Agent captures a .hsi image to your R2 bucket. If that Node ever dies, you restore the image to a fresh VPS and HostSSH rewrites the IP — a relocate — and re-deploys every App that was pinned to it.

Every bolded word is defined above. That's the whole model.