HHostSSH

Concepts & vocabulary

Every word HostSSH uses — Node, Slot, Rack, Mesh, Fleet, App, and the rest — defined precisely, with the mental model behind each.

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. A Slot is the space it runs in. Don't confuse them.

Slot

A unit of capacity on a Node, with hard resource caps. A Slot is like a labeled parking space with a size. Deploying an App "into a Slot" binds it to real CPU/memory/process limits so one noisy App can't starve its neighbors. Slots come in four sizes:

SizevCPUMemoryMax processes (PIDs)Good for
s0.5512 MB256static sites, small workers, cron
m1.01 GB512typical Next.js / API app
l2.02 GB1024busy app, small database-backed service
xl4.04 GB2048heavy app, build-heavy or memory-hungry

The caps are enforced by Docker (--cpus, --memory, --pids-limit). You can also deploy without a Slot (an "unslotted" deploy) — the App runs with no caps, which is fine for a box you own end to end. Slots matter most when you're packing many Apps onto one Node or reselling capacity. See Slots & capacity.

Rack

A Node seen as a set of Slots. The Rack view answers "how full is this box, and what's in each slot?" A Rack is not a different machine — it's the capacity-and-placement lens on one Node. The Slot Board in the dashboard shows every Rack and its occupied/free Slots.

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.