GoProxify

GoProxify is a distributed reverse proxy compiled as a single Go binary — built to manage multiple servers from a central interface, without heavy agents or configuration scattered across every machine.

You have several VPS, Docker containers on different hosts, and you want to route traffic, manage TLS certificates and keep control of everything from one place? That's exactly what GoProxify is for.

What makes it different

• One binary, three roles — the same executable starts as Edge (proxy), Admin (management UI) or Agent (service discovery)
• The Edge is autonomous — it starts and routes traffic even when the Admin is unreachable; routes and certificates are held locally, in RAM
• HTTP/1.1, HTTP/2, HTTP/3 QUIC, TCP/UDP L4 — one tool covers all protocols
• Built-in OWASP CRS-4 WAF — 13 rule sets (SQLi, XSS, Log4Shell…) with no external plugin
• SSH and Docker access from the UI — web terminal, UUID ssh to VMs and docker exec to containers, directly from your browser
• Automatic service discovery — the Agent reads goproxify.* labels on Docker/Podman containers and Kubernetes services, or tags from Consul, Nomad, etcd and Amazon ECS, and pushes routes in real time; a discovered container can be converted into a regular, editable proxy with one click
• WASM plugins — sandboxed plugins on requests, bodies and TCP/UDP streams; Coraza (SecLang) and ready-made examples installable in one click
• Alerting to 10 channels — Email, Webhook, ntfy.sh, Jira, Linear, GitHub Issues, and more

---

Preview (0.x). Use at your own risk. Details: DISCLAIMER.md · license Apache-2.0.

Contributing: CONTRIBUTING.md · Support: Discussions · Roadmap: suivi/roadmap-public.md.

---

Architecture

                        ┌──────────────────────────────────┐
                        │  ADMIN  (Control Plane)          │
                        │  Web UI · REST API · MCP · :9443 │
                        │  SQLite · ACME · Alerting        │
                        │  Proxies: Edge YAML files        │
                        │  rebuildable from Edges          │
                        └──────────┬───────────────────────┘
                                   │ persistent WS Admin→Edge
                                   │ (push routes/certs/config)
                                   ▼
┌──────────────┐    ┌──────────────────────────────────────┐
│   INTERNET   │───►│  EDGE  (Data Plane · central WS hub) │
│  :80 / :443  │    │  HTTP/1·2·3 QUIC · TCP/UDP L4        │
│  HTTP/1·2·3  │    │  TLS in RAM · AES-256 local cache    │
└──────────────┘    │  Zero reload · autonomous w/o Admin  │
                    │  :80 :443 :443/UDP :8000+WS (internal)│
                    └────────────▲─────────────────────────┘
                                 │ persistent WS Agent→Edge
                                 │ (heartbeat/metrics/events)
                    ┌────────────┴─────────────────────────┐
                    │  AGENT  (Docker Discovery)           │
                    │  Reads docker.sock (read-only)       │
                    │  Detects goproxify.* labels          │
                    │  Prometheus :9191/metrics            │
                    │  No inbound control-plane port       │
                    └──────────────────────────────────────┘

Component	Role	Persistence	Exposed ports
Edge	Data Plane — routing, TLS, L4 · WS control-plane hub	RAM + encrypted local cache · YAML proxies (proxies/*.yaml)	:80, :443 (TCP+UDP), :8000 (internal + WS)
Admin	Control Plane — UI, API, alerting	SQLite (config, users, tokens)	:9443
Agent	Docker discovery & metrics	Volatile	:9191 (Prometheus) — no inbound WS port

Example layouts

Many layouts are possible; two reference examples (also shown on the landing page). Read them top to bottom: Internet → gateways (Edges) → Agents (HTTP(S) proxies via labels) or hosts (TCP/UDP proxies). The Admin is the management link to the Edges.

Home lab — 1 Admin · 1 Edge · 1 Agent

              INTERNET
                 │ HTTPS · TCP · UDP
                 ▼
  ADMIN ◄──► GATEWAY (Edge)
                 │
        ┌────────┴─────────┐
        ▼                  ▼
  Docker host          Other host (NAS, VM…)
  AGENT + containers   TCP/UDP direct, no Agent
  (HTTP(S) via labels)

Enterprise, redundant — 1 Admin · 2 Edges · 4 hosts with Agents

                    INTERNET
                       │ HTTPS · TCP · UDP
        DNS round-robin or virtual IP
           ┌───────────┴───────────┐
           ▼                       ▼
   GATEWAY 1 (Edge) ◄─ ADMIN ─► GATEWAY 2 (Edge)
           └───────────┬───────────┘
                Internal network
     ┌──────────┬──────┴───┬──────────┐
     ▼          ▼          ▼          ▼
   HOST 1     HOST 2     HOST 3     HOST 4
   AGENT      AGENT      AGENT      AGENT

Step-by-step install for both: docs/deployment.md.

---

Quick start

Preview only — read DISCLAIMER.md before any deployment.

Docker Compose (recommended)

# 1. Run the quickstart script — it generates docker-compose.yml and .env
curl -fsSL https://github.com/vincamok/goproxify/raw/main/scripts/quickstart.sh -o quickstart.sh
bash quickstart.sh

The script generates hex-32 secrets, writes .env (chmod 600), checks Docker / ports, then starts Admin + Edge + Agent. Variants (run alone): bash quickstart.sh --print-secrets · bash quickstart.sh --env-only.

Images are published on GHCR (ghcr.io/vincamok/goproxify). Default quickstart: floating tag preview. To pin a SemVer: GOPROXIFY_ADMIN_TAG, GOPROXIFY_EDGE_TAG, GOPROXIFY_AGENT_TAG (see versions.json / .env.example).

The admin interface is available at http://localhost:9443.

The Edge and Agent pair automatically with the Admin via GPX_PAIRING_SECRET — no manual token copy needed.

Portainer

1. Stacks → Add stack → Web editor
2. Paste the compose from docs/deployment.md (or run bash scripts/quickstart.sh --env-only locally and copy the generated docker-compose.yml)
3. Environment variables: GPX_JWT_SECRET, GPX_PAIRING_SECRET, GPX_FIRST_ADMIN_EMAIL, GPX_FIRST_ADMIN_PASSWORD (generate secrets with openssl rand -hex 32)
4. Deploy the stack

Binary

# Build
git clone https://github.com/vincamok/goproxify && cd goproxify
go build -o goproxify ./cmd/goproxify

# Start Admin
GPX_SECURITY_JWT_SECRET=<secret> ./goproxify admin

# Start an Edge (token generated from Admin UI)
GPX_CONTROL_PLANE_ADMIN_ENDPOINT=http://localhost:9443 \
GPX_EDGE_TOKEN=gpx_... \
./goproxify edge

# Start Agent (optional)
GPX_CONTROL_PLANE_EDGE_ENDPOINT=http://localhost:8000 \
./goproxify agent

---

Pairing Edge / Agent

Edge → Admin

Two methods to connect an Edge to an Admin:

Method	Use case	Variable
Shared secret	All-in-one stack (same machine / same compose)	GPX_PAIRING_SECRET
Explicit token	Remote Edge, multi-site	GPX_EDGE_TOKEN

The shared secret is the recommended method for standard deployments. The explicit token is generated from Admin UI → Settings → Tokens.

Agent → Edge (WS)

The Agent↔Edge control plane uses a persistent WebSocket tunnel. The Agent connects to the Edge — not the other way around.

Step	Description	Variable
1. JOIN_TOKEN	First start — Agent connects and enters pending state	GPX_CONTROL_PLANE_JOIN_TOKEN
2. Approval	Operator approves the Agent in Admin UI	—
3. agent_hmac	Edge sends an HMAC secret via WS → Agent is approved	auto-negotiated
4. Rotation	Edge regenerates agent_hmac every hour	automatic

To generate a JOIN_TOKEN: Admin UI → Tokens → Create → role agent, TTL 24h.

---

CLI

goproxify <command> [options]

Service commands:
  admin    Start Administration (Control Plane + Web UI)
  edge     Start Edge (Data Plane — Reverse Proxy)
  agent    Start Agent (service discovery)
  landing  Start landing page (optional)

Operational commands (talk to Admin via HTTP):
  token      Edge/Agent pairing tokens
  backup     Backup and restore
  import     Import from nginx / Traefik / Caddy / HAProxy
  alert      Test alert channels
  status     Cluster status
  access     GoProxify Access (config, catalogue, users, templates, audit)
  nodes      Infrastructure nodes (list / accept / reject)
  declared   Architecture wizard declared nodes
  bootstrap  QR tickets / curl|bash host integration
  update     Update Docker images (via Agent)

  version  Binary version
  help     Help

Common auth for operational commands: -admin-url / -token or env vars GPX_CONTROLPLANE_ADMIN_ENDPOINT / GPX_CONTROLPLANE_AUTH_TOKEN.

Full reference → docs/cli.md

---

Features

Edge (Data Plane)

• HTTP/1.1, HTTP/2, HTTP/3 QUIC routing (UDP)
• TCP and UDP (L4) streaming
• TLS termination + SSL Passthrough via passive SNI detection
• Routes and certificates stored in RAM (sync.Map, GetCertificate) — no private key on disk
• AES-256-GCM encrypted local cache — starts and routes without Admin available
• Hot configuration reload, zero connection interruption
• Load balancing (Round Robin, Weighted, adaptive CPU/mem/IO + failover + inter-Edge gateway), Circuit Breaker, Retry, per-route slow-start
• Rate limiting, per-route backpressure (bounded queue, 503 + Retry-After), IP/CIDR filtering, Geo-IP, OWASP CRS-4 WAF (13 rule sets: SQLi, XSS, LFI, RCE, PHP, SSRF, Scanner, Java/Log4Shell, RFI, NodeJS, HTTP Smuggling, Sensitive Files, Response Leaks), HTTP security headers
• Automation flows — rules, schedules and playbooks built in one flow editor: a trigger (conditions on CVEs, bans, error rate, offline nodes, expiring certificates or any sampled metric; alert events; cron; manual runs with parameters) → steps (disable proxy, ban IP, notify, strict Fail2Ban mode, webhooks, PagerDuty, backup, wait, if/else, human approval, call a playbook); simulation, versions, parameterised templates, and simple flows run by the gateways even when the Admin is down
• Basic, Forward Auth, JWT authentication per route
• Live topology map (health, req/s, risk score per node), async JSON access log, Prometheus metrics, OpenTelemetry tracing (W3C traceparent propagated caller → Edge → backend, sampling)
• GoProxify Access — operator portal on the Edge: web terminal + UUID ssh to VMs/sshd and Docker containers (docker exec via Agent); SSH login vault + secrets; 2FA; TTL sessions

Admin (Control Plane)

• Web UI + REST API — CRUD proxies, snippets, tokens, users; three skins (Flat, Industry DS, Console), light or dark, each with its own accent colours
• GoProxify Access — destination catalogue (global / per-Edge view), invite users by email (SMTP), tags, Access HTML templates, portal options per Edge
• User API tokens (PAT) — gpx_pat_* self-service with scopes (proxies:read, certs:write, …) for scripts and MCP clients; a read scope never allows a write; distinct from Edge/Agent pairing tokens
• MCP server — JSON-RPC 2.0 + SSE; PAT-only authentication (no session JWT); every tool and resource requires the scope of its REST equivalent, plus the admin role where the REST route is admin-only — a tool without a declared scope is refused
• Terraform provider — integrations/terraform-provider-goproxify: proxies, bans (optionally scoped to a gateway or HA group), ban whitelist and IP profiles as code, with import and drift detection (not yet published on the Terraform Registry)
• Infrastructure view & architecture editor — live flow schema (Internet → Edges → Agents) with a node detail panel and a "to handle" bar; in-place editing (drag-and-drop palette, host cards, changes flagged with their impact, review before save), multi-Edge/HA, QR tickets / curl|bash to integrate a host
• Bans page — the same page in the Admin (all Edges) and in each Edge menu: KPIs, 48 h timeline, origin by country, filters, bulk actions and a mobile card layout; every ban records the Edge that reported it
• Ephor and the WAF learn — one risk note per IP, shared by both engines: every request feeds a behavioural store (rate, error spread, missing assets, regular cadence, User-Agent vs TLS fingerprint, whole-ASN failures), compared with the normal rate learned per route and hour; every new signal starts in detect (explained in the ban it would have caused, counted as a shadow note) and moves to block after a log replay; a long clean history raises the ban threshold; works without the Admin — see docs/security.md
• HA groups — Ephor, the WAF switch, HTTP timeouts and the access portal are configured once per HA group; the portal store (accounts, 2FA, vaults, optional shared web sessions) and Ephor reference lists are replicated between Edges, and bans keep flowing between peers when the Admin is down

Agent (Service Discovery)

• Reads /var/run/docker.sock read-only
• Detects goproxify.* labels on containers in real time
• Also discovers Portainer, Kubernetes Ingress/Service annotations, and Consul, Nomad, etcd and Amazon ECS instances (polled; an unreachable directory never removes a route)
• Sends routes, metrics and events to the Edge via persistent WS tunnel (Agent→Edge)
• HTTP heartbeat fallback if WS connection is unavailable
• Canary (goproxify.canary) and Shadow Mirror (goproxify.shadow) labels supported
• Prometheus export on :9191/metrics
• No inbound port required for the control plane

---

Ports

Port	Protocol	Component	Exposure
80	TCP	Edge	Public
443	TCP	Edge	Public
443	UDP	Edge	Public (HTTP/3 QUIC)
8000	TCP	Edge	Internal only
2222	TCP	Edge (Access)	UUID SSH portal (if Access enabled; configurable)
8444	TCP	Edge (Access)	Internal Access UI (if Access enabled; configurable)
9443	TCP	Admin	Operator
9191	TCP	Agent	Internal (Prometheus)

Port 8000 (Edge internal API) must not be exposed publicly.
Restrict access: ufw allow from <admin-ip> to any port 8000

---

Environment variables

GPX_* variables are read when a component first starts, to generate its admin.json / edge.json / agent.json; once the file exists, the JSON wins (only cluster.*, engine.metrics_disabled, engine.access_log_disabled and identity.node_name can still come from the environment when absent from the JSON).
See .env.example for the full list.

Variable	Component	Description
GPX_SECURITY_JWT_SECRET	Admin	JWT signing key (required)
GPX_PAIRING_SECRET	Admin / Edge / Agent	Shared secret for automatic pairing (HMAC WebSocket)
GPX_EDGE_TOKEN	Edge	Explicit token (alternative to shared secret)
GPX_TRUSTED_PROXIES	Edge / Admin	CSV of IPs/CIDRs of trusted front proxies (e.g. Cloudflare ranges) whose X-Forwarded-For / CF-Connecting-IP / X-Real-IP are honored. Loopback and private ranges are always trusted; * trusts everything (legacy, spoofable).
GPX_IDENTITY_EDGE_NODE_NAME	Admin	Edge hostname/IP reachable by Admin (http://<value>:8000)
GPX_CONTROL_PLANE_EDGE_ENDPOINT	Agent	Edge URL as seen by Agent (http://<edge>:8000)
GPX_ENGINE_LOG_LEVEL	All	Log level (debug/info/warn/error)
GPX_VULNSCAN_ALLOW_PRIVATE	Admin	true/1/yes: allow CVE scanner on private backends (RFC1918/ULA). Default: denied (anti-SSRF). Localhost and cloud metadata remain blocked.
GPX_BACKUP_KEY	Admin	(optional) Encryption key for Admin snapshots (AES-GCM). Takes precedence over a key set in the UI (Backups › Encryption key: generate, rotate, reveal by the superadmin). Without any key: JSON redacted of secrets, unencrypted. With a key: snapshots also embed an encrypted secrets section for a full restore (keep a copy of the key off the server).
GPX_NODE_TOKEN_KEY	Admin	(optional) Encrypts node tokens at rest. Otherwise derived from JWT secret.

---

Tech stack

Domain	Choice
Language	Go 1.25 — single static binary, zero runtime dependency
Protocols	HTTP/1.1, HTTP/2, HTTP/3 QUIC (quic-go), TCP/UDP L4
Control plane	Persistent WebSocket nhooyr.io/websocket — Admin→Edge(WS), Agent→Edge(WS)
TLS	SSL termination + SNI Passthrough, ACME DNS-01 wildcard (33 DNS providers), HTTP-01, TLS-ALPN-01
Admin persistence	CGO-free SQLite (modernc.org/sqlite) — config, users, tokens — Raft HA option
Edge persistence	Proxies: YAML files (proxies/*.yaml, proxies-revisions/*.yaml) · AES-256-GCM local cache (certs)
Configuration	GPX_* environment variables + optional JSON
Discovery	Docker Engine API via Unix socket (read-only), Portainer, Kubernetes, Consul, Nomad, etcd v3, Amazon ECS
Plugins	WebAssembly via wazero (no CGO)
Metrics	Prometheus on the Edge internal API (:8000/metrics, bearer token; public /metrics only with GPX_METRICS_PUBLIC=1), OpenTelemetry (OTLP)
Security	OWASP CRS-4 WAF (13 rule sets, request + response inspection), behavioral Ephor, native Fail2Ban, CrowdSec, automation flows (rules, schedules, playbooks with approval), step-by-step IP / CIDR trace over long periods, rate limiting, Geo-IP, ECDSA P-256 JWT, HMAC-SHA256 WS, CVE scanner with KEV/EPSS enrichment and configurable remediation SLA
Deployment	Single binary · Docker Compose · systemd

---

Documentation

Document	Description
CLI	Full reference for all commands and options
Detailed architecture	Data flows, technical decisions
Inter-Edge delegation	Passthrough vs Terminate modes, client IP, prerequisites
Features	Product capability catalogue
API specifications	Full REST contract
MCP	MCP server — tools, PAT auth, Claude/Cursor clients
Config schema	JSON schema for proxies
FAQ	First start, password reset, Docker labels, delegation
Changelog	Change history by version
Versioning	Version bump rules (SemVer)
Public roadmap	High-level milestones

French version: README.fr.md