Secure remote access layer for personal AI. One user, one claw, accessible from any browser, privately.

Browser ──────► Birdcage (VPS) ────► OpenClaw (home)
        cookie  auth + proxy   mesh  WireGuard agent

A claw is a local AI assistant like OpenClaw running on your home machine. Birdcage lets you reach it from anywhere after authenticating. Traffic is encrypted over WireGuard — your claw never touches the public internet.

See the demo video for a walkthrough.

Point a DNS A record to your VPS (DNS-only, not proxied). Open ports 443, 80, and 51820/udp.

Build (on the VPS, or cross-compile with GOOS=linux GOARCH=amd64):

git clone https://github.com/vhscom/birdcage.git && cd birdcage
go build -o birdcage .
sudo mv birdcage /usr/local/bin/

On the VPS:

apt install -y wireguard-tools
mkdir -p /opt/birdcage && cd /opt/birdcage
birdcage init                    # prompts for BASE_URL and WG endpoint
sudo birdcage serve install      # installs and starts as a system service

On the home machine:

# macOS
brew install wireguard-tools wireguard-go

# Linux
apt install -y wireguard-tools

# then
birdcage agent init https://your-domain.example.com <agent-key>
sudo birdcage agent install

Connect the gateway: Configure your claw's gateway token, then edit /opt/birdcage/.env on the VPS:

GATEWAY_URL=http://10.0.0.2:18789     # claw's mesh address
GATEWAY_TOKEN=<token from your claw>  # gateway auth token

Restart: sudo systemctl restart birdcage.

Open https://your-domain.example.com in a browser and register with the token printed during init.

Auth layer — Token-gated registration (single owner), login with PBKDF2-SHA384 (210K iterations), adaptive proof-of-work on brute force, JWT dual-token pattern with refresh token rotation and reuse detection, session management with sliding expiry, OWASP security headers.

Control proxy — HTTP reverse proxy and WebSocket bridge to the claw's web UI. Strips credentials before forwarding, injects gateway token and operator scopes into WebSocket connect frames.

WireGuard mesh — Server provisions its own WireGuard interface and coordinates peers. Agent runs at home alongside the claw, manages WireGuard, discovers endpoints via STUN, falls back to relay when direct UDP fails, rotates keys on a configurable interval.

Ops API + TUI — REST endpoints and an interactive terminal dashboard (birdcage ctl) for managing sessions, events, agent credentials, and mesh nodes. Includes cloak mode: when active, all ops and WebSocket endpoints return plain 404 to public IPs while WireGuard mesh addresses pass through unconditionally. Cloak auto-engages on attack (auth failures, TLS probes, rate-limit hits) and is on by default. See ops documentation.

birdcage init                          Generate server config (.env)
birdcage serve                         Start the server
birdcage serve install                 Install as system service
birdcage serve uninstall               Remove system service
birdcage agent                         Run the WireGuard mesh agent
birdcage agent init <server> <key>     Save agent config
birdcage agent install                 Install as system service
birdcage agent uninstall               Remove system service
birdcage ctl                           Open the management TUI

Requires Go 1.26+.

go build -o birdcage .

Single binary, pure Go, no CGO.

When BASE_URL starts with https://, Birdcage automatically obtains a TLS certificate from Let's Encrypt. No reverse proxy needed.

• Listens on :443 (HTTPS) and :80 (ACME HTTP-01 challenges + redirect)
• Renews the certificate ~30 days before expiry
• Stores certificates in ./certs (override with CERT_DIR)
• Falls back to TLS-ALPN-01 if port 80 is unavailable

Requirements: DNS A/AAAA record pointing to the server, ports 443 and 80 available.

For local development, use BASE_URL=http://localhost:8080 (the default).

• Keep generated secrets. birdcage init generates 256-bit secrets and a registration token. Don't replace them with weaker values. The server refuses to start if JWT secrets are under 32 characters.

• Single user, single purpose. No multi-tenancy, no admin roles, no user management beyond the owner.
• Privacy by architecture. Oauth-free. Traffic between the VPS and your home machine is encrypted via WireGuard.
• One binary. Server, agent, CLI — same executable, different subcommands.
• No magic. birdcage init shows you what it creates. birdcage serve does what it says. One .env, one database.
• Secure by default. HTTPS is automatic. Cookies are SameSite=Strict. Headers are OWASP. PoW activates under brute force. Cloak mode auto-engages on attack and hides the ops surface from public IPs.

• Ops API and TUI — REST endpoints, WebSocket ops, management TUI
• Auth flows — sequence diagrams for every authentication path
• Threat model — STRIDE analysis and JWT pitfall catalogue

AGPL-3.0 — see COPYING.