Docs › Reaching a worker's services from the hub

Reaching a worker's services from the hub

sparehand forward makes a service that runs on a worker reachable on the hub as if it ran there. Typical uses: a local AI model server on the worker with the GPU, a database, or a dev server. In the Mac app the same is under Settings → Machines → the machine → Services reached from this Mac (Add…, Stop).

sparehand forward gaming-pc 11434          # gaming-pc's port 11434 → localhost:11434 here
sparehand forward linux-box 5432 15432     # its PostgreSQL → localhost:15432 here
sparehand forward list
sparehand forward stop gaming-pc 11434

PORT is the service's port on the worker; LOCAL-PORT (1024 to 65535, default the same as PORT) is where it appears on the hub. sparehand forward list shows each forward and whether it is connected. A GPU example is in gpu.md. sparehand emulator start makes one for each Android emulator it boots on a worker.

How it works and what it allows:

It's an SSH tunnel (ssh -N -L 127.0.0.1:LOCAL:127.0.0.1:PORT) over the connection Sparehand already uses. Nothing new is opened on the worker or on the network.
Only the hub itself can use it: the local end listens on 127.0.0.1.
It reaches only services on the worker itself (its 127.0.0.1), not other machines.
Forwards are remembered in ~/.config/sparehand/forwards. The Mac app reconnects dropped ones every minute (after sleep, a network change, the worker restarting); elsewhere run sparehand forward up (for example from cron or a login item).
One local port serves one forward; a port that another forward or program already uses is refused.
Before a forward is reported as connected, one connection is tried through it, so a service that isn't running, or a worker that refuses forwarding, is reported straight away.

When a worker refuses forwarding

Machines added with pairing allow tunnels to their own services only (permitopen="127.0.0.1:*",permitopen="localhost:*" on the hub's key). Machines paired with an earlier version have no-port-forwarding in that key's options in ~/.ssh/authorized_keys, and refuse every tunnel. To allow tunnels to that worker's own services only, replace no-port-forwarding in that key's options with:

permitopen="127.0.0.1:*",permitopen="localhost:*"

That is a change on the worker you make yourself; Sparehand doesn't change it.