Self-hosting the edge

A self-hosted Houseguest™ edge is the same software as the hosted service, as a single workspace: one account, no domain verification and no Houseguest addresses. No preview traffic or workspace data reaches Houseguest. The hosts that serve releases and the agent image (GitHub’s container registry) see the IP addresses of the servers that download them.

The self-hosted edition is available on the Enterprise plan; contact hello@houseguest.dev. Its installer, install-edge.sh, and the release files come from Houseguest with the plan. They are not on a public downloads page. This page describes what the installation needs and does.

What you need

• A Linux server with a public IPv4 address: Ubuntu 22.04 or later, or Debian 12 or later. 1 vCPU and 1 GB of memory is plenty.
• Ports 443 and 80 (for certificate issuance) open to the internet.
• A domain you control for the edge’s own names, for example hg.example.com.
• An SMTP provider for sign-in codes and invites: Amazon SES, Postmark, Mailgun or your own mail server.

Install

1. Point three DNS names at the server with A records: console.hg.example.com, tunnel.hg.example.com and edge.hg.example.com.

2. Copy install-edge.sh (from your Enterprise installation materials) to the server and run it as root:

   sudo sh install-edge.sh \
     --domain hg.example.com --owner you@example.com \
     --smtp-host smtp.example.com --smtp-user USER --mail-from houseguest@example.com

   The SMTP password is asked for on the terminal (or set SMTP_PASSWORD in the environment). Port 587 uses STARTTLS, which is required; --smtp-port 465 uses TLS from the start.

   Outgoing mail ports

   Many hosting providers block outgoing ports 25, 465 and 587. Use your mail provider’s alternative port, for example Amazon SES --smtp-port 2587, or Postmark and Mailgun --smtp-port 2525. The installer warns when it cannot reach the mail server.

The installer checks the DNS first, installs Caddy from its official repository and the Houseguest edge (checked against its SHA-256 sums), and starts them as locked-down systemd services. It makes you the console’s Owner and waits for the console’s certificate. Then sign in at https://console.hg.example.com with the code that arrives by email.

Then

• Agents: Agents → Add agent gives each agent its install command, already pointed at tunnel.hg.example.com. See Install an agent.
• Shared hostnames: point each one (or a wildcard) at edge.hg.example.com with a CNAME, or at the server’s address with an A record. The edge gets each certificate itself.
• Members: Members & roles → Invite. See Members and roles.

Everything else in these docs applies, except domain verification, Houseguest addresses and Billing.

Operate

Task	How
Upgrade	sudo sh install-edge.sh --upgrade, with the installer for the new release. It backs up first and stops if the backup fails; add --version X.Y.Z for a particular release. It replaces the edge and the agent image the console offers, and restarts
Backups	Daily at 04:00, the newest 14 kept in /var/backups/houseguest. Copy them off the server
Restore	systemctl stop hg-gate; copy a backup to /var/lib/hg-gate/hg.db (owner hg-gate, mode 600); systemctl start hg-gate
Retention	Daily at 03:30: request log 90 days, expired codes and sessions 30 days
Mail settings	Edit /etc/hg-gate/smtp.env, then systemctl restart hg-gate
Logs	journalctl -u hg-gate, journalctl -u caddy, and /var/log/caddy/houseguest-access.log (paths only, never query strings)
Command line	sudo hg …: hg list, hg user add --email E --name N --role owner|admin|member|billing|auditor|none, hg backup, hg prune
Remove	sudo sh install-edge.sh --uninstall keeps the data; add --purge to delete it

Files

Path	What
/usr/local/bin/hg-gate, /usr/local/bin/hg	The edge, and a wrapper that runs it as user hg-gate
/var/lib/hg-gate/hg.db	Everything: previews, people, agents’ public keys, logs
/etc/hg-gate/smtp.env	Mail settings (root:hg-gate, mode 640)
/etc/caddy/Caddyfile	Written by the installer

Self-hosted differences

• One workspace. The console’s second sign-in policy defaults to Optional; set it in Settings.
• No domain verification: any hostname an agent forwards can be previewed once its public DNS points at your edge. Choose the registrable domain carefully: the hostnames in a preview must share a parent domain that is not a public suffix (not co.uk, for example).
• No Houseguest addresses, Billing or workspace limits. Terminal sharing (houseguest share) needs Houseguest addresses, so it is not available.