Frequently asked questions

One-paragraph answers. Each links to the full guide. If your question is "it's broken, how do I fix it," start with Troubleshooting and hostssh doctor instead.

Account & licensing

Do I need a license to get my data out? No. Recovery commands (capture, restore, status, doctor, firewall) are never gated. Only new captures, deploys, and migrations need an active license. See Licensing.

What happens if the control plane is unreachable? Your apps keep serving and the agent keeps working (scheduled captures included). The agent verifies its signed license offline with a grace clock; you just cannot push new changes until connectivity returns. See Concepts.

What does error "exit code 12" mean? A gated command (deploy, db, proxy, the agent daemon) ran without an active license. Activate with hostssh license activate --key HSSH-XXXX-XXXX-XXXX.

Install & onboarding

Which machines can join? Any Ubuntu host you control — cloud VPS, bare metal, office hardware, GPU rental. One Go agent binary, pull-only heartbeats. See Install and the ordered Onboarding checklist.

My box has no public IP. Does that work? Joining works (the agent needs only outbound HTTPS). Serving apps from it needs a Cloudflare Tunnel. See Tunnel-first join.

Where is the one-line installer? Dashboard → Fleet → Add node. While the public release-mirror gate is closed the panel routes to assisted onboarding rather than showing an unverifiable command. The script ships at agent/install.sh in the repo.

Deploying apps

How do I ship my first app? Dashboard → Deploy → New App, or hostssh deploy --name shop --source ./shop --builder hostpack. Four paths (dashboard, CLI, git-push, webhooks), three builders (hostpack, dockerfile, image). See Deploying apps.

My deploy failed — is my site down? No. A failed health gate rolls back to the previous version automatically; only a deploy with no prior good version can leave the site down. Check hostssh logs <app>. See Troubleshooting.

Where do environment variables live? On the App row in the control plane (sealed, encrypted), injected at every deploy — so they survive redeploys. Edit in App Settings → Environment Variables. See Secrets & environment.

Domains & TLS

How long until HTTPS works? Point the A record at the node, then ~10–30 s for the Let's Encrypt certificate (HTTP-01). For zero-downtime cutovers (cert before DNS moves), use DNS-01. See Domains & TLS.

Why does my browser warn about the certificate? The ACME challenge cannot validate: DNS is not pointing at the box yet, or DNS-01 has no token. Fix DNS, then hostssh proxy up --force. See Troubleshooting.

Backups, restore & moves

What is a .hsi image? One encrypted, integrity-signed file holding the whole server: platform state, databases, volume data, system config, and a manifest. It lives in your storage (R2/S3/MinIO/B2/Wasabi/SFTP/local). See Backups & recovery.

How do I restore / clone / relocate? hostssh restore --image latest (same box), hostssh clone --image <id> --to <target> (copy elsewhere), hostssh migrate --new-ip (fresh VPS with automatic IP rewrite). Three transfer modes: offline file, peer transfer key, managed migration. Ports, DNS, and verification are covered in Backups & recovery.

How do I move an app from Coolify / Vercel / Heroku? Follow the per-app loop: inventory → Dockerfile/hostpack → move the database → staging proof → pre-issue cert → cut over → soak 72 h → decommission. Coolify apps can be imported or live-migrated container-as-is. See Migrating to HostSSH.

Do backups include my uploaded files? Yes — named-volume contents (uploads, SQLite files, wp-content) are captured binary-safe, not just volume names. Declare volumes with --volume name:/path.

Cloud & storage

Where does my backup data live? Wherever you point it — bring your own bucket and keys. R2 is the default (zero-egress restores). You also choose who holds the encryption key (agent_local, zero_knowledge, or escrow). See Connections (BYOK).

Can HostSSH create VPSes for me? Yes — dashboard Fleet → Provision queues a provider VPS and enrolls it (tier-gated). Or connect any box you already own. See Getting started.

AI & GPUs

What is Fleet Copilot? An AI diagnostician grounded in a live snapshot of your fleet. It proposes fixes (redeploy, harden, cut over, restore…) as cards you confirm — it never executes on its own. Needs observability.view to ask, platform.deploy to run. See Fleet Copilot.

Can I run GPU / inference workloads? Yes on any node with an NVIDIA GPU + container toolkit: add -gpu all to the deploy. No GPU scheduler or VRAM sharing — one workload owns what it reserves. See GPU workloads.

How do I receive HostSSH events in my own app? Register a webhook endpoint; deliveries are signed (Stripe-style HMAC) so you can verify them. Minimal Node receiver:

// webhook-receiver.js — verify HostSSH webhook signatures
import { createHmac, timingSafeEqual } from "node:crypto";

export function verifyWebhook(rawBody, signature, secret) {
  const expected = createHmac("sha256", secret).update(rawBody).digest("hex");
  return timingSafeEqual(Buffer.from(signature), Buffer.from(expected));
}

See Add-ons.

Billing & support

How are seats and tiers billed? Per licensed node seat; tiers gate server count, transfer modes, and provisioning. Failed payments dun via the built-in email engine. See Licensing and Add-ons.

Something contradicts these docs. What now? That is a bug — the docs track the product commit by commit. Report it with the command you ran, what you expected, and what you saw; include hostssh doctor output.