A high-performance, multi-protocol proxy server written in C using GLib. Features kernel-integrated VPN gateway, deep packet inspection, protocol analysis and plugin extensibility.
Features · Usage · Getting Started · Architecture· Extending Deadlight · Use Cases · Roadmap · Configuration · License
Deadlight is a C-based proxy server built on GLib that handles multiple network protocols through a unified, extensible architecture. It features automatic protocol detection, TLS interception with certificate mimicry, plugin support, a VPN gateway mode, and a built-in web UI for monitoring and control.
Deadlight Proxy is a standalone, multi-protocol proxy server that can be used:
- Standalone:
- Traditional Proxy: HTTP/HTTPS/SOCKS proxy with TLS interception
- VPN Gateway: Layer 3 tunneling with kernel-level TCP/IP stack integration
- Protocol Bridge: API-based translation between web and native protocols (SMTP, IMAP, etc.)
- Network Security Tool: Ad blocking, rate limiting, and traffic inspection
- As part of the Deadlight Edge Platform: As a protocol bridge between Cloudflare Workers and local services (email, federation, etc.). Using as a component
This README focuses on standalone usage. For platform integration, see edge.deadlight.
- Kernel-Integrated VPN: True Layer 3 VPN gateway using Linux TUN devices
- True Multi-Protocol: One binary handles HTTP/S, SOCKS4/5, SMTP, IMAP/S, FTP, WebSocket, VPN, and custom protocols
- Intelligent TLS Interception: Mimics upstream certificates for transparent HTTPS inspection Security Considerations
- Plugin Architecture: Extend functionality without recompiling (ad-blocking, rate limiting, custom filters)
- Zero-Config Protocol Detection: Automatically identifies protocols from connection patterns
- Built-to-scale: Connection pooling, worker threads, async I/O, graceful error handling
Deadlight’s core innovation is its decoupling of the protocol from the service.
Stateless by Design: Instead of maintaining a local database or a mail queue, the proxy translates TCP traffic into clean HTTP API calls. This offloads all state management to a globally available database, allowing the proxy to remain lightweight and stateless. It can be turned off without losing any data.
Protocol Agnostic: The proxy is not an "email server" or a "SOCKS proxy"—it’s a platform for handling any TCP-based protocol. Its modular architecture means you can add new protocol handlers (e.g., for XMPP or Matrix) as simple, self-contained C files without changing the core application.
Secure Connectivity with Tailscale: The proxy leverages Tailscale for secure mesh network connections, allowing seamless VPN-like gateway services. for secure, outbound-only connectivity. This means your home IP address is never exposed, your firewall can remain closed, and you don’t need to worry about dynamic IPs or complex NAT configurations. Your home machine becomes a trusted network gateway, not a public server.
Deadlight is built on a modular design managed by a central DeadlightContext. A connection flows through the system as follows:
- The Main Thread runs a
GSocketService, accepting new connections. - Incoming connections are passed to a Worker Thread from a
GThreadPool. - The worker thread performs Protocol Detection by peeking at the initial bytes of the connection.
- The appropriate registered
DeadlightProtocolHandleris invoked to handle the connection. - The handler processes the request. It can either complete the request synchronously or, for long-lived tunnels, hand off control to asynchronous I/O watchers on its own thread's event loop. This prevents the worker thread from blocking.
VPN Gateway Mode: Unlike traditional proxies that work at Layer 7 (Application), Deadlight can operate at Layer 3 (Network) using Linux TUN devices. This allows it to:
- Route all system traffic transparently
- Handle any TCP/IP protocol without application configuration
- Maintain kernel-level TCP state for optimal performance
- Integrate with existing connection pooling for upstream efficiency
Modular Design: The system is organized around these core managers:
- Network Manager: Handles listener sockets, worker pool, and connection state
- SSL Manager: Manages TLS contexts, CA certificates, and performs interception
- Protocol System: Manages registration and detection of protocol handlers
- VPN Manager: Handles TUN device creation, packet routing, and TCP state
- Connection Pool: Reuses upstream connections for efficiency
- Plugin System: Dynamically loads and manages extension modules
Connection Flow:
- Proxy Mode: Connections → Protocol Detection → Handler → Upstream
- VPN Mode: Packets → TUN Device → TCP State Machine → Proxy Pipeline → Upstream
-
High-Performance C Foundation: Built with the robust and efficient GLib ecosystem for high-throughput, low-latency network I/O and multi-threaded connection handling.
-
VPN Gateway Mode: Kernel-integrated Layer 3 tunneling with transparent TCP proxying through TUN devices
-
Multi-Protocol Support: A single binary can act as a bridge for HTTP/HTTPS, SOCKS, SMTP, IMAP/S, Websocket, FTP (with command inspection) and a custom API.
-
API-First Design: Complete REST API for external integration, enabling real-time status monitoring, email sending, and federation from any web application.
-
Email-based Federation: A simplified approach to decentralized social media that uses proven email protocols for instance-to-instance communication, eliminating the need to invent a new protocol.
-
Advanced Security: Features include on-the-fly TLS interception (for development/analysis), robust certificate validation, and a secure deployment model that leverages outbound-only connections.
Advanced Multi-Protocol Support:
- HTTP/1.1 & HTTPS: Full proxying with a robust
CONNECTtunnel implementation - SSL/TLS Interception (MITM): Full Man-in-the-Middle capability with on-the-fly certificate generation for deep traffic analysis
- VPN Gateway: Kernel-level TCP/IP stack integration for transparent system-wide proxying
- WebSocket (Terminating Proxy): Acts as a true WebSocket endpoint, enabling frame-by-frame inspection, logging, and manipulation
- FTP (Intelligent Proxying): Full command inspection and dynamic rewriting of
PASVresponses to transparently proxy passive mode data connections - SOCKS4/4a & SOCKS5: Standardized support for versatile TCP-level proxying
- IMAP/S & SMTP: Basic support for email protocols, including
STARTTLS - Custom API: A built-in API for management and integration
Connection Management:
- Connection Pool: Efficient reuse of upstream connections across VPN and proxy modes
- Worker Thread Pool: Configurable thread pool for handling concurrent connections
- Async I/O: Non-blocking operations using GLib's event loop
- Session Management: Intelligent TCP state tracking in VPN mode with automatic cleanup
Plugin System:
- Dynamic Loading: Load plugins at runtime without recompiling
- AdBlocker Plugin: Block ads and trackers at the network level (21+ domains by default)
- RateLimiter Plugin: Configurable rate limiting per client (60 req/min default, 10 req/min for auth endpoints)
- Plugin API: Simple interface for creating custom plugins in C
Monitoring & Control:
- Built-in Web UI: Real-time monitoring dashboard (port 8081 by default)
- REST API: Complete API for status, statistics, and control
- VPN Statistics: Track active connections, total connections, bytes sent/received
- Live Logging: Real-time log viewing through web interface
When used with edge.deadlight, the proxy exposes these endpoints:
GET /api/blog/status- Blog service health checkPOST /api/email/send- Send email via local SMTPPOST /api/federation/send- Federate content to other instancesGET /api/email/status- Email queue status and processing metrics
These endpoints translate web requests into native protocol operations.
Example: /api/email/send receives JSON, translates it to SMTP
commands, and sends via your configured SMTP server.
Deadlight Proxy can be embedded in larger systems:
- REST API Integration: Control the proxy programmatically
- Custom Protocol Handlers: Add application-specific protocols
- Tailscale Mesh: Deploy as a secure network gateway
- Example: See edge.deadlight for a full platform implementation using this proxy as a component
STANDALONE MODE:
Client → Deadlight Proxy → Internet Services
PLATFORM MODE:
Cloudflare Worker → Tailscale → Deadlight Proxy → Local Services
↓
API Bridge
↓
(SMTP/IMAP/Federation)
TLS interception (MITM) is powerful. With great power, comes great responsibility.
- Development use only - Never use on production traffic you don't control
- Local Regulations - Intercepting traffic may be illegal in some jurisdictions.
- Secure your CA key - Anyone with your CA can impersonate any site
- Browser warnings - Users will see certificate warnings unless they trust your CA
When using with edge.deadlight:
- Secure your
X-API-Key- This authenticates the Cloudflare Worker - Use Tailscale ACLs - Restrict which devices can reach the proxy
- Monitor logs - Watch for unauthorized access attempts
DNS-Level Ad Blocking (Pi-hole Inspired)
Block ads, trackers, and malware domains at the network level Configure your router/devices to use Deadlight as HTTP/HTTPS proxy The AdBlocker plugin intercepts requests to known ad domains Blocks 21+ ad/tracker domains by default (easily extensible) Works across all devices on your network Logs blocked requests for monitoring No DNS configuration needed—works at the HTTP layer
Privacy-Focused VPN Alternative
Route all traffic through Deadlight + Tailscale mesh network Encrypts traffic without trusting a third-party VPN provider Self-hosted, you control the exit nodes Integrates with Tailscale for secure mesh networking No logging (unless you explicitly enable it) Works with any protocol, not just HTTP Corporate Network Gateway
Deploy as a security layer for remote workers Inspect encrypted traffic for compliance/DLP Rate limit API endpoints per-client Block malicious domains in real-time
HTTPS Debugging Without Charles/Burp
Intercept and inspect HTTPS traffic from any application
./bin/deadlight -c deadlight.conf.nplugin -v
curl --cacert ~/.deadlight/ca.crt -x http://localhost:8080 https://api.example.comAutomatic certificate generation with upstream mimicry Full request/response logging No application modification needed Works with mobile apps, desktop software, CLI tools
API Gateway for Legacy Protocols
Bridge old protocols (SMTP, IMAP, FTP) to modern REST APIs Use the plugin system to translate protocol commands to HTTP Perfect for modernizing legacy infrastructure Add webhooks to decades-old systems Monitor and log previously opaque protocols
Protocol Testing & Fuzzing
Test how clients handle malformed responses Inject delays or errors for chaos testing Analyze protocol handshakes in detail
Email Server Bridge
Access your Gmail/IMAP from anywhere without exposing ports Deadlight acts as a secure tunnel over Tailscale
telnet localhost 8080 # Connects to imap.gmail.com:993 via TLS tunnel
A001 NOOPNo open firewall ports needed Works from any device on your Tailscale network Centralizes authentication and logging Secure Home Network Gateway
Single entry point for all home services
Deploy on a Raspberry Pi or VPS Route traffic through Tailscale mesh Monitor all network activity from web dashboard Multi-Site Proxy Network
Deploy Deadlight at multiple locations Manage all instances from a central dashboard Implement consistent security policies Aggregate logs and metrics
- API-First: Full REST API for real-time status and management.
- Tailscale Mesh Deployment: Simplified private access to remote servers leveraging Tailscale's network.
- VPN Gateway: Kernel-integrated Layer 3 tunneling with transparent TCP proxying through TUN devices.
- Plugin Ecosystem: API for creating and sharing ad-blocking, analytics, and other plugins.
- Local Web Interface: A minimalist web server within the proxy for easy, direct configuration and debugging.
- Enhance FTP Handler: Add support for
PORT(active) mode to complement the existingPASVimplementation. Improve data channel error reporting back to the control channel. - Refine Protocol Detection: The detection system is functional, but could be enhanced with a more explicit priority system to prevent conflicts (e.g., the initial HTTP vs. WebSocket issue).
- Mobile & Desktop Clients: Publish an API specification for the development of native clients.
- A C99 compliant compiler (GCC or Clang)
makepkg-config- GLib 2.0+ & GIO development libraries (
libglib2.0-dev) - gnutls development libraries (
gnutls) - libmicrohttpd (for web UI)
- Root/CAP_NET_ADMIN (for VPN mode run as sudo)
On Debian/Ubuntu, install all prerequisites with:
sudo apt-get update
sudo apt-get install build-essential pkg-config libglib2.0-dev libssl-dev glib-networking libmicrohttpd-devbuild-essential: Provides gcc, make, etc.libglib2.0-dev: The GLib core libraries and development headers.gnutls: GNU TLS functions.glib-networking: The essential backend for GIO's TLS functionality.
Clone the repository and use the provided Makefile:
git clone https://github.com/gnarzilla/proxy.deadlight
cd proxy.deadlight
make clean && make UI=1The executable will be located at bin/deadlight.
The proxy uses an INI-style configuration file. A sample is provided at docs/CONFIGURATION.
# Proxy only
./bin/deadlight -c deadlight.conf.example
# VPN Gateway (requires root)
sudo ./bin/deadlight -c deadlight.conf.vpnAdd deadlight certificate to the trust store. If using Firefox you will also need to add via firefox's settings.
sudo cp ~/.deadlight/ca/ca.crt /usr/local/share/ca-certificates/
sudo update-ca-certificates# Configure client to use VPN
sudo ip route add default via 10.8.0.1 dev tun0
# All traffic now goes through Deadlight
ping google.com # Proxied through VPN
curl http://example.com # Automatically intercepted
ssh remote-server # TCP traffic proxiedConfigure your browser or system to use http://localhost:8080 as its proxy. Or, use curl:
# HTTP/HTTPS
curl -x http://localhost:8080 http://example.com
curl --cacert ~/.deadlight/ca.crt -x http://localhost:8080 https://example.com
# SOCKS5
curl --socks5 localhost:8080 http://example.com
# WebSocket
curl --proxy http://localhost:8080 -H "Upgrade: websocket" http://ws.ifelse.io/# Proxy a standard HTTP request
curl -x http://localhost:8080 http://example.com
# Proxy an HTTPS request (using the CONNECT method)
curl -x http://localhost:8080 https://example.com
For TLS interception to work, you must instruct your client to trust the proxy's Certificate Authority. The CA certificate is generated automatically (e.g., in ~/.deadlight/ca/ca.crt).
# The --cacert flag tells curl to trust our custom CA for this one request.
curl --cacert ~/.deadlight/ca.crt -x http://localhost:8080 https://example.comUse curl to route a request through the SOCKS4 handler:
curl --socks4 localhost:8080 http://example.comcurl http://localhost:8080/api/statuscurl http://localhost:8080/api/connectionsTest the secure IMAP tunnel using telnet (this proves the TLS handshake and tunneling):
telnet localhost 8080Once connected, type the following and press Enter:
a001 NOOP
The proxy will establish a secure TLS connection to the upstream IMAP server and tunnel the data.
Connect to the proxy with a full-featured FTP client like FileZilla or lftp, using localhost as the host and 8080 as the port. The proxy will handle the PASV command and correctly rewrite the data connection address.
Alternatively, for a quick command-line test:
printf "USER anonymous\r\nPASV\r\n" | nc localhost 8080-c, --config FILE: Path to configuration file.-p, --port PORT: Port to listen on (overrides config).-d, --daemon: Run as a background daemon.-v, --verbose: Enable verbose (debug) logging.-h, --help: Show help message.
The DeadlightProtocolHandler interface and table-driven detection system make extending the proxy simple and powerful. To add a new protocol, you implement a few functions and add detection rules - the core handles everything else.
To add support for a new protocol:
-
Create protocol files in
src/protocols/:my_protocol.candmy_protocol.h -
Implement the DeadlightProtocolHandler interface:
detect: Inspects initial bytes and returns a priority (0 = no match, higher = better match)handle: Main function to process the connection. Returns:HANDLER_SUCCESS_CLEANUP_NOWfor synchronous completionHANDLER_SUCCESS_ASYNCfor async operationsHANDLER_ERRORon failure
cleanup: Optional protocol-specific cleanup
-
Add detection rules in
src/core/protocol_detection.c:// Add to protocol_table array { .name = "MyProtocol", .protocol_id = DEADLIGHT_PROTOCOL_MYPROTOCOL, .priority = 30, .rules = my_protocol_rules, .rule_count = 1 }
-
Update core files:
- Add enum value to
DeadlightProtocolindeadlight.h - Add case to
deadlight_protocol_to_string()inprotocols.c - Register handler in
deadlight_protocols_init()inprotocols.c
- Add enum value to
-
Add to Makefile: Add
src/protocols/my_protocol.ctoPROTOCOL_SOURCES -
Recompile: Your protocol is now live!
The table-driven detection system supports multiple matching types (exact, prefix, contains, custom) and compound rules (AND/OR), making it easy to handle complex protocol signatures.
deadlight/
├── bin/ # Compiled binaries
├── obj/ # Compiled object files
├── ssl/ # Directory for SSL certificates
├── src/
│ ├── core/ # Core modules (main, context, config, network, etc.)
│ ├── plugins/ # Built-in plugin implementations
│ ├── vpn/ # vpn gateway module
│ └── protocols/ # Protocol handler implementations
├── deadlight.conf.example # Example configuration file
├── Makefile # Build configuration
├── docs/ # Other Project Documentation
└── README.md # This file