Docs › Using Sparehand from a phone, at home or anywhere

Using Sparehand from a phone, at home or anywhere

Two ways to open the dashboard on a phone, a tablet or another computer. Both can be on.

• This network: devices on the same home or office network, paired at the hub with a QR code. Nothing to install; it works only on that network, and without notifications.
• Tailscale: from anywhere, with notifications, once Tailscale is installed and signed in on the hub and on the device.

This network (without Tailscale)

On the hub, open Settings and Phone and other devices (the Mac app: Settings → Devices; the dashboard in a browser on the hub: the gear, then Devices).

1. Switch on. If the hub has several network addresses (Wi-Fi and a cable, say), choose the one on the network your phone uses. The dashboard then answers there, at an address like https://192.168.1.10:8743, to paired devices only.
2. Pair a device… shows a QR code, and the same link as text. Scan it with the phone's camera within five minutes.
3. The phone's browser warns that it doesn't know the certificate: the hub made it itself. Choose to go on (Safari: Show Details, then visit this website; Chrome: Advanced, then Proceed). To be sure it is your hub's, compare the certificate's SHA-256 fingerprint in the browser with the one Settings shows.
4. Give the device a name and press Ask to pair. It shows a 6-digit number.
5. The hub asks Allow this device? with what the device is, its address and that number. Allow it when the number is the one on the phone. The phone opens the dashboard by itself.

From then on the phone opens that address whenever it is on the same network. Settings lists the paired devices with when each was last seen; Remove refuses one from its next request. Switch off closes the dashboard to the network at once, and can forget every device.

Good to know:

• A paired device can do all you can, like a Tailscale login of yours. When allowing it in the dashboard you can give it a person from the People tab instead: a member's device is a member.
• It works on that one network. If the hub moves to another one (a laptop), the dashboard closes to the network by itself and opens again at home.
• If the hub's address changes, devices must be paired again. Give the hub a fixed address in your router (a DHCP reservation) to avoid that.
• A certificate warning on a device that was already paired means something else is answering at that address: don't go on.
• Not in this mode: notifications on the device (browsers give them only to an address whose certificate they trust) and anything from outside the network. For those, use Tailscale as well.
• On a Mac with the firewall on, macOS asks once whether Node may accept incoming connections: allow it.
• app.json: "lanPort" is the port (8743), "lan": false removes the feature.

What is protected and what isn't is in security.md.

From anywhere (Tailscale)

The app and the workers can be reached from outside your home without opening any port on your router, using Tailscale (a private WireGuard network between your own devices). Install it on the hub, every worker you want to reach remotely, and your phone/tablet, all signed in to the same account.

Publish the app on your tailnet

On the hub, with the app running (./install.sh --app):

tailscale serve --bg --https=443 http://127.0.0.1:8730

Tailscale shows the address, e.g. https://my-hub.tail1234.ts.net. HTTPS certificates must be enabled once for the tailnet: admin console → DNS → HTTPS Certificates.

Then put your Tailscale login in ~/.config/sparehand/app.json on the hub:

{
  "port": 8730,
  "allowedLogins": ["[email protected]"],
  "allowedIPs": ["100.101.102.103"]
}

allowedIPs is optional: list your phone's/tablet's Tailscale IPs to allow only those devices of your login. Restart the app after changing it (quit Sparehand from its menu-bar icon and open it again).

On an iPad or iPhone, open the address in Safari and choose Share → Add to Home Screen: it then opens full screen like an app.

The app trusts a login header only after checking it: with the tailscale command on the hub it asks tailscale whois whether the device the request came from really has that login (security.md). The Mac app's command lives at /Applications/Tailscale.app/Contents/MacOS/Tailscale and is found there; a tailscale on the PATH comes first.

Another reverse proxy

If you publish the dashboard through something other than tailscale serve (Caddy, nginx, a tunnel service), it must set the same headers (Tailscale-User-Login, optionally Tailscale-User-Name, and X-Forwarded-For) after authenticating the person itself, and prove it is your proxy with a secret:

{ "port": 8730, "allowedLogins": ["[email protected]"], "proxySecret": "a random string of at least 16 characters" }

The proxy sends it as the X-Sparehand-Proxy-Secret header on every request (openssl rand -hex 24 makes one). A proxied request without the right secret is refused when no tailscale command is on the hub, and otherwise checked with tailscale whois as above.

Letting other people in

Friends or family can use the dashboard with their own Tailscale login, without being able to change anything: the People tab (owners see it) adds a person as a member or an owner, and they open the same address you do. Two ways in:

• Invite by e-mail (the usual one): type their name and e-mail address and press Invite by e-mail. The hub asks Tailscale to invite that address to your tailnet as a member, Tailscale e-mails them the invitation, and the person appears in the list as Invited · not joined yet. They accept the mail, install Tailscale on the device they'll use, sign in there with that address and open the dashboard: the row then shows when they were last here. While the dashboard is open, the hub checks Tailscale's open invitations (at most once a minute): once theirs is gone the row says Accepted the invitation · hasn't opened the dashboard yet. Copy the link copies the invitation's link (the same one as in the mail; anyone with it can accept it, so send it to them only), Send again withdraws the invitation and e-mails a new one, and removing an invited person withdraws it too. Tailscale's own answer is shown when it refuses: the user limit of your plan (the free plan allows a few users), or a key it doesn't accept.
• Add: for someone who is in your tailnet already (you invited them in the admin console, or they share your domain); type their Tailscale login (it looks like an e-mail address).

Copy an invitation, on every row, copies a short message you can send them yourself: accept Tailscale's mail, install Tailscale and sign in with that address, open the dashboard's address (filled in when you're looking at the dashboard over https; from a local browser the text asks them to wait for it).

Inviting needs a Tailscale API access token on the hub: in the admin console open Settings → Keys, generate an API access token (your own user's, not a tag's: an invitation needs an inviting user) and copy it; then run, on the hub (the People tab shows this command too, with a copy button):

security add-generic-password -U -s sparehand-tailscale-api -a tailscale -w "$(pbpaste)"; pbcopy </dev/null

The token goes into your Keychain and never into a file (-w "$(pbpaste)" takes it from the clipboard, so a long token isn't cut short, and the clipboard is cleared after). On a Linux hub put it in ~/.config/sparehand/tailscale-api instead ((umask 077; cat > ~/.config/sparehand/tailscale-api), paste, Enter, Ctrl-D). No restart is needed: without a token the People tab shows these steps and hides the Invite button, and the moment one is there inviting works. app.json can name the tailnet and the Keychain item:

{ "tailscale": { "tailnet": "-", "keychain": "sparehand-tailscale-api" } }

"-" (the default) is the tailnet the token belongs to. Tokens expire (90 days at most): when Tailscale refuses one, the tab says so; make a new one and run the same command.

• A member sees the machines and how busy they are, and uses the Local AI chat with their own saved chats (kept on the hub in ~/.local/state/sparehand/chats/people/), paying with prepaid credits you add on the People tab (credits.md). Everything else answers "Only the owner can do that": no jobs, activity or history, no pausing or switching, no screens, shared folders, sessions, Crew, Studio, Advisor or Helper, and no settings. The page shows them only what they may use.
• An owner can do everything you can, from any of their devices. The logins in allowedLogins are owners too; allowedIPs limits only those.
• Removing a person on the People tab refuses them from the next request on, deletes their saved chats and withdraws an invitation they haven't accepted. People are kept in ~/.local/state/sparehand/people.json (readable by you only), with the invitation's id and link until their first visit.

Everyone who can open the dashboard shares the machines, so a member's chats run on them like yours (each request goes to a free machine that has the model). A member pays for each answer with credits (1 credit = 1 cent) that you sell them and add on the People tab, and their own apps can use the models through the AI hub with an API key; see credits.md.

Access rules

By default every device on a tailnet can reach every other on any port. Tighten that so your tablet can reach the machines, the hub can reach the workers' SSH, and workers can't reach anything. In the admin console → Access controls, with tags or device names that match yours:

{
  "tagOwners": {
    "tag:hub":    ["autogroup:admin"],
    "tag:worker": ["autogroup:admin"]
  },
  "grants": [
    // your phone / tablet: only the app on the hub (screens are relayed through it)
    { "src": ["autogroup:member"], "dst": ["tag:hub"], "ip": ["443"] },
    // the hub may log in to workers and relay their screens; nothing else may
    { "src": ["tag:hub"], "dst": ["tag:worker"], "ip": ["22", "5900"] }
  ]
}

Note that tagged devices aren't "users", so a request from a tagged device through tailscale serve carries no login and the app refuses it. Use the app from personal (untagged) devices.

Turn off key expiry for the hub and workers (machines you own and keep at home) so they don't drop off the tailnet, and keep it on for phones and tablets.

SSH to workers over Tailscale

If you also want jobs to run on a worker while you're away from home, point its SSH alias at its Tailscale name and allow the hub's Tailscale address in the worker's sshd AllowUsers line:

Host worker1
    HostName worker1.tail1234.ts.net

Remote syncs are slower than on your home network; Sparehand still prefers whichever free worker is least busy, so consider a lower --jobs for far-away workers.

Travelling

sparehand away check tests all of this from the Mac you take with you before you leave, and sparehand away on has that Mac tell you when the hub can't be reached: away.md.