Skip to content
Huginn Proxy Huginn Proxy

Getting started

Huginn Proxy is a reverse proxy built on Tokio, Hyper, and Rustls. It passively fingerprints clients (TLS JA4, HTTP/2 Akamai, optional TCP SYN via eBPF) and injects trusted x-tls-*, x-http2-*, and x-tcp-* headers for backends. Fingerprinting primitives come from Huginn Net. TCP SYN fingerprinting is implemented via an XDP eBPF program using Aya.

Inspired by production-grade proxies like Pingora, and rust-rpxy.

Prerequisites

Section titled “Prerequisites”
  • Obtain a binary or image: use the latest releases on GitHub; see Artifacts for GHCR image names and Containers to run with Docker Compose.
  • Linux (kernel ≥ 5.11) is required for TCP SYN / eBPF fingerprinting; TLS and HTTP/2 fingerprints work on other platforms when eBPF is disabled.

Scope and limitations

Section titled “Scope and limitations”

Huginn Proxy is built for passive fingerprinting and a small set of production hardening features, not feature parity with general-purpose load balancers. Before you invest time, be aware of the rough edges (this list will grow as we document more):

  • TLS (single certificate): one server certificate and key per process, read from paths in config. Multiple certificates per SNI / multi-tenant TLS vhosts are not supported.
  • TLS (certificate management): there is no built-in ACME (Let’s Encrypt), internal CA, or automatic issuance; many other proxies integrate that. You point config at files that some other process issues and renews (Kubernetes cert-manager, systemd timers, acme.sh, Vault, manual installs, etc.).
  • Load balancing: simple round-robin when a route references more than one backend address. There are no in-proxy health checks, least-connections, or weights. The design assumes an orchestrator (Kubernetes, Nomad, Docker Compose, etc.) or another layer owns replicas, health, and failover. If you run bare VMs without that, plan for health and failover outside this proxy (see Routes for the longer story).

It is the current scope. If you need an additional feature (TLS, routing, balancing, ops, etc.), open an issue on GitHub and describe the requirements and constraints (environment, scale, must-haves vs nice-to-haves). That gives maintainers something concrete to evaluate; there is no guarantee of priority or implementation.