t1k:web:devops:selfhost-netbird
| Field | Value |
|---|---|
| Module | devops |
| Version | 1.31.4 |
| Effort | medium |
| Tools | — |
Keywords: access groups, internal api, internal dashboard, internal service, internal tool, mesh-only, netbird proxy, netbird service, netbird-only access, no login, playablelabs.ai service, private service, reverse proxy service, the1studio.org service, whoami headers, x-netbird-groups, x-netbird-user
How to invoke
Section titled “How to invoke”/t1k:web:devops:selfhost-netbird[new|edit|verify|retire] <name>.<zone>Internal Service on the NetBird Mesh
Section titled “Internal Service on the NetBird Mesh”For a service that only people (and servers) inside the company need: publish it as
<name>.<zone> through the NetBird reverse proxy. The mesh is the login. There is no app-level
auth screen, no Cloudflare Access app, no password. A caller’s NetBird peer identity arrives as
headers, and their NetBird groups are the only authorization input you implement.
Access model in one line: admission is per-peer, authorization is per-group, and both are enforced before a byte of your code runs. Anything your service adds on top is optional.
Not this skill: installing/connecting the VPN client on a machine (→ /t1k:vpn), deciding which
box or tier the service belongs on (→ /t1k:web:devops:placement), a public app on Cloudflare
Tunnel + Access (→ /t1k:web:devops:selfhost-cloudflare), a Worker on the edge reachable only
through this proxy with an Access service token (→ /t1k:web:devops:cloudflare-internal-netbird).
Pick the zone first; the proxy cluster, wildcard cert and access defaults all follow from it.
| Zone | Cluster | Reachability | Use for |
|---|---|---|---|
the1studio.org | netbird-proxy-the1studio | NetBird peers only | studio tools, dashboards, internal APIs |
playablelabs.ai | netbird-proxy-playablelabs | NetBird peers only | playable-labs internal tooling |
byteonlabs.com | netbird-proxy-byteonlabs | public internet | nothing internal — no NetBird-Only Access exists on this cluster |
A service cannot span zones: the management server derives the cluster from the domain.
The four rules that hold the model together
Section titled “The four rules that hold the model together”- One route, or the headers mean nothing.
X-NetBird-*is trustworthy only because the proxy is the sole path in: it terminates TLS over WireGuard and strips any client-supplied copy before stamping its own. Publish noports:, add no LAN DNS pin, expose no LAN shortcut. If a peer can reach the container by any second path, it can forge its own identity. - Groups authorize, email identifies.
X-NetBird-Usercan be a peer name (server peers, setup-key peers) and NetBird documents the email as a display value that may change. Never build a role out of the email; readX-NetBird-Groups. - Names are one label. The zone router matches
^[a-z0-9-]+\.<zone>$.foo.bar.<zone>misses the passthrough and needs its own ACME order plus a DNS record — avoid it. - Service state is account state. Reverse-proxy services live in the management DB, not in any repo. Record what you created in the service’s README; nothing is replayed from git.
New service
Section titled “New service”1. Container
Section titled “1. Container”Attach it to the VPN stack’s external network and give it a stable name — the proxy dials
<container>:<port> directly, so the container name is the upstream.
name: mytool
services: mytool: image: ghcr.io/the1studio/mytool:latest container_name: mytool-app restart: unless-stopped networks: - theone-vpn_netbird
networks: theone-vpn_netbird: external: trueNo ports:, no Traefik labels, no ingress sidecar. The proxy reaches it by name inside the network.
2. Read the identity in the app
Section titled “2. Read the identity in the app”Two headers, on every request the proxy forwards. Full contract, parsers, and the local-dev shim: references/netbird-identity.md.
const email = req.headers.get("x-netbird-user"); // may be a PEER NAME, not an emailconst groups = (req.headers.get("x-netbird-groups") ?? "") // absent = peer in no groups .split(",").map((g) => g.trim()).filter(Boolean);if (!email) return new Response("reach this host through the NetBird proxy", { status: 401 });if (!groups.includes("The1Studio:TheOneStudio")) return new Response("forbidden", { status: 403 });Rules that the reference spells out and a rushed implementation gets wrong: validate the email
shape but keep a peer-name fallback as 401 (not 403), preserve group case (groups are
case-sensitive), and answer 401 with a non-Basic challenge so a browser does not pop a
credential dialog over what is really “connect your VPN”.
3. Register the service
Section titled “3. Register the service”Dashboard → Reverse Proxy → Services → Add Service, mode HTTP, subdomain <name>, base
<zone>, target Proxy Cluster (Direct Upstream) → mytool-app:8000, Authentication →
NetBird-Only Access + access group. Narrow the group to the team that should see it; All
admits every peer in the org.
Equivalent API (needs a user PAT — the NB_PROXY_TOKEN_* tokens only authenticate the proxy’s
own gRPC stream):
curl -fsS -X POST https://vpn.the1studio.org/api/reverse-proxies/services \ -H "Authorization: Token $TOKEN" -H 'Content-Type: application/json' \ --data '{ "name": "mytool.the1studio.org", "domain": "mytool.the1studio.org", "mode": "http", "private": true, "enabled": true, "access_groups": ["<group-id>"], "pass_host_header": true, "rewrite_redirects": false, "targets": [{ "target_id": "the1studio.org", "target_type": "cluster", "path": "/", "protocol": "http", "host": "mytool-app", "port": 8000, "enabled": true, "options": { "direct_upstream": true } }] }'access_groups takes group ids (GET /api/groups). Status moves pending → active;
meta.certificate_issued_at staying null is normal for a one-label name — TLS comes from the
zone’s mounted wildcard, not a per-service order.
No DNS work: the service mapping resolves the name on every peer. If an old NetBird DNS A record for this name points at a host IP, delete it or it shadows the mapping.
4. Verify — both directions
Section titled “4. Verify — both directions”# from a mesh peer: identity headers must be presentcurl -sS https://mytool.the1studio.org/ | grep -i x-netbird# X-Netbird-User: you@the1studio.org# X-Netbird-Groups: All,The1Studio:TheOneStudio,...Then from outside the mesh (a public host or an online fetcher) the same URL must be denied —
403/404, never the service. A reachable-from-outside internal service is a bug, not a
convenience. Check that no second route exists either: docker ps shows no published port for
the container, and the name has no LAN DNS pin.
Finally, be the wrong user: ask a peer from outside the access group (or remove yourself
temporarily) and confirm 403, so “the group works” is proven and not assumed.
Edit an existing service
Section titled “Edit an existing service”| Change | How |
|---|---|
| Narrow or widen who gets in | PUT /api/reverse-proxies/services/<id> with the new access_groups |
| Add/rename container target | Update targets[].host / port; the proxy re-resolves on its next config sync |
| Add a group to a person | NetBird group membership, not the service. Group sync from GitHub teams runs daily — a joiner appears after the sync, and a leaver loses access only then |
| Rename the hostname | Create the new service, verify, then delete the old one. There is no rename that keeps the cert path honest |
| Retire | Delete the service. The zone regex is zone-wide, so nothing else holds per-name state |
Before changing access_groups, read the current state and diff it — a service edited by hand in
the dashboard drifts from whatever the README claims:
curl -fsS https://vpn.the1studio.org/api/reverse-proxies/services \ -H "Authorization: Token $TOKEN" \ | jq -r '.[] | [.domain, .private, (.access_groups|join(",")), .pass_host_header, .rewrite_redirects] | @tsv'Hard rules
Section titled “Hard rules”private: falseonthe1studio.orgis the failure that matters. The public listener then answers the name. Setprivate: true+ a group on creation, not “later”.pass_host_header— leavetrueunless the app routes tenants byHostand 404s unknown names; a false value makesHost/ALLOWED_HOSTSchecks see the container name instead of the name a person typed.- A LAN pin advertises a path that is denied. Every passthrough router refuses
192.168.1.0/24; do not “fix” a LAN user’s404with a dnsmasq entry. - Machine callers have no email. CI jobs and server peers authenticate as a peer: they get a
peer name in
X-NetBird-Userand their groups. Put them in a dedicated group rather than special-casing the header. - The proxy strips spoofed headers — but only on requests it forwards. A backend bound to
0.0.0.0with a published port hands the identity story to whoever dials it.
More, with symptoms: ledger/gotchas/t1k-web-devops-selfhost-netbird.md.
References
Section titled “References”- references/netbird-identity.md — header contract, parsers, local-dev shim, threat model
/t1k:vpn— client install/connect/self-heal, host names,netbird status -dThe1Studio/TheOne-VPN—ADD-INTERNAL-TOOL.md(the recipe this skill operationalizes),DEPLOYMENT.md(Create a service, Service settings)