Skip to content

t1k:web:devops:selfhost-netbird

FieldValue
Moduledevops
Version1.31.4
Effortmedium
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

/t1k:web:devops:selfhost-netbird
[new|edit|verify|retire] <name>.<zone>

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.

ZoneClusterReachabilityUse for
the1studio.orgnetbird-proxy-the1studioNetBird peers onlystudio tools, dashboards, internal APIs
playablelabs.ainetbird-proxy-playablelabsNetBird peers onlyplayable-labs internal tooling
byteonlabs.comnetbird-proxy-byteonlabspublic internetnothing 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”
  1. 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 no ports:, 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.
  2. Groups authorize, email identifies. X-NetBird-User can 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; read X-NetBird-Groups.
  3. 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.
  4. 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.

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: true

No ports:, no Traefik labels, no ingress sidecar. The proxy reaches it by name inside the network.

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 email
const 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”.

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):

Terminal window
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.

Terminal window
# from a mesh peer: identity headers must be present
curl -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.

ChangeHow
Narrow or widen who gets inPUT /api/reverse-proxies/services/<id> with the new access_groups
Add/rename container targetUpdate targets[].host / port; the proxy re-resolves on its next config sync
Add a group to a personNetBird 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 hostnameCreate the new service, verify, then delete the old one. There is no rename that keeps the cert path honest
RetireDelete 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:

Terminal window
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'
  • private: false on the1studio.org is the failure that matters. The public listener then answers the name. Set private: true + a group on creation, not “later”.
  • pass_host_header — leave true unless the app routes tenants by Host and 404s unknown names; a false value makes Host/ALLOWED_HOSTS checks 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’s 404 with 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-User and 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.0 with a published port hands the identity story to whoever dials it.

More, with symptoms: ledger/gotchas/t1k-web-devops-selfhost-netbird.md.

  • references/netbird-identity.md — header contract, parsers, local-dev shim, threat model
  • /t1k:vpn — client install/connect/self-heal, host names, netbird status -d
  • The1Studio/TheOne-VPN — ADD-INTERNAL-TOOL.md (the recipe this skill operationalizes), DEPLOYMENT.md (Create a service, Service settings)