English | 日本語

   

Veil - High-Performance Reverse Proxy Server

Veil is a reverse proxy and web server written in Rust. Its data plane runs on a custom io_uring runtime (no tokio/monoio) with rustls and optional kernel TLS, and it speaks HTTP/1.1, HTTP/2 (TLS and h2c), HTTP/3 (QUIC), gRPC, WebSocket and raw TCP/UDP (L4).

Highlights

• Fast data plane — io_uring on Linux (epoll/kqueue/WSAPoll elsewhere), zero-copy splice(2)/sendfile(2), kTLS offload, per-thread workers with SO_REUSEPORT.
• Protocols — HTTP/1.1, HTTP/2, h2c, HTTP/3, gRPC / gRPC-Web, WebSocket, L4 TCP/UDP proxy, several listening ports per process ([[listener]]), Unix domain socket listeners and backends.
• Proxy features — path/host/header routing, load balancing, health checks, circuit breaker, retries, response compression, proxy cache, buffering, header rewriting.
• Extensible — Proxy-Wasm filters (Wasmtime) on every protocol.
• Dynamic — VDS pushes routes and upstreams from a control plane (xDS-style long polling, ACK/NACK), and built-in ACME issues and renews certificates (HTTP-01, Let's Encrypt).
• Embeddable — use veil as a library to write API servers in Rust (macros, OpenAPI, tower, GraphQL, WebSocket, multipart, L4 handlers), C (libveil) or Python (FastAPI-compatible, ASGI) on the same io_uring data plane, with helper packages veil-proxy-kit and veil-api-kit and a production guide.
• Operable — hot reload (SIGHUP) of config and certificates, Prometheus metrics, OpenTelemetry, structured access logs, admin API.
• Secure by default — memory-safe Rust, seccomp/Landlock (Linux), capsicum (FreeBSD), pledge/unveil (OpenBSD), Seatbelt (macOS), privilege dropping.
• Cross-platform — Linux, FreeBSD, OpenBSD, NetBSD, macOS and Windows (x86_64 / aarch64).

Performance against nginx is published in docs/perf/README.md.

Install

The packages and the container image install a default configuration and page: run veil and open http://127.0.0.1:8080/ (the container: http://localhost:8080/).

	Command
Container	docker run --rm -p 8080:8080 ghcr.io/aofusa/veil (also aofusa/veil on Docker Hub)
Debian / Ubuntu, RHEL / Fedora / Amazon Linux	add the apt or dnf repository, then apt install veil / dnf install veil
Homebrew (macOS, Linux)	brew install aofusa/tap/veil, then brew trust aofusa/tap (Homebrew 7 and later)
Windows	winget install Aofusa.Veil
FreeBSD, OpenBSD, NetBSD	the ports in packaging/bsd/ports
Rust	cargo binstall veil-proxy or cargo install veil-proxy --locked --features full

cargo install, cargo binstall and the archives attached to each GitHub release install the veil binary only: create the configuration file yourself (the archive has an example in examples/). veil reads -c FILE, then VEIL_CONFIG, then the default path (/etc/veil/config.toml; %ProgramData%\veil\config.toml on Windows). See Configuration file.

To build from source (Rust stable, cmake and nasm):

cargo build --release                    # default: kTLS + HTTP/2 + mimalloc
cargo build --release --features full    # everything (HTTP/3, gRPC, WASM, cache, metrics, ...)

The binary is target/release/veil. See docs/guide/building.md for feature flags, packaging and BSD/macOS/Windows builds.

Quickstart

1. Create a certificate (self-signed for testing):

   openssl req -x509 -newkey ec -pkeyopt ec_paramgen_curve:secp384r1 -nodes \
     -keyout key.pem -out cert.pem -days 365 -subj "/CN=localhost"

2. Write config.toml — serve /static/ from disk and proxy everything else:

   [server]
   listen = "0.0.0.0:443"
   http2_enabled = true
   
   [tls]
   cert_path = "/etc/veil/ssl/cert.pem"
   key_path  = "/etc/veil/ssl/key.pem"
   
   # Static files under /static/
   [[route]]
   [route.conditions]
   path = "/static/*"
   [route.action]
   type = "File"
   path = "/var/www/"
   
   # Everything else goes to the application
   [[route]]
   [route.conditions]
   path = "/*"
   [route.action]
   type = "Proxy"
   url = "http://127.0.0.1:8080"

3. Validate and run:

   veil -t -c config.toml   # check the configuration
   veil -c config.toml      # start (SIGHUP reloads, SIGTERM shuts down gracefully)
   curl -k https://localhost/static/index.html

   Or run the container image (latest = musl; glibc is also published, for linux/amd64 and linux/arm64). With nothing mounted it serves a built-in page on port 8080:

   docker run --rm -p 8080:8080 ghcr.io/aofusa/veil      # open http://localhost:8080/

   With your own configuration, certificate and files (Container guide):

   docker run --rm -p 443:443 -p 443:443/udp \
     -v "$PWD/config.toml:/etc/veil/conf.d/config.toml:ro" \
     -v "$PWD/cert.pem:/etc/veil/ssl/cert.pem:ro" -v "$PWD/key.pem:/etc/veil/ssl/key.pem:ro" \
     ghcr.io/aofusa/veil:latest

   The image is the full-container build (epoll readiness reactor), so it runs under the container's default seccomp profile (Docker's default and Kubernetes' RuntimeDefault forbid io_uring).

A fully commented reference of every key is in examples/config.toml.

Use veil as a library

# Cargo.toml (the crate is `veil-proxy` on crates.io; keep the name `veil`, the macros refer to it)
[dependencies]
veil = { package = "veil-proxy", version = "0.11", default-features = false, features = ["full", "api"] }
serde_json = "1"

No .cargo/config.toml settings are needed (library guide). Python: pip install veil-api (import veil).

use veil::prelude::*;

#[veil::route(path = "/hello/{name}", method = "GET")]
async fn hello(name: String) -> Json<serde_json::Value> {
    Json(serde_json::json!({ "hello": name }))
}

#[veil::main]
async fn main() -> Result<(), veil::api::Error> {
    veil::serve(Config::load()?).await   // plaintext HTTP/1.1 + h2c on 127.0.0.1:8080, OpenAPI at /docs
}

See the library guide (Rust, C API, Python, building artifacts).

Documentation

Topic	Guide
Feature overview	docs/guide/features.md
Platforms & runtime backends	docs/guide/platforms.md
Building & packaging	docs/guide/building.md
Running, validation, reload & shutdown	docs/guide/running.md
Configuration reference	docs/guide/configuration.md
TLS, kTLS & certificate reload	docs/guide/tls.md
Routing, redirects & headers	docs/guide/routing.md
Load balancing, health checks & resilience	docs/guide/load-balancing.md
L4 stream proxy	docs/guide/l4-proxy.md
HTTP/2, HTTP/3 & WebSocket	docs/guide/protocols.md
Compression, cache & buffering	docs/guide/compression-cache.md
WASM extensions	docs/guide/wasm.md
API server library (Rust, C, Python)	docs/guide/library.md
VDS: dynamic routes from a control plane	docs/guide/vds.md
ACME: automatic certificates	docs/guide/acme.md
Metrics, tracing & logging	docs/guide/observability.md
Admin & cache purge APIs	docs/guide/admin-api.md
Security & sandboxing	docs/guide/security.md
Performance tuning & benchmarks	docs/guide/performance.md
Testing (developers)	docs/guide/testing.md
References & logos	docs/guide/references.md

Contributors: start with AGENTS.md (design philosophy, constraints and workflow).

License

Licensed under either of:

• Apache License, Version 2.0 (LICENSE-APACHE)
• MIT License (LICENSE-MIT)

at your option.

(c) 2025 aofusa