Tiyi documentation
Tiyi is a single Go binary that runs a Caddy reverse proxy, a Coraza WAF with the OWASP Core Rule Set, an embedded SQLite control plane, and a Vben Admin UI. These docs cover everything from a five-minute first run to a hardened multi-node production deployment.
Start here
If you've never run Tiyi before, follow these three pages in order. They take about 30 minutes end to end and leave you with a real WAF in front of a real upstream.
Build the binary, start tiyi standalone, create your first site, and watch the WAF block real attacks. Five minutes.
Build from source, download a signed release, configure the YAML config, and choose between standalone, server, and agent modes.
Sites, upstream pools, certificates, WAF policies, agents, telemetry, and the audit chain — what each one is and how they fit together.
Every tiyi subcommand grouped by resource, with the flags that matter and the exit-code contract.
The ConnectRPC contract that drives the UI, CLI, and agent stream. Auth, error codes, and the 14 services.
Production hardening, HA failover with epoch fencing, SIEM egress, observability, and the upgrade path.
Design philosophy
Three architectural decisions shape every page that follows:
- One binary, zero runtime deps. No Docker daemon, no Nginx, no Postgres, no Redis. The binary embeds Caddy, Coraza, SQLite, and the Vben Admin UI. A reasonable sysadmin should bring up a usable instance in under five minutes.
- API-first with declarative YAML. One ConnectRPC API owns every mutation. The UI and CLI are thin clients.
tiyi apply -f site.yamlproduces the same effect as clicking Save — same validator, same mutator, same audit row. - Push + reconcile, not push alone. Agents hold a long-lived ConnectRPC bidi stream. Every change writes SQLite, bumps a monotonic revision, and pushes a signed bundle to every open agent stream in ~50 ms. Agents reconcile every 15 s as a safety net. Updates are idempotent by revision — replay and reorder are free.
What these docs are not. These pages cover the operator surface — install, run, secure. For internal architecture and the per-RPC API specification, the canonical sources are PRD-v3.md, PRD-API.md, PRD-DB.md, and PRD-UI.md in the source tree. We link out to the relevant section where it helps.
Versions covered
These docs target v3.0.0-rc.1, the first public release candidate. Behaviour is frozen at this version; subsequent patch releases that change CLI flags, defaults, or output shape are tracked in the changelog and reflected here in the same patch. If a CLI command in these docs disagrees with the binary you're running, the binary is authoritative — please file an issue.