Deploy and Host railbird on Railway

railbird is a TCP port forwarder that bridges Railway services and a NetBird mesh. It runs an embedded NetBird client and forwards traffic in either direction — Railway → mesh peers (egress) or mesh peers → Railway services (ingress) — so services on Railway can reach other peers on a NetBird mesh without per-app SOCKS5 setup.

About Hosting railbird

Hosting railbird is a matter of running a single Go binary as its own Railway service, accessible only over Railway's Private Network. The container joins your NetBird mesh at startup using a setup key and your management URL, then opens one local listener per entry in the FORWARDS list. State (the device's WireGuard private key) lives on a small persistent volume so the same peer identity survives redeploys instead of re-registering against your setup-key quota every restart. No public ports are exposed; sibling Railway services connect via railbird's RAILWAY_PRIVATE_DOMAIN on the listen ports you configured.

Common Use Cases

Connect a Railway app to a Postgres / Redis / Elasticsearch instance reachable only from your NetBird mesh
Expose a Railway-hosted internal service to peers elsewhere on the mesh (admin tools, dashboards, on-prem clients)
Bridge a Railway environment with a self-hosted Headscale-style NetBird control plane and resources living in another cloud or on-prem

Dependencies for railbird Hosting

A NetBird account and management URL — NetBird Cloud (https://api.netbird.io) or a self-hosted instance
A NetBird setup key authorized for the groups/ACLs you want railbird's peer to belong to
A small Railway volume (~1 GB minimum is more than enough) for persistent device state

Deployment Dependencies

Implementation Details

FORWARDS accepts a comma-separated list. Each entry is host:port (listen on :port) or lport=host:port (listen on :lport):

FORWARDS=5432=db.railway.internal:5432, 6379=cache.railway.internal:6379

Once deployed, sibling services connect to railbird over the private network:

DATABASE_URL=postgresql://user:pass@${{railbird.RAILWAY_PRIVATE_DOMAIN}}:5432/dbname

Mount the volume at /var/lib/netbird/data and set NB_STATE_DIR=/var/lib/netbird/data so the embedded NetBird client's config.json and state.json (the device's identity and runtime state) persist across restarts.

> ⚠️ Do not expose railbird publicly on Railway — anyone reaching the public listener would be reaching your mesh.

Why Deploy railbird on Railway?

Railway is a singular platform to deploy your infrastructure stack. Railway will host your infrastructure so you don't have to deal with configuration, while allowing you to vertically and horizontally scale it.

By deploying railbird on Railway, you are one step closer to supporting a complete full-stack application with minimal burden. Host your servers, databases, AI agents, and more on Railway.