NetBird and Zero-Trust Access to Your Homelab AI Stack

Option A: NetBird as TrueNAS App (Recommended)

Easiest method with automatic updates:

# In TrueNAS UI:
# 1. Go to Apps → Available Apps
# 2. Search for "NetBird"
# 3. Select the NetBird app and click Install
# 4. Configure:
#    - Network: Your NetBird network name/ID
#    - Setup Key: The setup key from step 1
#    - Port: 51821 (default WireGuard port, can change if needed)
#    - Allow LAN: Enable if you want local LAN devices to join
#    - Disable Internet Kill Switch: Usually disable for homelab
#    - Debug: Leave unchecked unless troubleshooting

# 5. Click Save and wait for installation
#    - TrueNAS will pull the container and start the service
#    - Check Apps → Installed Apps → NetBird → Logs for status

Option B: Manual Docker Installation

More control, slightly more complex:

# 1. Create storage for NetBird config
mkdir -p /mnt/nvme-pool/apps/netbird
mkdir -p /mnt/nvme-pool/apps/netbird/data

# 2. Run the NetBird container
docker run -d \
  --name netbird \
  --restart unless-stopped \
  --net=host \  # Required for proper WireGuard operation
  --cap-add=NET_ADMIN \
  --cap-add=SYS_MODULE \
  -v /mnt/nvme-pool/apps/netbird:/etc/netbird \
  -v /mnt/nvme-pool/apps/netbird/data:/var/lib/netbird \
  -v /lib/modules:/lib/modules:ro \
  netbirdio/netbird:latest \
  --setup-key= \
  --management-url=https://management.netbird.io \
  --log-level=info

# 3. Alternative: Using docker-compose
# Create docker-compose.yml:
version: '3.8'
services:
  netbird:
    image: netbirdio/netbird:latest
    container_name: netbird
    restart: unless-stopped
    network_mode: host
    cap_add:
      - NET_ADMIN
      - SYS_MODULE
    volumes:
      - ./netbird:/etc/netbird
      - ./netbird/data:/var/lib/netbird
      - /lib/modules:/lib/modules:ro
    command: >
      --setup-key=${NETBIRD_SETUP_KEY}
      --management-url=https://management.netbird.io
      --log-level=info

Supported Platforms

• Windows: 10/11 (64-bit)
• macOS: 10.15+ (Intel and Apple Silicon)
• Linux: Ubuntu, Debian, Fedora, Arch, etc.
• iOS: 12+
• Android: 8.0+

Installation Examples

# Windows (PowerShell, run as Administrator):
# 1. Download installer from https://www.netbird.io/install/windows
# 2. Run the .exe file
# 3. Enter your setup key when prompted
# 4. Complete the setup wizard

# macOS (Terminal):
# 1. Install via Homebrew:
#    brew install netbird/tap/netbird
# 2. Run setup:
#    netbird up --setup-key=

# Linux (Ubuntu/Debian example):
# 1. Add repository:
#    curl -fsSL https://pkgs.netbird.io/pub.gpg | sudo apt-key add -
#    echo "deb https://pkgs.netbird.io/debian stable main" | sudo tee /etc/apt/sources.list.d/netbird.list
# 2. Install:
#    sudo apt update
#    sudo apt install netbird
# 3. Setup:
#    sudo netbird up --setup-key=

# Docker (for containers/services):
# docker run -d \
#   --name netbird-client \
#   --restart unless-stopped \
#   --net=host \
#   --cap-add=NET_ADMIN \
#   --cap-add=SYS_MODULE \
#   -v /lib/modules:/lib/modules:ro \
#   netbirdio/netbird:latest \
#   --setup-key=

Example: Developer Access Policy

Who: Members of "ai-developers" group

What: Full access to development AI services

When: 6:00 AM - 10:00 PM local time

Where: Anywhere (no geographic restrictions)

Device requirements:

• OS: Windows 10/11, macOS 12+, or Linux kernel 5.10+
• Antivirus: Must be installed and running
• Disk encryption: Required (BitLocker, FileVault, or LUKS)
• Firewall: Local firewall must be enabled
• Screen lock: Must activate after ≤5 minutes idle

Network access:

• ✓ Ollama (TCP 11434)
• ✓ ComfyUI (TCP 8188)
• ✓ LiteLLM (TCP 4000)
• ✓ Qdrant (TCP 6333)
• ✓ LangFuse (TCP 3100)
• ✓ Postgres (TCP 5432)
• ✓ Redis (TCP 6379)
• ✓ Internal development ports (3000-3010)
• ✗ Administration ports (ssh 22, webmin 10000, etc.)
• ✗ External internet (unless explicitly allowed)

Example: Researcher Access Policy

Who: Members of "ai-researchers" group

What: Access to AI services for experimentation

When: 8:00 AM - 8:00 PM local time

Where: Anywhere

Device requirements:

• OS: Any supported platform
• Antivirus: Recommended but not required
• Disk encryption: Strongly recommended
• Firewall: Recommended
• Screen lock: Recommended

Network access:

• ✓ Ollama (TCP 11434) - Limited to specific models
• ✓ ComfyUI (TCP 8188) - Limited to SD 1.5, no batch >1
• ✓ LiteLLM (TCP 4000) - Limited to local models only
• ✓ Qdrant (TCP 6333) - Read-only access
• ✓ Datasets (TCP 8080) - Read-only access to /mnt/Storage_Pool/datasets/
• ✗ Production models (protected /mnt/Storage_Pool/models/production/)
• ✗ Generation output directories
• ✗ Administration and management interfaces

Example: Family Access Policy

Who: Members of "family" group

What: Limited access to non-sensitive services

When: 7:00 AM - 10:00 PM local time

Where: Anywhere

Device requirements:

• OS: Any supported platform
• Antivirus: Strongly recommended
• Disk encryption: Strongly recommended
• Firewall: Recommended
• Screen lock: Recommended

Network access:

• ✓ ComfyUI (TCP 8188) - Only for image viewing/generation
• ✓ Simple web interfaces (TCP 3000-3005) - Non-admin dashboards
• ✓ Media streaming (if applicable) - Plex, Jellyfin, etc.
• ✗ Ollama/LiteLLM - No LLM access
• ✗ Qdrant - No vector database access
• ✗ Postgres/Redis - No database access
• ✗ File shares - No access to SMB/NFS shares
• ✗ Administration interfaces

Split Tunneling Options

• Full tunnel (default): All traffic goes through NetBird
• Split tunnel: Only NetBird-managed services use the mesh
• LAN access: Allow communication with local network devices

Configuration Examples

# For TrueNAS running AI services:
# Usually want:
# - Split tunnel: OFF (so services are accessible via NetBird IP)
# - LAN access: ON (so local dev tools can still reach services)
# - Internet kill switch: OFF (unless you want strict isolation)

# For daily driver laptop:
# Usually want:
# - Split tunnel: ON (so regular web browsing doesn't go through homelab)
# - LAN access: ON (so can still access printers, NAS shares, etc.)
# - Internet kill switch: OFF

# For high-security workstation:
# Usually want:
# - Split tunnel: OFF (maximum protection)
# - LAN access: LIMITED (only specific services)
# - Internet kill switch: ON (blocks all non-NetBird traffic if connection drops)

NetBird vs Traditional VPNs (OpenVPN, WireGuard)

NetBird vs Tailscale/Headscale

Security Best Practices

• Principle of least privilege: Start with no access, Grant only what's absolutely needed
• Regular access reviews: Quarterly audits of who has access to what
• Use groups effectively: Manage permissions at group level, not individual
• Leverage device posture: Require encryption, AV, updates for sensitive services
• Time-based restrictions: Limit sensitive access to appropriate hours
• Monitor access logs: Use NetBird's audit logs to detect anomalies
• Keep software updated: Regularly update NetBird clients and server
• Backup your setup key: Store securely - loss requires re-onboarding all peers
• Consider geographic restrictions: If applicable, limit access to expected regions

Performance Optimizations

• Enable direct connections: Ensure firewall/NAT allows peer-to-peer WireGuard
• Choose optimal relay region: Select NetBird region closest to your users
• MTU tuning: Adjust if experiencing fragmentation issues (try 1420)
• Monitor peer health: Watch for peers that consistently use relays
• Consider split tunneling: Don't send all traffic through NetBird if unnecessary
• Bandwidth awareness: Remember upload rates may limit download speeds
• Test regularly: Periodically check latency and throughput

Management and Maintenance

• Document your setup: Record network name, setup key location, policies
• Automate onboarding: Create scripts for adding new devices
• Use tags for organization: Tag devices by type (laptop, phone, server, iot)
• Leverage service accounts: For n8n, backup systems, monitoring bots
• Plan for growth: The free tier supports 100 peers - plenty for most homelabs
• Consider hierarchy: Separate networks for production, development, guest access
• Review logs: Check NetBird dashboard for connection issues or policy denials
• Stay updated: Follow NetBird blog for new features and security advisories