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 Controller with optional remote data planes.
Start here
If you've never run Tiyi before, follow Quickstart, Installation, then Operations. They leave you with a real WAF in front of a real upstream and a repeatable investigation workflow.
Install the signed binary, start tiyi run, create your first site, and watch the WAF block real attacks. Five minutes.
Install a signed release, configure the YAML config, and run the Controller or enroll remote Agents.
Back up, completely uninstall v3.4.0 or earlier, install a clean v3.5.3 service, and re-enroll Agents.
Sites, upstream pools, certificates, WAF policies, agents, telemetry, and the audit chain — what each one is and how they fit together.
Publish an application, read exact counters and evidence, investigate SecurityFacts and attack logs, tune safely, and operate Agents.
Diagnose startup, login, routing, TLS, WAF, agent, and observation-pipeline problems from the outside in.
Current v3.5.3 commands grouped by resource, with safe examples and a reminder to check each command's built-in help.
The ConnectRPC contract that drives the UI, CLI, and agent stream: authentication, errors, and the current service catalog.
Production hardening, remote-Agent continuity and Controller outage boundaries, 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. - Local first, remote when needed. The built-in local data plane applies in-process. Remote Agents hold one long-lived ConnectRPC stream to the Controller, verify signed bundles, reconcile after reconnect, and continue serving the last accepted bundle during a Controller outage.
What these docs are not. These pages cover the operator surface — install, run, secure. The installed binary exposes the API contract; implementation details that are not needed for operations stay out of the public docs.
Versions covered
These docs target v3.5.3, the current public release. Replacing v3.4.0 or any earlier installation requires a verified backup, complete purge, clean v3.5.3 service install, and Agent re-enrollment; see the v3.5.3 upgrade guide. Changes to CLI flags, defaults, or output shape are tracked in the changelog. If an example disagrees with the installed binary, tiyi <command> --help is authoritative.