Get Started

Make this computer a machine's way out to the internet: sites the machine visits see your home address, not the cloud's.

Needs: macOS or Linux, the vpn plugin (lnk up boxes), and a box (lnk box start) or any machine you reach over SSH. Nothing to pay for beyond the box.

Quickstart

lnk vpn exit aws-1 home       # aws-1's traffic can leave from here
lnk vpn list                  # the exits this computer keeps, and for whom
lnk vpn exit aws-1 off        # stop

Make this computer a machine's exit

lnk vpn exit gcp-1 home              # a box, by its name in lnk box list
lnk vpn exit me@server.example home  # any host you SSH to, or a name in ~/.ssh/config

The machine gets a SOCKS5 proxy on a Unix socket in its home folder, ~/.config/lnk/vpn/exit.sock, and its connections leave from this computer. A program on the machine has to use the proxy, and give it addresses, not names:

# on the machine: your home address (curl 7.84 or newer)
curl --proxy "socks5://localhost$HOME/.config/lnk/vpn/exit.sock" https://ifconfig.me

Only your user on the machine can use the socket (who can reach what).

The exit runs in the background here. It reconnects when the connection drops, starts again at login, and keeps a Mac awake while it's an exit. For a host that isn't a box, your SSH to it must work without typing anything: a key with no passphrase to type, or your SSH agent. Its sshd must allow forwarding to a socket (AllowStreamLocalForwarding, on by default).

For an agent on a box, use lnk agent exit home instead: it holds the exit for the agent and sends the agent's traffic through it (agents).

Use a port instead of the socket

lnk vpn exit me@server.example home --port   # the proxy on the host's 127.0.0.1:40780

For a program on the machine that takes no Unix socket. The exit is on the port while anyone holds it there. The host's sshd must then keep GatewayPorts at no, the default, or clientspecified; with yes, the exit stops rather than open the proxy to the host's network. To check, on the host:

# must say no or clientspecified
sudo sshd -T | grep -i gatewayports

Stop being its exit

lnk vpn exit gcp-1 off

The exit stops once nobody holds it. You hold it when you run exit home; each agent that exits from home on that machine holds it too, so it stays up while any of them does.

lnk vpn stop    # every exit here, at once; who holds each stays

lnk vpn exit <machine> home starts one again. lnk uninstall runs stop before it removes the programs.

See the exits

lnk vpn list          # each exit, up or down, and who holds it
lnk vpn list --json   # [{"machine", "via", "running", "holders", "socket"}]

Where things live

~/.config/lnk/vpn/exits.toml: the exits this computer keeps.
~/.config/lnk/vpn/<machine>.log: each exit's log.
On the machine, ~/.config/lnk/vpn/exit.sock: the exit's socket.

Troubleshooting

Symptom	Fix
The exit is `down` in `lnk vpn list`	Read `~/.config/lnk/vpn/<machine>.log`; check `lnk box ssh <box>` or `ssh <host>` works
The log says "remote port forwarding failed"	On the host, allow `AllowStreamLocalForwarding` in `/etc/ssh/sshd_config` and reload sshd, or use `--port`
The log says "sshd has GatewayPorts yes" (with `--port`)	On the host, set `GatewayPorts no` in `/etc/ssh/sshd_config` and reload sshd
"isn't a box's name or a host to SSH to"	Use letters, digits and `@._:-`, not starting with `-`
A program on the machine still shows the cloud's address	Point it at the SOCKS5 proxy, `~/.config/lnk/vpn/exit.sock` (`127.0.0.1:40780` with `--port`)

Every flag: lnk vpn --help. What the exit protects and what it doesn't: Security. Why it works this way: Decisions.