HÖGMAN

Joining a pen

You need an invite link from someone in the pen and a Mac or Linux computer. It takes about a minute.

Your first computer

  1. Open your invite link on the computer you want to join. Invites work once and expire after 7 days.
  2. Copy the command it shows into a terminal. It downloads hogman-join for your computer and runs it with your link:
    $ curl -fsSLo hogman-join https://smith.pens.hogman.network/join/dl/hogman-join-Darwin-arm64 \
        && chmod +x hogman-join \
        && ./hogman-join 'https://smith.pens.hogman.network/join#t=…&fp=…'
  3. The page picks the right download for your computer. If you'd rather fetch it yourself, the files are on the same host under /join/dl/, with checksums in SHA256SUMS:
    Mac, Apple siliconhogman-join-Darwin-arm64
    Mac, Intelhogman-join-Darwin-x86_64
    Linux, x86-64hogman-join-Linux-x86_64
    Linux, ARM (Raspberry Pi 4/5, ARM servers)hogman-join-Linux-aarch64
    Windows (untested)hogman-join-windows-amd64.exe
  4. Pick your name when asked: lowercase letters, digits and dashes, 2 to 32 characters. It's how the pen knows you.
  5. Enter your password once, so the pen's certificate can be added to your computer. On a Mac this has to happen at the Mac itself, not over SSH: macOS only lets a person approve a new trusted certificate on screen.
  6. You're in. It checks your pen's home page loads over HTTPS and opens it. Keep the hogman-join file: you'll use it to update, share things, and leave.

If it stops part way (a password prompt cancelled, DNS not ready), fix what it says and run the same command again. If the stop came before your device joined, the invite is still unused; if after, the rerun sees the device is already in and skips the invite. Either way the link only ever adds this one computer.

Before trusting anything, the tool checks the pen's certificate against the fingerprint in your link, and that the certificate can only vouch for the pen's own names. A link that doesn't match is refused before the invite is used.

How it connects

One way, on every computer: a small background connection of its own, running as you (never as administrator), that starts by itself when you log in. It carries HTTPS to the pen's names, and nothing else (if you type an http:// address, the connection itself sends you to HTTPS). Your other networks, your own Tailscale if you have one, and everything else on the computer are left alone.

That's deliberate: a pen is for websites, and anything more is more for an attacker to use. There's no setting for more: see what Hogman deliberately doesn't do.

In practice

Only programs that use the proxy reach the pen. The join tool prints your proxy address (something like http://127.0.0.1:21234) and sets things up:

More devices

On your pen's home page, press Add a device. You get a one-time link (and a QR code) that works once and expires in an hour. Open it on the other computer and copy the command, as before; the device joins as you. Phones can't join yet; the app is in the works.

To put something in the pen, you don't need another device: see Putting things in your pen.

Updating

$ ./hogman-join update

This downloads the latest hogman-join from your pen's server (or from a host or link you pass: ./hogman-join update 'https://your-host.example'), updates this program, updates your pen's installed agent copy and restarts it if it is running, and refreshes any cached share binaries on disk from that server. If you have shares currently running, they stay up on the old process until you restart them (./hogman-join share stop NAME, then start the share again). On more than one pen? Pick one with --pen ZONE. Use --dry-run to see what would change without touching files.

Before replacing anything on disk, update checks the download's SHA-256 checksum against SHA256SUMS on the same server over the same HTTPS connection. That catches truncated or corrupted downloads and mismatched CDN copies — not a tampered server, which is the same trust model as the first download.

Leaving

$ ./hogman-join leave '<your link>'

This takes down anything you share from this computer, removes the pen's certificate, stops the pen's background connection and removes its settings. Your membership stays; the keeper removes members.

Options

--handle NAMEYour name in the pen, instead of being asked.
--hostname NAMEWhat this device is called (default: the computer's name).
--no-serviceRun in the background without starting at login.
--no-system-proxyDon't change the Mac's proxy setting.
--dry-runCheck the link and the pen, change nothing.
--no-trustDon't add the pen's certificate (you'll handle trust yourself).
--no-openDon't open the home page at the end.
--pen ZONEWhich pen to use with share or update, when on more than one.

Run ./hogman-join --help for the full list.

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