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
- Open your invite link on the computer you want to join. Invites work once and expire after 7 days.
- Copy the command it shows into a terminal. It downloads
hogman-joinfor 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=…' - 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 inSHA256SUMS:Mac, Apple silicon hogman-join-Darwin-arm64Mac, Intel hogman-join-Darwin-x86_64Linux, x86-64 hogman-join-Linux-x86_64Linux, ARM (Raspberry Pi 4/5, ARM servers) hogman-join-Linux-aarch64Windows (untested) hogman-join-windows-amd64.exe - Pick your name when asked: lowercase letters, digits and dashes, 2 to 32 characters. It's how the pen knows you.
- 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.
- You're in. It checks your pen's home page loads over HTTPS and opens it.
Keep the
hogman-joinfile: 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:
- Browsers: on a Mac, the tool sets the automatic proxy setting for you
(it never replaces one someone else set). On Linux and Windows, set your browser's or
desktop's automatic proxy configuration URL to the
proxy.pacaddress it prints. The rules file sends only pen names through the pen. - curl and most command-line tools, per command:
$ https_proxy=http://127.0.0.1:21234 curl https://blog.smith.hogmanDon't export it for the whole shell: the proxy refuses everything outside the pen. - git, per site:
$ git config --global http.https://git.smith.hogman/.proxy http://127.0.0.1:21234
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 NAME | Your name in the pen, instead of being asked. |
--hostname NAME | What this device is called (default: the computer's name). |
--no-service | Run in the background without starting at login. |
--no-system-proxy | Don't change the Mac's proxy setting. |
--dry-run | Check the link and the pen, change nothing. |
--no-trust | Don't add the pen's certificate (you'll handle trust yourself). |
--no-open | Don't open the home page at the end. |
--pen ZONE | Which 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.