t1k:vpn
| Field | Value |
|---|---|
| Module | t1k-base |
| Version | 5.15.36 |
| Effort | low |
| 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
How to invoke
Section titled “How to invoke”/t1k:vpninstall | 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.
| Fact | Value |
|---|---|
| Management server | https://vpn.the1studio.org |
| Access | No open registration — admin (Manh) creates user accounts or setup keys |
| Connectivity canary | https://greeting.the1studio.org — must greet when Connected |
| Peer IPs | every peer answers on 10.100.x.x |
| Encryption | WireGuard, 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.
| Host | NetBird name | Note |
|---|---|---|
| sv-2 (production) | sv-2.theone.netbird | plain sshd; DNS comes from the NetBird daemon |
| the1-sv | the1-sv.theone.netbird | CCS gateway box |
| sv-1 | sv-1.theone.netbird | verify 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.
Step 0 — Detect state before acting
Section titled “Step 0 — Detect state before acting”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.
Install (auto per platform)
Section titled “Install (auto per platform)”| Platform | Command |
|---|---|
| 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. |
| macOS | brew install netbirdio/tap/netbird (no brew: app from https://netbird.io/downloads) |
| Windows | winget install Netbird.Netbird (fallback: MSI from https://netbird.io/downloads; on t1k workstations with WinPodX, drive the MSI via winpodx app run) |
| Linux desktop GUI | optional — 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).
Enroll / connect
Section titled “Enroll / connect”Two credential paths — always obtain at runtime, never persist:
- Setup key (servers, CI, headless): ask the user to paste it, then
Never write the key to any file, log, env file, or commit. After
Terminal window sudo netbird up --management-url https://vpn.the1studio.org --setup-key <KEY>up, it is no longer needed — the daemon stores its own identity. - User account (personal devices):
netbird up --management-url https://vpn.the1studio.orgwithout 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)”sudo netbird status→ daemonConnected, peers listed.curl -fsS --max-time 10 https://greeting.the1studio.org→ must return the greeting. If not, run Self-heal before reporting success.
Self-heal playbook
Section titled “Self-heal playbook”Symptom → fix, in order (from TUTORIAL §4–5):
| Symptom | Fix |
|---|---|
Internal *.the1studio.org hangs / 403 after sleep or Wi-Fi switch | wait ~10s, then sudo netbird down && sudo netbird up, reload; hard-refresh the page |
| App/CLI shows not Connected | sudo 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 failing | collect sudo netbird status -d (especially the DNS section) and hand to the admin |
After any fix, re-run the Verify step.
Ground rules
Section titled “Ground rules”- 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 downon a machine you don’t own without saying so first.
References
Section titled “References”- TheOne-VPN TUTORIAL.md — colleague guide (SSOT for URLs and symptoms)
- TheOne-VPN dashboard-guide.md — admin: groups, policies, setup keys