https://github.com/vxaboveground/Overlord GitHub - vxaboveground/Overlord: Overlord By KingKDot Archived: 2026-06-10 02:01:57 UTC TELEGRAM SERVER JOIN NOW NO EXCUSES WE GIVE SUPPORT AND IT'S FUN Hello, I made this project for fun. The server is TypeScript on Node/Bun. The client is Go. Operators talk to the server through a web panel or the Electron desktop app, and agents connect over encrypted WebSockets. Docker is the easiest way to run it. Quick Start (Docker) Windows Linux macOS No Docker (.bat / .sh) Production Package Scripts WebRTC Streaming Docker Notes (TLS, reverse proxy, cache) Quick Start (Docker) Pick your OS below. Each section is self-contained: install Docker, get the project, start it. Page 1 of 7 https://github.com/vxaboveground/Overlord Windows and macOS use docker-compose.windows.yml . Linux uses the default docker-compose.yml (host networking). After the first start, open https://localhost:5173 . Default login is admin / admin unless you set OVERLORD_USER / OVERLORD_PASS . First startup writes generated secrets to data/save.json (inside the container: /app/data/save.json ) — keep that file private and back it up. Windows Step-by-step: Windows Linux Step-by-step: Linux (Debian / Ubuntu / Kali) macOS Step-by-step: macOS No Docker (.bat / .sh) If you don't want Docker, use the included scripts. Prerequisites: Bun in PATH Go 1.21+ in PATH Windows Development mode (starts server + client): start-dev.bat Production mode (build + run server executable): start-prod.bat Build client binaries (adds client builds to the build queue): build-clients.bat Linux / macOS Page 2 of 7 https://github.com/vxaboveground/Overlord Make scripts executable once: chmod +x start-dev.sh start-dev-server.sh start-dev-client.sh start-prod.sh build-prod-package.sh Development mode (server in background, client in foreground): ./start-dev.sh Only server, or only client: ./start-dev.sh server ./start-dev.sh client Production mode: ./start-prod.sh Production Package Scripts Build a production-ready package where the server can still build client binaries at runtime. Windows: build-prod-package.bat Output: release/ Linux / macOS: ./build-prod-package.sh Output: release/prod-package/ WebRTC Streaming The remote desktop viewer has a Transport dropdown with three modes: Canvas (default): H.264 / JPEG / block frames over the existing WebSocket, decoded into a . Highest latency, works anywhere the WS does. WebRTC P2P: browser ↔ agent direct. The server only relays SDP and ICE candidates over the existing WS — MediaMTX is not involved. Lowest latency. Fails when both sides are behind aggressive symmetric Page 3 of 7 https://github.com/vxaboveground/Overlord NAT. WebRTC Relayed: agent publishes to a MediaMTX sidecar via WHIP, browser plays via WHEP. The server proxies signaling so the existing JWT auth + per-client RBAC still apply. Lowest-effort fallback when P2P can't punch through. Building agents with WebRTC WebRTC is opt-in per agent build. In the builder UI, tick the WebRTC checkbox before clicking Build. Without it, the Pion stack (~6 MB of Go modules) is not compiled in — any WebRTC start attempt from the operator returns webrtc support not compiled in and the viewer falls back to Canvas. The Canvas path always works regardless of the build setting. The build tag ( overlord_webrtc ) is also available if you build agents outside the UI: go build -tags overlord_webrtc ./cmd/agent MediaMTX sidecar Compose starts an overlord-mediamtx service for Relayed mode. It needs: Port 8189/udp and 8189/tcp reachable from operators (WebRTC ICE traffic). The Windows / macOS compose publishes these; Linux uses host networking and shares the host's interfaces directly. No auth config — the Overlord server proxies every WHIP/WHEP request through /api/webrtc/... and enforces the existing operator JWT + RBAC there. If you only ever want P2P, you can comment out the mediamtx: service in your compose file — only Relayed mode depends on it. LAN / public access By default MediaMTX advertises 127.0.0.1 as an ICE candidate, which is enough for operators running their browser on the same machine as Docker. For viewers on a different machine: Linux (host networking): nothing to configure — MediaMTX sees the host's eth0/wlan0 and gathers those candidates automatically. Windows / macOS (bridge networking): set OVERLORD_WEBRTC_ADDITIONAL_HOSTS to a comma-separated list including the server's reachable LAN or public IP. Either export it in your shell, or add it to a .env file next to the compose file: OVERLORD_WEBRTC_ADDITIONAL_HOSTS=127.0.0.1,192.168.1.42 Then docker compose -f docker-compose.windows.yml up -d mediamtx to apply. Page 4 of 7 https://github.com/vxaboveground/Overlord Advanced MediaMTX customization The compose file passes a minimal set of MTX_* environment variables to MediaMTX — enough for Overlord to work. To change anything else (codecs, paths, ICE servers, etc.), either: Add more MTX_* variables to the mediamtx service's environment: block (every option in MediaMTX's docs is supported as an env var), or Provide a full mediamtx.yml via a bind mount: mediamtx: # ...existing config... volumes: - ./mediamtx.yml:/mediamtx.yml:ro Make sure the file exists on the host before the container starts — Docker will otherwise auto-create an empty directory at that path and fail with "not a directory". Docker Notes (TLS, reverse proxy, cache) Notes on configs and workarounds. BuildKit cache for faster rebuilds docker-compose.yml ships with build.cache_from and build.cache_to pointing at .docker-cache/buildx . Local builds reuse it automatically — no extra setup. Runtime client build cache The compose setup uses a persistent volume for runtime client builds: Volume: overlord-client-build-cache Mount: /app/client-build-cache Env: OVERLORD_CLIENT_BUILD_CACHE_DIR (default /app/client-build-cache ) Certbot TLS To use Let's Encrypt certificates in production Docker: 1. Set OVERLORD_TLS_CERTBOT_ENABLED=true 2. Set OVERLORD_TLS_CERTBOT_DOMAIN=your-domain.com 3. Mount letsencrypt into the container read-only, e.g. /etc/letsencrypt:/etc/letsencrypt:ro Default cert paths: Page 5 of 7 https://github.com/vxaboveground/Overlord cert: /etc/letsencrypt/live//fullchain.pem key: /etc/letsencrypt/live//privkey.pem ca: /etc/letsencrypt/live//chain.pem Override with: OVERLORD_TLS_CERTBOT_LIVE_PATH OVERLORD_TLS_CERTBOT_CERT_FILE OVERLORD_TLS_CERTBOT_KEY_FILE OVERLORD_TLS_CERTBOT_CA_FILE Reverse proxy TLS offload If your platform terminates TLS before traffic reaches Overlord (Render, Caddy, nginx, etc.), set: OVERLORD_TLS_OFFLOAD=true OVERLORD_HEALTHCHECK_URL=http://localhost:5173/health OVERLORD_PUBLISH_HOST=127.0.0.1 When enabled: Container serves internal HTTP on 0.0.0.0:$PORT External URL stays https://... through your platform proxy Health checks should use http://localhost:$PORT/health inside the container Don't expose the internal container HTTP port directly to the internet Source IP behind a domain / reverse proxy If the dashboard, audit log, or IP bans show all agents as 172.x.x.x (or some other proxy/bridge IP), something between the agent and Bun is rewriting the source IP. Two independent flags govern this: OVERLORD_TLS_OFFLOAD — TLS terminates at the proxy; Overlord runs plain HTTP internally. OVERLORD_TRUST_PROXY — honor X-Forwarded-For / X-Real-IP / CF-Connecting-IP so dashboard/audit/IP-bans see the real client. Auto-enabled when TLS_OFFLOAD=true . Common shapes: Setup Domain, no proxy (Linux host networking; certbot inside Overlord; TLS_OFFLOAD TRUST_PROXY false false Cloudflare DNS-only) Domain, proxy does TLS (Render, nginx terminating TLS → http upstream) true auto ( true ) Page 6 of 7 https://github.com/vxaboveground/Overlord Setup Domain, proxy in front but Overlord still does TLS (Cloudflare orange- cloud Full Strict; nginx with proxy_pass https:// ) TLS_OFFLOAD TRUST_PROXY false true Only enable OVERLORD_TRUST_PROXY when a trusted reverse proxy is in front. If Overlord is directly exposed and you enable it, agents can spoof their source IP by sending their own X-Forwarded-For header, breaking IP bans and audit accuracy. The upstream proxy also has to be configured to inject the header (Cloudflare does by default; nginx/Caddy/Traefik need explicit directives). If you're using docker-compose.windows.yml or docker-compose.quickstart.yml (Docker Desktop bridge networking) with no reverse proxy, Docker itself rewrites source IPs to the bridge gateway and there is no header to recover from — TRUST_PROXY cannot help. Either switch to Linux host networking or put a real reverse proxy in front. Notes Keep HOST=0.0.0.0 inside the container. Limit exposure with OVERLORD_PUBLISH_HOST , not the bind host. If your .env secret/password contains $ , escape it as $$ to avoid Docker Compose variable-expansion warnings. Source: https://github.com/vxaboveground/Overlord Page 7 of 7