HÖGMAN

How Hogman works

A pen is a private network for a group of people: its own encrypted mesh, its own names, its own certificate authority and its own member list. This page goes through each part, then follows a request from start to finish.

The parts

Each pen runs five small services, in containers, with its own data folder. Only the first is reachable from the internet; the rest answer only inside the mesh.

PartSoftwareJob
Control server and relayHeadscale Registers devices, hands out WireGuard keys, pushes the access policy and DNS settings to every device. Its built-in relay carries encrypted packets for devices that can't reach each other directly.
RegistrarHogman (Go) The ledger: members, roles, invites, devices, names, the audit log. Writes the access policy into Headscale, answers DNS for the pen's zone, and serves the home page's API.
Certificate authoritystep-ca Issues HTTPS certificates for names in the pen over ACME (the standard way to get certificates automatically), the protocol Let's Encrypt uses.
Home pageCaddy Serves home.yourpen.hogman, where members manage devices and names and the keeper runs the pen.
The pen's own nodeTailscale client Puts the pen's DNS, home page and CA at one address inside the mesh.

Exact versions are pinned in core/compose.yaml. Members' computers run Hogman's built-in client (see joining). Hogman's own code is the registrar, the join tool (hogman-join), the sign-up service, and shell tools that run pens and hosts.

One request, start to finish

Bob is a member. Alice shared a photo folder as photos.smith.hogman. Bob types that address into his browser:

  1. DNS. Bob's browser hands any address ending in .smith.hogman to the pen's background connection (its automatic proxy setting says so; every other address goes to the internet as usual). The connection asks the pen's DNS, inside the mesh, and the registrar answers with the mesh address of Alice's share, something like 100.80.12.7. The connection only ever dials devices the pen itself knows, whatever the answer.
  2. Policy. Bob's laptop may connect to that address on port 443 because the policy says members' devices may reach servers over HTTPS, and Alice's share is a server. If Bob were suspended, his devices would simply not be in the policy and nothing would connect.
  3. Tunnel. The connection goes over WireGuard, Bob's device to Alice's, end to end. If a firewall blocks a direct path, it goes through the pen's relay, still encrypted; the relay can't read it.
  4. TLS. The share presents a certificate for photos.smith.hogman signed by the pen's CA. Bob's computer trusts that CA because hogman-join installed its root when he joined, after checking its fingerprint against his invite link. The browser shows the padlock.

A stranger typing the same address gets nowhere at step 1: .hogman isn't a public top-level domain, so the name doesn't resolve. Even with the IP address, there's no route to it: 100.80.12.7 exists only inside the mesh.

Joining

  1. The keeper makes an invite: a single-use token, valid for 7 days. The link looks like https://<control host>/join#t=<token>&fp=<fingerprint>. The part after # never leaves the browser except when the invite is redeemed.
  2. The link's page shows one command, which downloads hogman-join for your computer and runs it with the link.
  3. hogman-join fetches the pen's root certificate and checks it against the fingerprint in the link, and that it can only vouch for the pen's own names. Only then does it trust anything from the pen.
  4. It adds the root to your computer's trust store (your password, once), then redeems the invite with the name you choose. The registrar creates your membership and returns a one-time device key.
  5. It starts the pen's background connection: a small built-in client (Tailscale's tsnet, its library for building a connection into a program) running as you, not as administrator, with a local proxy that carries only HTTPS to the pen's names (an http:// address is answered on your own computer with a redirect to HTTPS). Browsers use it through an automatic proxy setting; everything else on the computer, including any Tailscale of your own, is untouched.
  6. It checks that your home page loads over HTTPS, and you're in.

Details and options: Joining a pen.

Who can reach what

Every device is either personal (a member's laptop or phone) or a server (anything set up to host sites). The registrar rebuilds the access policy from its ledger every few seconds and whenever something changes. It is default deny, meaning nothing is allowed unless a rule says so:

DeviceAccepts connections fromCan connect to
PersonalNobodyThe pen's DNS, home page and CA; every server, on HTTPS (443) only
ServerAny active member's device, on 443 onlyThe pen's services; other servers, on 443
Anything elseNobodyNothing

Sometimes the best security fix for a surface is just to delete the surface.

So Hogman carries HTTPS and nothing else: no ssh, no other ports, no joining a whole computer as a server. Things that serve the pen are shares, each a small device of its own. The policy lists device addresses, not tags. So suspending someone is just leaving their devices out (instant and reversible), and a device that somehow joined without going through the registrar is in no rule at all and can reach nothing.

Names

Certificates

Shares

hogman-join share blog 3000 creates a small device of its own, a server, using Tailscale's tsnet inside the join tool. It names itself blog, gets a certificate from the pen's CA, and passes visitors to port 3000 on your computer (or serves a folder). Because the share is its own device, your laptop stays a personal device that accepts no connections, and nothing needs administrator rights or an open port. A server may only name itself, and only with a free name or one that already points at it. Guide: Sharing a folder or a website.

Removing people

Three levels, from lightest:

Measured on a real Mac over a home network: suspend 2.0 s, resume 0.8 s, the boot 2.1 s. What it can't do: take back data they already copied, or log them out of apps that keep their own accounts.

Hosted pens

On our server, every pen is its own set of the five containers above, with its own folder, database, keys and relay port, using about 75 MB of memory. A shared front door (Caddy) holds ports 80 and 443, has a public Let's Encrypt certificate for each pen's control address, and passes each pen's traffic only to that pen. Pens never share a network with each other. A pen's folder is the whole pen: copy it to another server running Hogman and it carries on there.

Who sees what

The keeperUs, if we host the pen
Who is in the pen, their devices, when they're onlineYesYes
Which pen names devices look upYesYes
What members send each otherNo (end to end encrypted)No
Your browsing outside the penNoNo
Could add a device or vouch for a nameYesYes, in principle

Joining a pen means trusting its keeper, the same as joining anyone's Tailscale network means trusting its admin. If you'd rather trust nobody upstream, raise your own pen.

Limits, honestly

The full design, with the reasoning, is in DESIGN.md.

Something wrong or unclear on this page? Its source is in site/docs-src; issues and fixes welcome.