HostSSH Developer Documentation

Architecture, internals, APIs, and contribution guide for people building HostSSH itself.

HostSSH — Developer Documentation

This is the documentation for people building HostSSH — the control plane, the agent, the proxy, and the platform features. If you're a customer using HostSSH, see docs/user/ instead.

The system in one paragraph

HostSSH is three cooperating parts: a control plane (a Next.js/TypeScript app + Postgres) that is the brain and the dashboard; a Go agent (one dependency-free binary) on each Node that builds/runs apps, manages the proxy, runs backups, and reports telemetry; and a managed proxy (Traefik) the agent runs for TLS and routing. They communicate over an authenticated job queue and heartbeat protocol; Nodes are linked by a private WireGuard mesh. The control plane never handles app traffic — it hands agents signed jobs and reads their heartbeats.

Map of these docs

Orientation

Doc	What's in it
Architecture	The whole system, components, and data flow.
Platform / Framework	Product/platform framing and the build philosophy.
Local development	Get the control plane and agent running on your machine, run the tests.
Contributing	Branch/commit conventions, the fix-forward rule, PR checklist.

The agent (Go)

Doc	What's in it
Agent protocol	Activation, heartbeat, job claim/report, the wire contract.
Deploy pipeline	build → run → route, builders, gates, rollback, guards.
HostPack	The zero-config builder and BuildKit.
Secure access / Web-SSH	Browser root shell, relay, mTLS, recording.
Hardening	The harden engine, firewall, container defaults.

The control plane (TS)

Doc	What's in it
Control panel / Dashboard	The god-mode UI surfaces.
Database & migrations	Schema, the forward-only migration runner, roles/RLS.
API reference	Every `/api/v1` route, auth, and payload.
API & CLI	How the CLI and API map onto each other.
DNS tools	The DNS SuperTool / integrity / attack-surface internals.
MCP kit	Building and hosting MCP servers on the platform.

Cross-cutting

Doc	What's in it
Security model	Sealed secrets, RLS tenancy, mTLS, the trust root.
Build guards	The fix-forward regression catalog (G1–G19) and the discipline.
Testing & CI	How to run and write tests; what CI enforces.
Changelog	Notable changes over time.

The non-negotiable rules

Three rules govern all development here. Break them and you'll get a review rejection.

Fix forward, never patch one box. Every bug fix lands at the most upstream layer that makes it automatic for every app (the agent defaults, the deploy pipeline, a shared template), plus a regression test, plus a row in the build-guards catalog. We never patch a symptom on one server and lose it. See ../planning/BUILD-GUARDS.md.
Zero third-party dependencies in the agent. agent/go.mod has no require block. The agent is one auditable, portable binary. If you reach for a library, find another way — the standard library and shelling out to system tools (docker, restic, nftables) are the toolkit.
Evidence or it didn't happen. A feature isn't done because it compiles. Backups aren't real until a restore-drill passes; a deploy isn't green until it serves; a security control isn't done until an adversarial pass tries to break it. Claims in a PR carry the command output that proves them.

Repo layout (top level)

agent/              the Go agent + CLI (module github.com/Girard-Media/hostssh/agent)
  main.go             binary entrypoint
  cmd/hsmcp/          the MCP-kit scaffolder binary
  internal/           all agent packages (deploy, runtime, proxy, builder, slots, harden, …)
  install.sh          the signed one-liner installer
  release-*.sh        release mirror + provenance scripts
control-plane/web/    the Next.js control plane (the dashboard + API + platform logic)
  app/(marketing)/    the public site
  app/(god)/          the operator dashboard
  app/api/            the API (v1 + auth + webhooks)
  lib/                platform logic (slots, platform, fleet, licenses, migrations, …)
  lib/migrations/     forward-only DB migrations + runner
dashboard/            (secondary UI app)
engine/               the proven capture/restore shell engine (.hsi)
services/             standalone services (ws-relay, browser-worker, …)
deploy/               local-dev → live-node deploy surfaces (git-push, CLI, webhook)
wordpress-plugin/     the hostssh-migrate WP plugin
docs/                 these docs (user/, dev/, product/, ops/) + top-level specs
planning/             the single source of truth for what's built and what's next
  MIGRATION-MASTER-PLAN.md  the A-to-Z program
  TODO.md                   the task board
  BUILD-GUARDS.md           the fix-forward catalog
  GAP-REGISTER-*.md         the audited gap backlog

Start with Architecture, then Local development.