How-To · 5 min
Licences, devices & 402s
One page for all of licensing: how it works, both activation paths, restoring after a trial, registering headless machines, device limits, offline behaviour — and every cause of a 402 with its fix.
How licensing works
Three facts make the rest of this page simple: a licence is attached to your CHYNJ account email, however it was issued; a device is "connected" when its fingerprint is registered against the licence — Kaptain does that for you at activation (only a SHA-256 of the fingerprint ever leaves the machine); and your account portal is the source of truth — your key and every connected device live there, even if a licence email never arrived (check spam for [email protected], or just copy the key from the portal's License card).
Activate: sign in, or paste a key
Option A — sign in (recommended). On the wizard's Account step, sign in with the account the licence is on (2FA code if enabled). Kaptain finds the licence attached to your email, applies it, and registers this machine automatically — it appears under Devices in your portal, and the device certificate enrolls in the same act. From then on the box re-checks your account every few hours, so renewals and licence moves apply themselves.
Option B — paste the key. On the Plan step, Have a license key? reveals the field (already visible on an expired-trial machine); paste KAPTAIN-XXXXXXXX-XXXX-XXXX and continue. Use this when only the key travelled — a teammate's machine, say.
Restore after a trial (including a remote machine)
A trial binds to the machine, so a box whose trial ended doesn't know about a licence you got later. You never reinstall — the licence and sign-in screens stay reachable on an expired box. On that machine, sign in (durable: licensing becomes automatic from then on) or paste the key on the "Trial expired" screen. Remote? With Tailscale enabled open http://<its-tailnet-address>:8810 from anywhere; otherwise SSH/remote-desktop in and open http://localhost:8810 there.
Headless box (SSH only): kaptain device register (flags: --nickname "build-server", --no-browser, --json) — it prints a URL and short code and waits; approve from any browser; it finishes by printing this box's access code once; then kaptain stop then kaptain start (one line on Linux/macOS: kaptain stop && kaptain start). Nothing is ever pasted into the command and a password is never typed into the CLI. (kaptain account accepts only status/open; kaptain license only status/refresh — no signin, no set.)
402 — every cause
Every API answer of 402 carries the same message: this machine holds no current signed entitlement. These are all the ways to get here, and the right fix for each:
| Cause | How it happens | Fix |
|---|---|---|
| Never bound (the common one) | fresh install where account sign-in was skipped | kaptain device register — steps below |
| Device revoked | the device was deleted in your account portal | re-register the same way |
| Lease expired | the box was offline long enough that the background refresh couldn't renew (a short outage is fine — leases outlive it) | reconnect to the internet; it renews itself. Still 402 after that: re-register |
| Moved to new hardware | the data folder was copied to a different machine — the certificate is bound to the original installation | register the new machine (see moving a box) |
| Trial ended | the server stops issuing leases when the trial is consumed | subscribe or restore in the portal, then refresh |
| Clock skew | the machine's clock is far enough off that the lease "isn't valid yet" | fix the system clock |
| Build below minimum version | a lease can require a minimum safe Kaptain version | Settings ▸ Update Kaptain, or kaptain update |
kaptain device status and kaptain license status print exactly which of these this machine is in. (Dev builds without compiled trust keys don't run this gate at all — 402 is a release-build behaviour.)
The fix, step by step
- On the Kaptain machine:
It prints a short pairing code and waits.kaptain device register - Open chynj.ca/account (any device), sign in, approve the code. The command notices within seconds.
- It finishes by writing the device certificate and a fresh access code (
chynj_…) — shown once. Save it: every paired browser and phone re-pairs with this new code, one time. - Restart if it was running:
kaptain stopthenkaptain start(one line on Linux/macOS:kaptain stop && kaptain start). 402s are gone.
Codes expire if left unapproved — if the portal rejects one, just run the command again for a fresh code.
What changes afterwards
- The machine appears under Devices in your account portal, and can be removed there.
- Kaptain keeps its entitlement fresh in the background — brief network loss is fine; it fails closed only when the certificate can't be verified at all.
- Updates from the website (Settings ▸ Update Kaptain) install signed builds that keep working, because the trust keys travel with the release.
Why pasting a licence key isn't enough
A licence key activates a plan; the device certificate proves this machine may use it. Pasting a key alone never issues a certificate — sign in during setup or run kaptain device register. Until one has run, a release build can refuse the machine with exactly the 402 this page opens with.
Devices, limits & offline
- Limits: a Pro licence allows up to 5 connected devices; a 6th is refused until you free a slot. The portal's Devices list shows every machine with nickname and last-seen — Sign out frees the slot (that box drops out of Pro until re-activated; nothing else is affected). Re-activating a removed device later is fine.
- Validation & offline: after activation Kaptain re-checks the licence at startup and roughly every 4 hours. Temporarily offline, it runs on a signed local cache and re-validates when back online — you never re-enter anything.
Troubleshooting
- No licence email: you don't need it — the key is in your portal's License card, or just use sign-in activation.
- "No license found for this account": the licence lives on a specific email — confirm the portal email matches where it was issued.
- "Device limit reached": portal ▸ Devices ▸ sign out a machine you no longer use, then activate again.
- "Invalid license key": re-copy with the portal's Copy button — stray spaces are the usual culprit.
Agent-readable version: index.md · Every claim on this page was exercised on a real install before being written. Something missing that cost you time? That is a documentation bug — tell us.