Tiyi documentation
Run Tiyi between visitors and your application to protect websites and APIs. Start with installation, login, and your first site, then move to production traffic, protection tuning, automation, and daily operations.
Start here
If you've never run Tiyi before, follow Quickstart. Install, sign in, create one site, and watch the WAF block real attacks. Then continue with Practice and advanced use, or connect your application with the Operations guide.
Install the signed binary, start the systemd service, create your first site, and watch the WAF block real attacks. Five minutes.
One-line installation, manual steps, custom ports, offline setup, configuration, and service management.
Check the backup, fresh-state and remote-Agent re-enrollment requirements before upgrading.
Sites, upstream pools, certificates, WAF policies, agents, telemetry, and the audit chain — what each one is and how they fit together.
Connect a real application, inspect traffic and logs, investigate blocks, tune policies, configure alerts, and manage nodes.
Keep using the demo site to explore observe/block modes, rule tuning, API protection, automation, and recovery.
Rehearse Nginx integration, inspect real WAF blocks, tune a scoped exception and restore the original route, with tested commands and screenshots.
Configure security-threshold alerts, global IP blocking and fixed expiry, then verify results and remove blocks.
Diagnose startup, login, routing, TLS, WAF, agent, and observation-pipeline problems from the outside in.
Current 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.
Complete startup and resource YAML with downloads, apply steps and verification.
Portable site bundles, conflict handling, certificate choices and rollback.
API discovery, document import, JSON learning, request validation and file requirements.
Configure block pages, response statuses and API error formats.
Look up RPCs, fields, permissions and CLI flags.
New capabilities, boundaries and backup/migration requirements before upgrading.
Install the operator skill to complete authorized tasks through supported Tiyi interfaces.
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. ConnectRPC owns authenticated mutations while the UI and CLI remain clients.
tiyi apply -f site.yamladds a strict, transactional desired-state path for its supported resource fields, with the same durable store and audit chain. - 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 track the current release. Use upgrade and migration before replacing a binary or moving state. Changes to user-facing behavior are tracked in the changelog. If an example disagrees with the installed binary, tiyi <command> --help is authoritative.
Templates and full reference
Startup tiyi.yaml · Minimal site YAML · Four-kind YAML · Site import JSON · OpenAPI YAML · Local demo API · Protection response JSON.
All RPCs · Permissions · All CLI flags.
Upgrading an existing installation to v3.8.0 requires backup, fresh state, and re-enrollment of all remote Agents. Read the v3.8.0 notes and migration procedure before replacing the binary and restarting. History: v3.7.2 · v3.7.1 · v3.7.0.