https://github.com/vhscom/birdcage
Secure remote access for personal AI
https://github.com/vhscom/birdcage
acme go remote-access reverse-proxy security self-hosted single-user wireguard
Last synced: about 1 month ago
JSON representation
Secure remote access for personal AI
- Host: GitHub
- URL: https://github.com/vhscom/birdcage
- Owner: vhscom
- License: agpl-3.0
- Created: 2026-03-17T09:40:19.000Z (4 months ago)
- Default Branch: main
- Last Pushed: 2026-04-02T06:45:26.000Z (3 months ago)
- Last Synced: 2026-04-02T20:20:43.903Z (3 months ago)
- Topics: acme, go, remote-access, reverse-proxy, security, self-hosted, single-user, wireguard
- Language: Go
- Homepage:
- Size: 1.22 MB
- Stars: 3
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: COPYING
Awesome Lists containing this project
README
# birdcage
Secure remote access layer for personal AI. One user, one claw, accessible from any browser, privately.
[](https://github.com/vhscom/birdcage/actions/workflows/ci.yml)
[](https://github.com/openclaw/openclaw)
[](https://go.dev/)
[](COPYING)
```
Browser ──────► Birdcage (VPS) ────► OpenClaw (home)
cookie auth + proxy mesh WireGuard agent
```
A claw is a local AI assistant like [OpenClaw](https://github.com/openclaw/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](docs/demo.mp4) for a walkthrough.
## Quick start
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`):
```sh
git clone https://github.com/vhscom/birdcage.git && cd birdcage
go build -o birdcage .
sudo mv birdcage /usr/local/bin/
```
**On the VPS:**
```sh
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:**
```sh
# macOS
brew install wireguard-tools wireguard-go
# Linux
apt install -y wireguard-tools
# then
birdcage agent init https://your-domain.example.com
sudo birdcage agent install
```
**Connect the gateway:** Configure your claw's gateway token, then edit `/opt/birdcage/.env` on the VPS:
```sh
GATEWAY_URL=http://10.0.0.2:18789 # claw's mesh address
GATEWAY_TOKEN= # 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.
## What it does
**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](docs/ops.md).
## CLI
```
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 Save agent config
birdcage agent install Install as system service
birdcage agent uninstall Remove system service
birdcage ctl Open the management TUI
```
## Building
Requires Go 1.26+.
```sh
go build -o birdcage .
```
Single binary, pure Go, no CGO.
## TLS
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).
## Safe deployment
- **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.
## Design principles
- **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.
## Documentation
- [Ops API and TUI](docs/ops.md) — REST endpoints, WebSocket ops, management TUI
- [Auth flows](docs/flows.md) — sequence diagrams for every authentication path
- [Threat model](docs/threat-model.md) — STRIDE analysis and JWT pitfall catalogue
## License
AGPL-3.0 — see [COPYING](COPYING).