Tardigrade

A small Zig edge server for static file serving, reverse proxying, TLS termination, and operator-friendly reloads.

Releases | Support Matrix | Observability | Security | Contributing

---

Host-native edge serving in Zig

Tardigrade is a lightweight HTTP/1.1 server and reverse proxy for deployments that want a small native binary, config-driven routing, observable runtime behavior, and predictable reloads.

It is early-stage software with a deliberately narrow stable core. The official compatibility promise is documented in the Core v1 support matrix.

---

Menu

• Features
• Install
• Build from source
• Quick start
• Overview
• Full documentation
• Performance
• Development
• Getting help
• About

Features

• Static file serving with normalized path handling, range support, cache validation, and symlink escape protection.
• Reverse proxying with config-driven location routing, upstream health checks, retries for safe connection-drop cases, and optional bounded streaming for larger HTTP transfers.
• TLS termination for the stable HTTP/1.1 edge path.
• Hot reloads and graceful drain behavior for operator-managed deployments.
• JSON access logs, request IDs, W3C traceparent forwarding, and Prometheus metrics at /status/metrics by default.
• Request limits, rate limiting, security headers, and release-gated security regression tests.
• A native packaging path with release archives, published DEB/RPM packages, service files, checksums, SBOMs, and provenance attestation.

HTTP/2, HTTP/3/QUIC, WebSocket/SSE, ACME, FastCGI, uWSGI, SCGI, memcached, and BearClaw-specific flows exist in-tree, but they are not all part of the stable Core v1 contract. Check the support matrix before depending on a specific surface.

Install

The fastest way to install the latest release is the official install script:

curl -fsSL https://github.com/Bare-Systems/Tardigrade/releases/latest/download/install.sh | sh

The installer downloads the matching Linux release archive (x86_64 or aarch64), verifies it against tardigrade-checksums.txt, and installs the tardi binary (with a tardigrade compatibility alias) into $HOME/.local/bin by default. Published archives currently cover Linux only; macOS is not yet built or published by the release workflow (see packaging/README.md for exact status).

Published release binaries use the default "general" TLS profile, which links OpenSSL at runtime — installing via this script or the raw archive requires OpenSSL 1.1/3.x already present on the target host, the same runtime dependency the DEB/RPM packages declare explicitly.

Other install paths:

• Download release archives directly from GitHub Releases.
• Native DEB/RPM packages (published on every release), systemd/launchd service files, and a Homebrew formula — see packaging/README.md for current status and install/build instructions.
• Build from source (see below).

Build from source

Requirements:

• Zig 0.16.0
• OpenSSL development libraries on Linux, for example libssl-dev on Debian or Ubuntu
• HTTP/3 is served by the built-in native Zig QUIC/H3 stack and requires no additional system libraries.

For development:

git clone https://github.com/Bare-Systems/Tardigrade.git
cd Tardigrade
zig build run

For a release-mode binary:

zig build -Doptimize=ReleaseFast
./zig-out/bin/tardi --help

With explicit version metadata:

zig build -Doptimize=ReleaseFast -Dversion="$(git describe --tags --always)"

Useful build options are documented in CONTRIBUTING.md.

Quick start

Create a small static root:

mkdir -p public
printf '%s\n' '<h1>Hello from Tardigrade</h1>' > public/index.html

Create tardigrade.conf:

listen 8069;
server_name localhost;

root ./public;
try_files $uri /index.html;

location = /health {
    return 200 ok;
}

location /api/ {
    proxy_pass http://127.0.0.1:8080;
}

Build and run:

zig build
./zig-out/bin/tardi run -c ./tardigrade.conf

Then open:

• http://localhost:8069/
• http://localhost:8069/health

Common CLI commands:

./zig-out/bin/tardi check ./tardigrade.conf
./zig-out/bin/tardi config validate ./tardigrade.conf
./zig-out/bin/tardi validate -c ./tardigrade.conf
./zig-out/bin/tardi print-config -c ./tardigrade.conf
./zig-out/bin/tardi status -c ./tardigrade.conf
./zig-out/bin/tardi reload -c ./tardigrade.conf
./zig-out/bin/tardi stop -c ./tardigrade.conf
./zig-out/bin/tardi config init

check performs a dry parse and semantic validation without starting listeners or connecting to upstreams. When no path is supplied, it validates ./tardigrade.toml; pass the path explicitly when using the nginx-style tardigrade.conf examples.

Overview

Tardigrade's stable Core v1 identity is intentionally focused: a host-native Zig HTTP/1.1 edge server and reverse proxy with predictable operator behavior. The main thread handles the non-blocking accept/event loop, while accepted connections move through a bounded worker pool for blocking TLS, parsing, proxying, and response writes.

Idle HTTP/1.1 keep-alive connections are parked off the worker pool between requests, so idle clients do not consume worker capacity. HTTP/2 multiplexes internally, and HTTP/3 is served over a built-in native Zig QUIC/H3 stack that needs no external QUIC libraries. Both HTTP/2 and HTTP/3 are tracked as experimental surfaces rather than part of the default stable release contract.

Configuration is nginx-inspired and can be checked before startup with tardi check <config>. Runtime inspection commands such as status and print-config are designed to make package and service deployments easier to operate without guessing which config file or pid file is active.

Full documentation

Topic	Location
Core v1 support matrix	docs/SUPPORT_MATRIX.md
HTTP/3 rollout and lifecycle	docs/HTTP3_ROLLOUT.md
Concurrency & hot-path audit	docs/CONCURRENCY.md
Observability	docs/OBSERVABILITY.md
Proxy security	docs/PROXY_SECURITY.md
Security test plan	docs/SECURITY_TEST_PLAN.md
Pentest playbook	docs/PENTEST_PLAYBOOK.md
Code review checklist	docs/CODE_REVIEW_CHECKLIST.md
Release checklist	docs/RELEASE_CHECKLIST.md
Packaging	packaging/README.md
Benchmarks	benchmarks/README.md
BearClaw example	examples/bearclaw/README.md
Security policy	SECURITY.md
Contributing	CONTRIBUTING.md
Release history	CHANGELOG.md

Performance

Canonical benchmark runs are captured from a dedicated benchmark target, not a local laptop fallback run. Saved benchmark JSON records latency percentiles, throughput, errors, and optional target CPU/RSS samples.

Scenario	req/s	p50 (ms)	p95 (ms)	p99 (ms)	p999 (ms)	CPU %	Peak RSS (MiB)	MB/s	Errors
keepalive	4700	0.4	-	41.8	-	-	-	-	0
proxy-http1	1724	1.3	-	114.9	-	-	-	-	0
static-http1	4586	0.4	-	46.1	-	-	-	-	0

v0.32.0-18-gb44f8c1 · 2026-05-02 · tool: wrk · 4 connections · 30s per scenario · host: 127.0.0.1 driver: loopback (dedicated benchmark target) · env: release-baseline · workers: 2 · config: release-baseline config CPU/RSS columns are sampled from the target Tardigrade process only when the run used --pid or --pid-file; otherwise they remain -.

Run ./benchmarks/run.sh --save benchmarks/baselines/$(git describe --tags).json then ./benchmarks/report.sh <file> --update-readme README.md to refresh this table.

Development

Use Zig 0.16.0 for local validation.

# Format check
zig fmt --check build.zig src/ tests/

# Unit tests
zig build test --summary all --error-style verbose

# Stable Web PKI differential corpus (requires OpenSSL and Go)
zig build test-pki-differential --summary all --error-style verbose

# Security corpus replay
zig build test-security-corpus

# Integration tests
zig build test-integration

# Failure-mode / chaos suite (broken origins, aborting clients, reloads)
zig build test-failure

# Pure-Zig QUIC/HTTP-3 package tests (no system libraries)
zig build test-quic

# Allocation budget report
zig build bench-allocations

See CONTRIBUTING.md and docs/CODE_REVIEW_CHECKLIST.md before making larger changes.

Getting help

• Use GitHub Issues for actionable bug reports and feature requests.
• Use SECURITY.md for vulnerability reporting instructions.
• Include the config, command, logs, platform, and whether the affected surface is listed as stable or experimental in the support matrix.

About

Tardigrade is developed by Bare Systems as a host-native edge component for small services, internal platforms, and controlled deployments. It is licensed under the Apache License 2.0.