---
title: "Deploy railbird"
description: "Connect to Railway services via Netbird."
category: "Other"
url: https://railway.com/deploy/railbird
---

# Deploy railbird

Connect to Railway services via Netbird.

**[Deploy railbird on Railway](https://railway.com/template/railbird)**

- **Creator:** Jonas Atienza's Projects
- **Category:** Other
- **Total deploys:** 2

## Template content

### railbird https://cdn.jsdelivr.net/gh/homarr-labs/dashboard-icons/svg/netbird.svg

- **Source:** jratienza65/railbird

## Documentation

# Deploy and Host railbird on Railway

railbird is a TCP port forwarder that bridges Railway services and a [NetBird](https://netbird.io/) 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://app.netbird.io/) (`https://api.netbird.io`) or a self-hosted instance
- A NetBird [setup key](https://docs.netbird.io/how-to/register-machines-using-setup-keys) 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

- [NetBird documentation](https://docs.netbird.io/)
- [NetBird setup keys](https://docs.netbird.io/how-to/register-machines-using-setup-keys)
- [railbird source on GitHub](https://github.com/) 
- [Railway Private Networking](https://docs.railway.com/guides/private-networking)

### 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.

## Similar templates

- [Rocky Linux](https://railway.com/deploy/rocky-linux) — Hosted Rocky Linux 9 workspace with SSH and persistent storage. 🚀
- [Foundry Virtual Tabletop](https://railway.com/deploy/X5tR6G) — A Self-Hosted & Modern Roleplaying Platform
- [Letta Code Remote](https://railway.com/deploy/letta-code-remote) — Run a Letta Code agent 24/7. No inbound ports, just deploy.

Open this page in a browser: https://railway.com/deploy/railbird