harnsy Max
Open the dashboard from outside: a step-by-step guide
For a person who wants to reach harnsy from a phone or a laptop away from home.
What you need
- harnsy Max on this machine (the license flag
mobile). Without it the page opens but does nothing. - A name, for example
harnsy.example.com, that you control in DNS. - A way for the internet to reach harnsy. Pick one:
- The machine is on the internet itself (a VPS, a server): recipe A. Simplest.
- harnsy runs at home, and you rent a small VPS as a door : recipe B. The VPS only passes encrypted bytes; it cannot read them. Best for a home machine.
- You already run nginx with a certificate and a VPN to the machine : recipe C. It can also let in only VPN clients.
- A phone or laptop with a passkey: a phone with a screen lock (Android 9+, iPhone), or a laptop with Windows Hello, Touch ID or a security key.
Steps, in order
Choose the door above and follow its recipe in
gateway-recipes.mdup to the config file. Point the DNS record of your name at the machine that faces the internet.Write the settings in
~/.harnsy/config.yamland restart harnsy (they are read once, at start). The shortest form, for recipe A:~/.harnsy/config.yaml
gateway: addr: ":443" hosts: harnsy.example.com tls: acme: true email: you@example.comacme: truelets harnsy get the certificate itself. Use one name inhosts: a passkey belongs to the name it was made on.Check on the machine itself: open the dashboard, System › “Access from outside”. It says whether the gateway listens, on which address and name, and how the certificate comes. If it is not open, it says why; fix that first.
Bind the phone. On the same page press “Make a code” in the “Add your phone or laptop” step. A QR code appears; it works once, for 5 minutes. Scan it with the phone. (On a VPS with no screen, reach the dashboard through
ssh -L 7788:127.0.0.1:7788 you@vps, recipe A step 5.)Create the passkey at once. The phone offers “Create a passkey”: confirm with fingerprint, face or PIN. This must happen within 15 minutes of the scan, and only once per scan. Until then the phone can only read.
Sign in with the passkey. The session the QR code gave is only for binding: it can read, pause a team after its step and create the passkey, and it ends after a day. Open the login page and use its button (no name, no password). Only a session that signed in with the passkey can change things. It stays signed in for up to 7 days unused and at most 30 days; then sign in again the same way.
Working from outside
- Reading needs only the session. Changing anything (sending a message, answering an agent, deciding a task) from a session that signed in with its passkey asks for your passkey once, and the check holds for 15 minutes.
- Full control is a separate switch on the local dashboard only: typing into terminals, starting agents, stopping a team at once, changing settings. It is off by default and switches itself off after 2 hours (1 to 24, set next to the switch). Turn it on only while you need it.
- Every new device, a code made, a passkey added and full control switched on show up in Home (“Needs you”) on the machine.
If something does not work
| You see | Usually |
|---|---|
| the login page says access from outside is not allowed | the license has no mobile flag |
| the page does not open at all | DNS, the firewall or the port; the local page in step 3 says whether the gateway listens |
421 | the name in the browser is not in hosts |
| a certificate error | acme: true needs port 443 reached from the internet (recipe A/B), or give your own files |
| “Create a passkey” is refused | the 15 minutes passed, or this scan already made one: make a new code |
| a change asks to confirm with the passkey again | the 15-minute check ran out; confirm again. A phone that only has the QR session must first sign in with its passkey (step 6) |
| a change is refused with “full control is off” | switch it on at the local dashboard (it may have switched itself off) |
429 | too many tries from one address; wait a little |
Something lost or stolen: sign the device out at the local dashboard (Access from outside › Devices), or sign out everywhere.
Reference for the details: gateway.md (what is allowed, limits, threat model) and gateway-recipes.md (the three ways to reach the node, with every command).