harnsy

Relay: reach your machines from anywhere

A computer at home or in an office usually cannot be reached from outside: there is no public address, and a router is in the way. A relay solves that. Your machines connect out to it, and it joins them: your phone opens your dashboard, your laptop works with your home machine. With harnsy Max.

What a relay does. It only passes encrypted bytes along. By design it cannot read your messages, your tokens or your dashboard: the encryption runs from your phone or machine to your other machine, not to the relay. It does see which machines connect, when, and how much data goes. With the harnsy relay there is one more point of trust: see «What you trust here».

Two jobs (one relay can do both):

  • Open the dashboard of a machine from your phone or another computer, at an address like https://k3f9q2.n.harnsy.app.
  • Join the machines of one team (a cluster) that cannot see each other directly, for example a laptop as the main machine and a server as a member.

Which relay

harnsy relayPersonal relayYour own relay
Where it runsour server, relay.harnsy.app (beta)a server of yoursa server of yours
Forany of your machinesone computer, one name of yoursseveral machines and their dashboards
You set upnothing: one buttonone name in DNS, one command, one line to pastea name, a wildcard name, a service, a token per machine
Needsharnsy Maxa harnsy Max key on the servera licence with the «relay of your own» right

Start with the harnsy relay. Take your own when you do not want your traffic to pass a machine of ours.

Open the dashboard from your phone: the harnsy relay

  1. On the machine, open the dashboard: Settings › Reach from outside › «The dashboard on a phone or laptop», step «Access from the internet».
  2. Choose harnsy relay and press Apply. There is nothing to fill in. Within about 15 seconds the step shows «relay connected» and the address, https://<id>.n.harnsy.app. The certificate for it comes by itself.
  3. Bind your phone: in the «Add your phone or laptop» step press «Make a code» and scan the QR code with the phone. The code works once, for 5 minutes.
  4. On the phone, create the passkey at once (fingerprint, face or PIN), then sign in with it. The full steps, with what the phone may do before and after: Use harnsy on your phone as an app.

The address stays the same. It comes from the machine's own key. If you later switch to another way in, the address changes, and the phones bound to the old one have to be added again.

What you trust here. The relay passes the encrypted bytes on and cannot read them, but our licence service holds the DNS key of n.harnsy.app, so whoever holds that key could get a certificate for your name. harnsy watches the public certificate logs and rings the bell if a certificate it did not ask for appears. Your own domain or your own relay needs no such trust.

The harnsy relay is a beta: its address and limits (a monthly traffic allowance, a speed per connection) may still change. What it records and for how long: Privacy: the harnsy relay.

Join your machines through the relay

For a main machine with no address the other machines can reach, such as a laptop or a home computer.

  1. On the main machine, in a terminal, turn the relay on:
    Shell
    harnsy debug cluster relay on

    It uses the harnsy relay. Restart harnsy on that machine: it takes the change at its next start. There is no switch for this in the dashboard; Settings › Machines only shows «relay on» or «relay down».

  2. Open Settings › Machines › «+ Connect a machine», leave the address empty and press «Get the command». The window says «the connection goes through the harnsy relay, nothing to set up». Run that one command on the other machine. The steps: Several machines.
  3. Check: Settings › Machines shows each machine that joined.

harnsy debug cluster relay shows the relay and its state. harnsy debug cluster relay off turns it off; members then need a direct address again. Restart harnsy after off, too. (The shorter harnsy cluster relay … does the same.)

The connection between the machines is encrypted and pinned to the main machine's certificate, so, by design, the relay joins encrypted streams and does not read them.

A personal relay: one computer at a name of yours

We have not yet run this end to end on a real server: the steps follow harnsy's code and its own documentation. Try it on a spare server first, and tell us if a step does not work.

For one computer that should open at a fixed address of your own, for example https://harnsy.example.com, from your phone. Nothing is offered to other machines.

You need: a small Linux server with a public address and port 443 free; a name you control; harnsy Max. Your key on the server takes one of the key's machines, like any computer of yours; hr license deactivate on the server gives it back (the hr of «Your own relay», step 1; up to 3 times in 30 days).

  1. DNS: one A record, harnsy.example.com → the server.
  2. On the server: put the harnsy program there (the Linux archive of a release is enough; do not run the installer and do not start harnsy serve), add your licence (see «Your own relay», steps 1 and 2), then run:
    Shell
    harnsy relay serve --personal harnsy.example.com

    The first start prints one binding line that begins with harnsy-relay://. It is a secret: it is shown once and kept nowhere. Behind NAT add --public-ip <ip>.

  3. On your computer: Settings › Reach from outside › «The dashboard on a phone or laptop» › Own relay › paste the line › Connect. The computer gets the certificate for harnsy.example.com by itself and then opens at https://harnsy.example.com. Bind your phone as above.

The first computer that connects with the line is bound to the relay for good; another one with the same line is refused. Lost the line before any computer used it? harnsy relay line on the server prints a new one (the old one stops working). To move to another computer, run harnsy relay unbind on the server: it cuts the bound computer off and prints a new line. If the server's address changes, do the same; the name for the phone stays.

Your own relay: several machines and dashboards

We have not yet run this end to end on a real server: the steps follow harnsy's code and its own documentation. Try it on a spare server first, and tell us if a step does not work.

The same program on a server you run. Your traffic goes through a machine you own, and nothing is asked of our licence service.

You need

  1. A Linux server with a fixed public address. Port 443 free and open in its firewall.
  2. A name for it, for example relay.example.com, pointed at the server. For your machines' dashboards also a wildcard name, for example *.n.example.com, pointed at the same server.
  3. A licence with the «relay of your own» right. Without it the relay does not start and says edition_relay_host. The key on the server takes one of its machines; hr license deactivate gives it back (up to 3 times in 30 days).
  4. The harnsy program on the server: the Linux archive of a release is enough. Do not run the installer there and do not start harnsy serve.

1. Give the relay its own folder and user.

Shell
sudo useradd --system --create-home --home-dir /var/lib/harnsy-relay harnsy-relay
sudo install -m 0755 harnsy /usr/local/bin/harnsy
alias hr='sudo -u harnsy-relay env HARNSY_HOME=/var/lib/harnsy-relay harnsy'

Every hr … command below runs as that user with that folder.

2. Add the licence.

Shell
hr license add /path/to/your-licence-file
hr license

3. Try it by hand once.

Shell
hr relay serve --addr :443 --domain relay.example.com --email you@example.com

harnsy gets a free certificate for the name from Let's Encrypt on port 443 (port 80 is not needed). When it prints harnsy relay on …, it works; stop it with Ctrl+C. If it stops with a message about the certificate, the name does not point at this server yet, or port 443 is closed.

With a certificate of your own instead: --cert cert.pem --key key.pem. The relay then prints relay pin sha256/…: keep it, your machines need it.

4. Make it start by itself. Create /etc/systemd/system/harnsy-relay.service:

INI
[Unit]
Description=harnsy relay
After=network-online.target
Wants=network-online.target

[Service]
User=harnsy-relay
Environment=HARNSY_HOME=/var/lib/harnsy-relay
ExecStart=/usr/local/bin/harnsy relay serve --addr :443 --domain relay.example.com --web-zone n.example.com --web-acme
Restart=always
AmbientCapabilities=CAP_NET_BIND_SERVICE
NoNewPrivileges=yes
ReadWritePaths=/var/lib/harnsy-relay

[Install]
WantedBy=multi-user.target
Shell
sudo systemctl daemon-reload
sudo systemctl enable --now harnsy-relay
sudo systemctl status harnsy-relay

--web-zone (the wildcard name without *.) and --web-acme are only for dashboards; to join machines only, leave both out.

5. A token for each machine.

Shell
hr relay token add home-pc

It prints a line that starts with hrelay_ once. Copy it now: harnsy keeps only a fingerprint. One token per machine, named after it; hr relay token list shows them, hr relay token revoke home-pc cancels one.

6. Connect your machines.

  • Machines of a team: on the main machine run harnsy debug cluster relay on --url https://relay.example.com --token hrelay_… (add --pin sha256/… for a certificate of your own), then restart harnsy there. Connect the other machines as in «Join your machines through the relay».
  • A machine's dashboard: on that machine, Settings › Reach from outside › «The dashboard on a phone or laptop» › Own relay: the relay address, the token, the zone (n.example.com) and, only for a certificate of your own, the pin. Press Apply. Within about 15 seconds the step shows the relay connected and the address https://<id>.n.example.com, which stays the same for this machine.

Every day

  • Logs: journalctl -u harnsy-relay. Restart: sudo systemctl restart harnsy-relay; machines reconnect by themselves.
  • Update: put the new harnsy in place of /usr/local/bin/harnsy, then restart the service.
  • Cancel a machine: hr relay token revoke <name>. Block one: hr relay ban add <id> "why"; hr relay ban list, hr relay ban remove <id>.
  • If the licence is gone or has ended, a running relay accepts no new machine.

Is it working

You seeUsually
the step says it cannot connect to the relaya wrong token or pin, or the relay cannot be reached; the message names which
the page does not open from the phonethe machine is asleep or offline; or, with your own relay, the wildcard name does not point at the server
the relay does not start: edition_relay_hostthe licence on the server has no «relay of your own» right
a certificate error on the serverthe name does not point at the server yet, or port 443 is closed
a second computer is refused by a personal relaythe line is bound to the first computer: harnsy relay unbind on the server
members stopped joining after relay offthey need a direct address again, or turn the relay back on

Safety, in short

  • Keep a token or a binding line like a password: it is shown once; give one to one machine.
  • The relay cannot read your traffic, by design; with the harnsy relay you also trust our licence service with the DNS key of your address (see «What you trust here»). It sees which machines connect and how much data goes. Keep your relay server updated, with only port 443 open to the world.
  • A phone signed in from outside can give orders to your agents, and agents can run commands on your machine. Give the phone a screen lock and sign out a lost device at once: Settings › Reach from outside › Devices.

What it does →

Questions? Ask on Discord →

Anthropic, Claude Code, OpenAI, ChatGPT, Codex, OpenCode, pi, Telegram, Discord, GitHub, Apple, macOS, iOS, iPhone, Safari, Google, Android, Chrome, Microsoft, Windows, Windows Security, Defender and QR Code are names of their owners’ products. harnsy is not affiliated with or endorsed by them. iOS is a trademark of Cisco used under licence by Apple; QR Code is a registered trademark of DENSO WAVE INCORPORATED. No logos.