Deadlight Proxy

A high-performance, multi-protocol proxy server built for real-world conditions: intermittent connectivity, resource constraints, and hostile networks. Written in C with GLib, featuring automatic protocol detection, TLS interception, VPN gateway mode, REST API, and lightweight web UI.

Multi-protocol in one binary · 17.6 MB Docker image · Works on ARM64 · REST API · Edge-native design

Quick Start · Features · API · Configuration · Documentation · Architecture · Roadmap

Security Notice: This proxy can perform TLS interception. Only deploy on hardware you control. See Security Considerations.

Quick Start

Download Binary (Fastest)

Grab the latest release for your platform:

# Linux amd64
curl -LO https://github.com/gnarzilla/proxy.deadlight/releases/latest/download/deadlight-linux-amd64
chmod +x deadlight-linux-amd64
./deadlight-linux-amd64 -v

# Linux arm64 (Raspberry Pi, ARM servers)
curl -LO https://github.com/gnarzilla/proxy.deadlight/releases/latest/download/deadlight-linux-arm64
chmod +x deadlight-linux-arm64
./deadlight-linux-arm64 -v

Proxy runs on :8080, Web UI on :8081, API at /api.

Docker

docker run -d \
  --name deadlight-proxy \
  -p 8080:8080 \
  -p 8081:8081 \
  gnarzilla/proxy-deadlight:latest

Docker Compose

version: '3.8'
services:
  proxy:
    image: gnarzilla/proxy-deadlight:latest
    ports:
      - "8080:8080"
      - "8081:8081"
    environment:
      - DEADLIGHT_AUTH_SECRET=your-secret-here
    volumes:
      - ./config:/etc/deadlight
      - ./federation:/var/lib/deadlight/federation
      - ./blog-cache:/var/lib/deadlight/blog
    restart: unless-stopped

Platforms: linux/amd64, linux/arm64 (Raspberry Pi, ARM servers, Apple Silicon)

Build from Source

Build instructions

Requirements: GLib 2.0+, OpenSSL 1.1+, GCC/Clang, json-glib-1.0 Optional: libmicrohttpd (for web UI)

# Install dependencies (Debian/Ubuntu)
sudo apt-get install build-essential pkg-config libglib2.0-dev \
  libssl-dev libjson-glib-dev libmicrohttpd-dev

# Build
git clone https://github.com/gnarzilla/proxy.deadlight.git
cd proxy.deadlight
make clean && make UI=1

# Run
./bin/deadlight -c deadlight.conf -v

Verify It's Working

# HTTP proxy
curl -x http://localhost:8080 http://example.com

# Health check
curl http://localhost:8080/api/health

# Web UI
open http://localhost:8081

Features

Core Capabilities

Feature	Description
Multi-Protocol	HTTP/S, SOCKS4/5, WebSocket, SMTP, IMAP/S, FTP—auto-detected
TLS Interception	MITM HTTPS inspection with upstream cert mimicry
Connection Pooling	Reuses upstream connections with health checks
VPN Gateway	Kernel-integrated TUN device for Layer 3 routing
REST API	Email, federation, metrics, and management endpoints
Blog Cache	Read-through cache for blog.deadlight with offline fallback
Plugins	Ad blocking, rate limiting, custom filters
Web UI	SSE-powered real-time monitoring at `:8081`
Resource-Efficient	17.6 MB Docker image, minimal RAM

REST API

Quick Examples

# Health check
curl http://localhost:8080/api/health

# Send email
curl -X POST http://localhost:8080/api/email/send \
  -H "Content-Type: application/json" \
  -d '{"to":"user@example.com","subject":"Test","body":"Hello"}'

# View metrics
curl http://localhost:8080/api/metrics | jq

# Federation: Send post to another Deadlight instance
curl -X POST http://localhost:8080/api/federation/send \
  -H "Content-Type: application/json" \
  -d '{"target_domain":"other.deadlight.boo","content":"Hello!","author":"alice"}'

Endpoints

Category	Endpoint	Description
System	`GET /api/health`	Health check with version info
	`GET /api/system/ip`	External IP detection
	`GET /api/metrics`	Real-time connection/protocol/pool stats
	`GET /api/stream`	SSE real-time event stream
	`GET /api/dashboard`	Unified metrics + logs
	`GET /api/logs`	Log buffer
Email	`POST /api/email/send`	Send email (no auth)
	`POST /api/outbound/email`	Send email (HMAC auth required)
Federation	`POST /api/federation/send`	Send post to another instance
	`POST /api/federation/receive`	Receive federated posts
	`GET /api/federation/posts`	List stored posts
	`GET /api/federation/status`	Federation system status
	`GET /api/federation/test/{domain}`	Test domain connectivity
Blog	`GET /api/blog/posts`	List blog posts (cached)
	`GET /api/blog/status`	Blog system status

Full API documentation: docs/API.md

Federation Architecture

   Alice's Proxy                    Bob's Proxy
   (proxy.alice.deadlight)         (proxy.bob.deadlight)
         │                                │
         ├─ POST /api/federation/send     │
         │  {"target": "bob.deadlight"}   │
         │                                │
         └──> SMTP (via MailChannels) ────┤
                                          │
                    ┌─────────────────────┘
                    │
                    ├─ POST /api/federation/receive
                    └─ Stores in /var/lib/deadlight/federation/

Configuration

Default Locations

Docker: /etc/deadlight/deadlight.conf (auto-generated)
Native: /etc/deadlight/deadlight.conf

Key Sections

[core]
port = 8080
max_connections = 500
worker_threads = 4
auth_secret = <generate_with_openssl_rand>

[ssl]
enabled = true
ca_cert_file = /etc/deadlight/ca.crt
ca_key_file = /etc/deadlight/ca.key

[smtp]
mailchannels_api_key = <your_api_key>

[plugins]
enabled = true
autoload = adblocker,ratelimiter

[vpn]
enabled = false  # Requires root + --privileged
tun_device = tun0

[blog]
workers_url = https://deadlight.boo
cache_ttl = 300
enable_cache = true
cache_dir = /var/lib/deadlight/blog

Hot-reload: Config changes apply automatically (no restart needed).

Generate auth secret: openssl rand -hex 32

Example configs: deadlight.conf.example, deadlight.conf.docker

Command-Line Options

-c, --config FILE   Config file (default: /etc/deadlight/deadlight.conf)
-p, --port PORT     Override listening port
-v, --verbose       Enable debug logging
-d, --daemon        Run as background daemon
-h, --help          Show usage

Security Considerations

TLS Interception

When enabled, the proxy terminates and re-encrypts TLS. This means:

Plaintext is visible to the proxy process
Plugins can inspect/modify decrypted traffic
Credentials in requests are exposed to the proxy

Recommendation: Run on trusted hardware only.

Install CA Certificate

# Extract CA from Docker
docker run --rm gnarzilla/proxy-deadlight:latest cat /etc/deadlight/ca.crt > deadlight-ca.crt

# Debian/Ubuntu
sudo cp deadlight-ca.crt /usr/local/share/ca-certificates/
sudo update-ca-certificates

# Fedora/RHEL
sudo cp deadlight-ca.crt /etc/pki/ca-trust/source/anchors/
sudo update-ca-trust

# macOS
sudo security add-trusted-cert -d -r trustRoot \
  -k /Library/Keychains/System.keychain deadlight-ca.crt

# Windows: Double-click → Install → Trusted Root Certification Authorities
# Firefox: about:preferences#privacy → Certificates → Authorities → Import

Warning: Only install on devices you control. Breaks certificate pinning on some sites.

REST API Security

API binds to 0.0.0.0 by default—restrict with api_bind = 127.0.0.1
HMAC auth required for sensitive endpoints (/api/outbound/*)
Federation endpoints accept unauthenticated POSTs (by design)

Architecture

┌─────────────────┐
│  GSocketService │ ← Connection acceptance (port 8080)
└────────┬────────┘
         │
    ┌────▼─────┐
    │  Workers  │ ← Thread pool
    └────┬─────┘
         │
    ┌────▼──────────┐
    │  Detection     │ ← Protocol auto-detection
    └────┬──────────┘
         │
    ┌────▼─────────────────────────┐
    │  Protocol Handlers           │
    │  ├─ HTTP/HTTPS               │
    │  ├─ SOCKS4/5                 │
    │  ├─ API (REST endpoints)     │
    │  ├─ SMTP/IMAP                │
    │  ├─ WebSocket                │
    │  ├─ TLS Interception         │
    │  ├─ Connection Pool          │
    │  └─ Plugin Hooks             │
    └──────────────────────────────┘

Design Philosophy:

Stateless core — no local DB/queues, federation uses filesystem
Edge-native — optimized for intermittent connectivity
Plugin-extensible — modify behavior without core changes
Performance-focused — connection pooling, async I/O, worker threads
API-first — RESTful interface for programmatic control

Use Cases

Scenario	How Deadlight Helps
Home Gateway	Secure all devices via VPN without exposing ports
Development	Inspect/modify API calls with TLS interception + plugins
Email Bridge	Send emails via REST API or tunnel legacy SMTP/IMAP
Privacy Tool	SOCKS proxy with built-in ad blocking
Edge Networks	Works on mesh/satellite/2G with intermittent connectivity
Federation Node	Inter-instance communication for distributed systems
Monitoring Hub	Real-time metrics via REST API for dashboards

Extending Deadlight

Add a Protocol Handler

Create src/protocols/myprotocol.c
Implement detect, handle, cleanup functions
Register in src/core/protocols.c
Rebuild: make

Add a Plugin

Create src/plugins/myplugin.c
Define hooks (on_request_headers, on_response, etc.)
Export with G_MODULE_EXPORT
Enable in config: [plugins] autoload = myplugin

See docs/EXTENDING.md for details.

Roadmap

Near-term (early 2026)

REST API with email sending
Federation system (experimental)
Connection pool metrics
Connection pool with TLS session reuse
Blog caching with offline fallback
Server-Sent Events for real-time dashboard
API rate limiting tested & vetted
Deeper TLS session management for pooled connections

Medium-term (late 2026)

Dynamic plugin loading (no rebuild required)
Full IPv6 support
Windows/macOS native builds
Prometheus metrics export
ActivityPub federation support

Long-term

HF radio transport layer for resilient, infrastructure-free networking

Part of the Deadlight Ecosystem

blog.deadlight — Cloudflare Workers blog (<10 KB pages)
meshtastic.deadlight — Internet-over-LoRa gateway
edge.deadlight — Unified edge platform

Documentation

API Reference — Complete REST API documentation
Quick Start Guide — Detailed setup instructions
Architecture — Technical deep dive
Extending Deadlight — Plugin and protocol development
Contributing — How to contribute

License

MIT License — see LICENSE

Support

Issues: GitHub Issues
Donate: ko-fi.com/gnarzilla
Email: gnarzilla@deadlight.boo

Contributions welcome — see CONTRIBUTING.md

Name		Name	Last commit message	Last commit date
Latest commit History 308 Commits
.github/workflows		.github/workflows
bin		bin
deadlight-monitoring		deadlight-monitoring
docs		docs
plugins		plugins
src		src
tests		tests
Dockerfile		Dockerfile
Makefile		Makefile
README.md		README.md
arch.txt		arch.txt
deadlight.ALPHA		deadlight.ALPHA
deadlight.conf.example		deadlight.conf.example

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

Deadlight Proxy

Quick Start

Download Binary (Fastest)

Docker

Build from Source

Verify It's Working

Features

Core Capabilities

REST API

Quick Examples

Endpoints

Configuration

Default Locations

Key Sections

Command-Line Options

Security Considerations

TLS Interception

REST API Security

Architecture

Use Cases

Extending Deadlight

Roadmap

Near-term (early 2026)

Medium-term (late 2026)

Long-term

Part of the Deadlight Ecosystem

Documentation

License

Support

About

Uh oh!

Releases 2

Packages

Uh oh!

Languages

gnarzilla/proxy.deadlight

Folders and files

Latest commit

History

Repository files navigation

Deadlight Proxy

Quick Start

Download Binary (Fastest)

Docker

Build from Source

Verify It's Working

Features

Core Capabilities

REST API

Quick Examples

Endpoints

Configuration

Default Locations

Key Sections

Command-Line Options

Security Considerations

TLS Interception

REST API Security

Architecture

Use Cases

Extending Deadlight

Roadmap

Near-term (early 2026)

Medium-term (late 2026)

Long-term

Part of the Deadlight Ecosystem

Documentation

License

Support

About

Topics

Resources

Contributing

Uh oh!

Stars

Watchers

Forks

Releases 2

Packages 0

Uh oh!

Languages

Packages