From a989f8fbfa43d554335be1b272c42cf04afefe6e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Andr=C3=A9=20Padez?= Date: Wed, 12 Aug 2026 20:34:40 +0000 Subject: [PATCH] say where offscale runs, which matters more than how it installs MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit "One command to install" was the wrong emphasis and read as though it happens here. It does not: a coordination server has to be reachable by every device that joins, including phones on mobile data and laptops in other buildings, so it needs an address that resolves from anywhere. It goes on a small public VPS of its own — not this machine, and not behind a home router. That is the thing people get wrong, and getting it wrong produces a private network unreachable from exactly the devices it exists to reach. It is a property of being the thing everyone checks in with, so it is true of headscale too, and the long answer now says so. Choosing option 1 leads with it, links the install anchor rather than the page, and says plainly that nothing below will work until that server is up and answering — so somebody who has not done it stops here instead of typing an address that does not exist yet. "Installs in one command" survives in the goodies list, where it belongs: it is one command ON THAT SERVER, and the sentence now says so. Co-Authored-By: Claude Opus 5 (1M context) --- scripts/setup/machine-setup/lib/tailscale.sh | 24 ++++++++++++++++---- scripts/setup/machine-setup/machine-setup.sh | 11 ++++++--- 2 files changed, 27 insertions(+), 8 deletions(-) diff --git a/scripts/setup/machine-setup/lib/tailscale.sh b/scripts/setup/machine-setup/lib/tailscale.sh index 3482ba86..39b7f498 100644 --- a/scripts/setup/machine-setup/lib/tailscale.sh +++ b/scripts/setup/machine-setup/lib/tailscale.sh @@ -65,11 +65,15 @@ tailscale_network_menu() { echo " Your own coordination server. The protocol on the wire is" echo " Tailscale's and the encryption is WireGuard's; offscale changes" echo " neither — it runs headscale's open-source code. What changes is" - echo " the work: one command to install, certificates included, managed" - echo " from an app rather than a terminal, and enrolling a device is a" - echo " link and a tap. Set it up first, then come back here with its" + echo " the work: managed from an app rather than a terminal, and" + echo " enrolling a device is a link and a tap." + echo " It runs somewhere publicly reachable — a small VPS — not on this" + echo " machine and not at home. Every device has to be able to find it," + echo " including the ones that are not on your network, so it needs an" + echo " address that resolves from anywhere." + echo " Follow that setup through first, then come back here with its" echo " address and a key." - echo " https://officer.dev/infrastructure/offscale.html" + echo " https://officer.dev/infrastructure/offscale.html#install" echo "" echo " [2] use a network you already run — headscale or offscale" echo " You already have a coordination server somewhere. Point this" @@ -129,8 +133,18 @@ tailscale_networks_help() { echo " Tailscale's. Desktop apps of our own are not there yet; on a" echo " computer you point the official client at your own server." echo "" + # Where it runs matters more than how it installs, and is the thing people + # get wrong: a coordination server at home is unreachable from exactly the + # devices a private network exists to reach. + echo " Where it runs: somewhere publicly reachable, on its own — a small" + echo " VPS is enough. Not on this machine, and not behind a home router." + echo " Every device that joins has to find it, including phones on mobile" + echo " data and laptops in other buildings, so it needs an address that" + echo " resolves from anywhere. That is true of headscale too; it is a" + echo " property of being the thing everyone checks in with." + echo "" echo " What it does that plain headscale does not:" - echo " · installs in one command, with the certificates handled" + echo " · installs in one command on that server, certificates included" echo " · health, logs, restarts and access policies from the app," echo " instead of a config file and a CLI" echo " · enrolling a device is a link and a tap — the key is minted" diff --git a/scripts/setup/machine-setup/machine-setup.sh b/scripts/setup/machine-setup/machine-setup.sh index 721a1dd5..ad531621 100755 --- a/scripts/setup/machine-setup/machine-setup.sh +++ b/scripts/setup/machine-setup/machine-setup.sh @@ -457,9 +457,14 @@ if ! skip; then # what to say, not what to do. if [[ "$TS_PLANE_CHOICE" == "1" ]]; then echo "" - echo " Install offscale first — one command, per" - echo " https://officer.dev/infrastructure/offscale.html — then give" - echo " this machine its address and a key." + echo " offscale runs on a publicly reachable server of its own — not" + echo " this machine, and not behind a home router. Work through the" + echo " whole setup there first:" + echo "" + echo " https://officer.dev/infrastructure/offscale.html#install" + echo "" + echo " Then come back here with its address and a key. Nothing below" + echo " will work until that server is up and answering." fi # No default offered. A coordination server URL is somebody's private # infrastructure, and a machine that joins the wrong one has joined a