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.
| Part | Software | Job |
|---|---|---|
| Control server and relay | Headscale | 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. |
| Registrar | Hogman (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 authority | step-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 page | Caddy | Serves home.yourpen.hogman, where members manage devices and names and the
keeper runs the pen. |
| The pen's own node | Tailscale 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:
- DNS. Bob's browser hands any address ending in
.smith.hogmanto 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 like100.80.12.7. The connection only ever dials devices the pen itself knows, whatever the answer. - 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.
- 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.
- TLS. The share presents a certificate for
photos.smith.hogmansigned by the pen's CA. Bob's computer trusts that CA becausehogman-joininstalled 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
- 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. - The link's page shows one command, which downloads
hogman-joinfor your computer and runs it with the link. hogman-joinfetches 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.- 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.
- 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 (anhttp://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. - 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:
| Device | Accepts connections from | Can connect to |
|---|---|---|
| Personal | Nobody | The pen's DNS, home page and CA; every server, on HTTPS (443) only |
| Server | Any active member's device, on 443 only | The pen's services; other servers, on 443 |
| Anything else | Nobody | Nothing |
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
- Each pen has its own zone,
yourpen.hogman. The registrar is the only DNS server for it, and answers only inside the mesh. - Members claim names first come, first served, up to 50 each:
blog.smith.hogman, and anything under a name they own (photos.blog.smith.hogman). A name points at one of that member's servers. - Reserved:
home,ca,ns,registrar,search,nodes,www,join,admin. Devices also get automatic names undernodes.yourpen.hogman. - Your browsing outside the pen never touches the pen's DNS.
Certificates
- When a pen is raised it makes its own root certificate. The root carries X.509 name
constraints: it may sign only names ending in the pen's zone, and no IP addresses.
Browsers and operating systems enforce that, so installing it can't be used to intercept your
other traffic. Hogman's tests try to make the CA sign
www.google.comand check that it fails. - Day-to-day signing uses an intermediate certificate valid for five years. The root key is taken off the server and kept offline, encrypted.
- The CA speaks ACME at
ca.yourpen.hogman:9000, inside the mesh only. Certificates last 7 days and renew automatically; the short life is the revocation mechanism. - A server proves it owns a name the usual ACME way (TLS-ALPN or HTTP challenge) at the address the pen's DNS gives for it. Since the registrar controls DNS, owning a name in the pen is what entitles you to a certificate for it.
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:
- Remove a device: one lost or stolen laptop is cut off.
- Suspend: all of a member's devices are left out of the policy. Everything else is kept, and resuming takes under a second.
- The boot (kick): the registrar marks them removed and refuses them everything, revokes their unused device keys and the invites they made, deletes every device they own from Headscale, deletes their Headscale user, rewrites the policy, and holds their names for 90 days so nobody can impersonate their sites. All of it is in the audit log.
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 keeper | Us, if we host the pen | |
|---|---|---|
| Who is in the pen, their devices, when they're online | Yes | Yes |
| Which pen names devices look up | Yes | Yes |
| What members send each other | No (end to end encrypted) | No |
| Your browsing outside the pen | No | No |
| Could add a device or vouch for a name | Yes | Yes, 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
- Not audited. Young security software. Don't put anything high-stakes in a pen yet.
- Phones can't join yet; the app is in the works.
- Windows is built but untested.
- One control server per pen: if it's down, new connections, joins, DNS for the pen and certificate renewals stop. Existing direct connections keep working for a while.
- Some programs keep their own certificate list (Java, Node, Python). They need to be pointed at the pen's root; see the FAQ.
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.