--- title: PunkProxy url: 'https://punksky.com/en/punkproxy' markdown: 'https://punksky.com/en/punkproxy.md' lang: en date: '2026-09-25' description: 'PunkProxy v5 PunkProxy is a modern, high-performance HTTP gateway and reverse proxy with a comprehensive REST API and cluster support. Built in Go, PunkProxy provides enterprise-grade features for routing, security, and traffic management at the edge. Note PunkProxy is free and open source under…' --- # PunkProxy v5 PunkProxy is a modern, high-performance HTTP gateway and reverse proxy with a comprehensive REST API and cluster support. Built in Go, PunkProxy provides enterprise-grade features for routing, security, and traffic management at the edge. Note PunkProxy is **free and open source** under the Functional Source License (FSL-1.1-ALv2). Self-host at no cost, or use PunkSky managed hosting with SLAs and support. **Get started:** - [Source code](https://git.punksky.com) clone, build, and run yourself - [Container images](https://docker.punksky.com) pull from our Docker registry - [Documentation](https://wiki.punksky.com) guides and reference - [Managed service](https://billing.punksky.com) billing and customer portal ## Overview PunkProxy is designed to serve as a flexible edge proxy solution that sits between your clients and backend services. It provides domain-level routing, automatic SSL/TLS certificate management, advanced security features, and a powerful control plane API for managing your infrastructure. ## Key Features ### Implemented - **Domain-Level Routing** Route traffic to different backends based on domain names - **Automatic SSL/TLS Management** Built-in ACME client (Let's Encrypt) for automatic certificate provisioning and renewal - **Force SSL Redirect** Automatically redirect HTTP traffic to HTTPS - **JA3 Fingerprinting** Advanced TLS fingerprinting for client identification and security analysis - **Multi-Protocol Support** Full support for HTTP/3 (QUIC), HTTP/2, and HTTP/1.1 - **Control Plane API** RESTful API for managing zones, destinations, certificates, and settings - **Cluster Support** Designed for distributed deployments with shared state - **Prometheus Metrics** Built-in metrics endpoint for monitoring and observability - **GeoIP Integration** Geographic location detection using MaxMind GeoIP databases - **Session Management** Distributed session handling with Valkey (Redis-compatible) ### Planned - File caching for improved performance - IP and GEO-based blocking - Coraza WAF integration for web application firewall capabilities - Rate limiting per zone and destination - Agent checking and validation - Zone-level custom rules - Image processing services (resizing, re-encoding) ## Architecture PunkProxy consists of 3 main components: **Proxy Service** (`proxy/`) The high-performance edge proxy that handles incoming HTTP/HTTPS traffic. Handles TLS termination, routes requests to configured backends, implements security middleware (JA3, IP blocking, rate limiting), and serves metrics and health endpoints. **Control Plane** (`control/`) The management API and certificate authority. RESTful API for configuration management, ACME certificate management, zone and destination configuration, and database-backed configuration storage. **Legbot** (`legbot/`) A ACME client powered by the Go package Lego. ## Quick Start With Docker and Docker Compose: clone the repo from , set `ACME_EMAIL`, and run `docker-compose up -d`. Proxy runs on 9880 (HTTP) and 9443 (HTTPS); control plane API on 8088. Swagger at `http://localhost:8088/swagger/index.html`. For production, use `prod-docker-compose.yml`. Pull images from [docker.punksky.com](https://docker.punksky.com) for the fastest start. ## Usage ### Managing Zones Zones represent a collection of domains that route to one or more backend destinations. Use the control plane API to: - Create zones with domain names - Configure SSL certificates (automatic via ACME or manual) - Set up backend destinations - Enable/disable zones - Configure zone-specific settings ### API documentation The control plane exposes a Swagger/OpenAPI documentation endpoint. Once running, access it at `http://localhost:8088/swagger/index.html`. ### Metrics Prometheus metrics are available at `http://localhost:9191/metrics`. ## Configuration ### Environment variables **Proxy Service:** | Variable | Description | |---|---| | `HTTP` | Comma-separated list of HTTP ports (default: 9880) | | `HTTPS` | Comma-separated list of HTTPS ports (default: 9443) | | `CONTROL_PLANE` | Control plane API URL (default: http://control) | | `VALKEY` | Valkey/Redis connection string (default: valkey:6379) | | `SESSION_PREFIX` | Session key prefix (default: session) | **Control Plane:** | Variable | Description | |---|---| | `DSN` | PostgreSQL connection string | | `ACME_EMAIL` | Email for ACME certificate registration | | `ACME_URI` | ACME server URI (Let's Encrypt or test server) | | `DEBUG` | Enable debug mode | ## License This project is licensed under the **Functional Source License, Version 1.1, ALv2 Future License (FSL-1.1-ALv2)**. This license allows: - Internal use - Non-commercial education and research - Professional services for licensees Commercial products that compete with PunkSky require a [Partner Program](https://punksky.com/en/partner-program) agreement. **Future License Grant:** After 2 years from the release date, the code will be available under the Apache License 2.0. ## Roadmap ### Milestone 1 (In progress) - Domain level routing - ACME client - Force SSL redirect - JA3 fingerprinting - HTTP 3/2/1.1 support ### Milestone 2 (In progress) - File caching - IP and GEO blocking - Coraza WAF integration - Rate limiting ### Milestone 3 (Planned) - Agent checking - Zone level rules ### Milestone 4 (Planned) - Image services (resizing, re-encoding) ## Security PunkProxy includes several security features: - **JA3 Fingerprinting** Identify and track clients based on TLS handshake characteristics - **TLS Termination** Full control over TLS configuration and cipher suites - **IP Blocking** Block traffic from specific IP addresses or ranges - **GeoIP Blocking** Block traffic from specific geographic regions - **WAF Integration** Web Application Firewall support via Coraza (planned) **Repository:** [git.punksky.com](https://git.punksky.com) --- ## Navigation - Previous: [Home](https://punksky.com/en/index.md) - Next: [Utility Belt](https://punksky.com/en/utilitybelt.md)