Skip to content

t1k:vpn

FieldValue
Modulet1k-base
Version5.15.36
Effortlow
Tools—

Keywords: 10.100.x.x, greeting.the1studio.org, internal network, netbird, netbird connect, netbird install, netbird status, netbird up, peer, plane unreachable, relayed, setup key, theone vpn, vpn, vpn down, vpn install, vpn not working, vpn troubleshoot, vpn.the1studio.org, wireguard

/t1k:vpn
install | status | connect | disconnect | doctor <internal-url>

TheOne VPN (NetBird) — install, connect, self-heal

Section titled “TheOne VPN (NetBird) — install, connect, self-heal”

Share pages and files with peers over NetBird: t1k-netbird-share.

The org’s private network is self-hosted NetBird. Human-readable guide: The1Studio/TheOne-VPN TUTORIAL.md. This skill is the agent procedure for the same machine work.

FactValue
Management serverhttps://vpn.the1studio.org
AccessNo open registration — admin (Manh) creates user accounts or setup keys
Connectivity canaryhttps://greeting.the1studio.org — must greet when Connected
Peer IPsevery peer answers on 10.100.x.x
EncryptionWireGuard, end-to-end; server only coordinates

NetBird is the studio standard (Tailscale is legacy)

Section titled “NetBird is the studio standard (Tailscale is legacy)”

Reach every studio server and internal site over NetBird. Do not start new work on Tailscale (decided 2026-10-20 after a workstation’s Tailscale lost its coordination server and stranded the production host sv-2 for 12 hours). Old docs, memory notes and ProxyCommand='tailscale nc ...' recipes that say otherwise are stale: replace them, do not follow them.

HostNetBird nameNote
sv-2 (production)sv-2.theone.netbirdplain sshd; DNS comes from the NetBird daemon
the1-svthe1-sv.theone.netbirdCCS gateway box
sv-1sv-1.theone.netbirdverify with netbird status -d before relying on it

SSH over NetBird needs no ProxyCommand and no Tailscale daemon: ssh root@sv-2.theone.netbird. A first connection to a name you have only trusted by its old address fails host-key verification; compare the key (ssh-keyscan <name> against the known_hosts entry for the old address), then -o HostKeyAlias=<old entry> or add the name. Peer addresses live in netbird status -d; never copy an address into a doc.

Terminal window
command -v netbird && netbird version # CLI present?
sudo netbird status 2>/dev/null || netbird status 2>/dev/null # daemon + Connected?

Desktop app presence: netbird ui command exists on desktop installs. Never reinstall over a working install — jump straight to Verify.

PlatformCommand
Linux — mutable distros (incl. Arch; CLI + daemon)curl -fsSL https://pkgs.netbird.io/install.sh | sh (needs sudo, see the gate below)
Linux — immutable/ostree (Bazzite, Silverblue, Kinoite; /run/ostree-booted exists)Hand the install to the user’s own terminal: curl -fsSL https://pkgs.netbird.io/install.sh | sh. It layers the package with rpm-ostree, so netbird exists only in the staged deployment and is NOT on PATH until a reboot. After reboot: sudo netbird service install && sudo netbird service start if systemctl is-active netbird is not active, then connect. Use sudo rpm-ostree apply-live --allow-replacement ONLY when rpm-ostree status shows no staged deployment; otherwise it live-applies the whole pending OS update.
macOSbrew install netbirdio/tap/netbird (no brew: app from https://netbird.io/downloads)
Windowswinget install Netbird.Netbird (fallback: MSI from https://netbird.io/downloads; on t1k workstations with WinPodX, drive the MSI via winpodx app run)
Linux desktop GUIoptional — app from https://netbird.io/downloads; CLI below is sufficient

Phones (iPhone/iPad/Android) cannot be automated from here: point the user at “NetBird: P2P VPN” (App Store) / “NetBird” (Google Play), server URL https://vpn.the1studio.org (Android: menu → Change Server; iOS: alternate server option), then browser login.

sudo gate (Linux): the installer needs sudo with a password and an agent has no TTY to answer it. Run sudo -n true first; if it fails, stop and hand the install command to the user’s own terminal instead of attempting it.

The daemon auto-starts on boot; on systemd systems confirm systemctl is-active netbird after install (on ostree: after the reboot).

Two credential paths — always obtain at runtime, never persist:

  • Setup key (servers, CI, headless): ask the user to paste it, then
    Terminal window
    sudo netbird up --management-url https://vpn.the1studio.org --setup-key <KEY>
    Never write the key to any file, log, env file, or commit. After up, it is no longer needed — the daemon stores its own identity.
  • User account (personal devices): netbird up --management-url https://vpn.the1studio.org without a key opens the browser device-flow login; GUI app: enter the same URL when asked, sign in, approve the VPN permission dialog.

Verify (mandatory after any install/connect)

Section titled “Verify (mandatory after any install/connect)”
  1. sudo netbird status → daemon Connected, peers listed.
  2. curl -fsS --max-time 10 https://greeting.the1studio.org → must return the greeting. If not, run Self-heal before reporting success.

Symptom → fix, in order (from TUTORIAL §4–5):

SymptomFix
Internal *.the1studio.org hangs / 403 after sleep or Wi-Fi switchwait ~10s, then sudo netbird down && sudo netbird up, reload; hard-refresh the page
App/CLI shows not Connectedsudo netbird up (setup-key path re-asks for the key) or reconnect in app
Login expired (peer page says so)reconnect in app / re-run netbird up
Status says “relayed”works but slow — UDP blocked by the network; suggest comparing on mobile data
Still failingcollect sudo netbird status -d (especially the DNS section) and hand to the admin

After any fix, re-run the Verify step.

  • One account = one person. Never share credentials or setup keys, never commit them.
  • Admin can see and revoke devices at any time.
  • Don’t run netbird down on a machine you don’t own without saying so first.