tyr-server

tyr-server is the central control plane. It exposes REST (:7701) and gRPC (:7700), uses PostgreSQL for state, and serves the web UI.

Ports

Port	Protocol	Purpose
7700	gRPC	Agents only. mTLS with client certs.
7701	REST / HTTP	Admin UI, CLI, SSE event stream. JWT-authenticated.

Environment variables

Env	Required	Default	Description
DATABASE_URL	yes	—	PostgreSQL connection string
TYR_WEB_DIR	no	/usr/share/tyr/web	Path to built Svelte UI assets
TYR_REST_NO_TLS	no	false	Disable TLS on REST (use behind a TLS-terminating proxy)
TYR_DATA_DIR	no	/var/lib/tyr	Server data dir for CA key material
TYR_BOOTSTRAP_ENROLLMENT_TOKEN	no	—	Pre-seed a known enrollment token (for quickstart)
RUST_LOG	no	info	Log level
TYR_REST_BIND	no	0.0.0.0:7701	REST bind address
TYR_GRPC_BIND	no	0.0.0.0:7700	gRPC bind address

PKI

On first boot, if $TYR_DATA_DIR/ca.key doesn’t exist, the server generates a root CA. Every enrolled agent receives a client certificate signed by this CA. Public cert is downloadable at /api/v1/ca.pem.

curl -sSL https://tyr.example.com:7701/api/v1/ca.pem -o ca.pem

Back this up. Losing ca.key means all agents must re-enroll.

Database

• PostgreSQL 14+ required (tested on 17).
• Migrations run automatically on startup from crates/tyr-server/migrations/.
• Recommended sizing: 2 vCPU / 4 GiB RAM / SSD for ~1000 agents and 30 days of events.

Health

GET /health

Returns 200 OK with a JSON body { "status": "ok", "db": "ok", "version": "0.5.2" }.

Use this for load balancer health checks and readiness probes.

Startup behaviors

• On boot: connects to Postgres, runs migrations, loads CA keys, loads latest policy versions into the in-memory engine, binds ports.
• On SIGTERM: drains in-flight SSE clients, flushes event buffers, closes DB pool. Graceful shutdown within 10s.
• On database unavailable: exits with code 1. Run behind a supervisor with restart.

Running without TLS

For local dev or behind a TLS-terminating proxy:

TYR_REST_NO_TLS=true tyr-server

Never expose a TYR_REST_NO_TLS=true server directly to the internet — the JWT is sent in the clear.

Web UI

The server serves $TYR_WEB_DIR as static assets at /. Requests to /api/* route to the REST handlers. The first-run setup flow lives at /setup and redirects to the login page once an admin account is created.

Logs

Stderr by default. Structured tracing in JSON with RUST_LOG=tyr_server=info,sqlx=warn.

Metrics (roadmap)

A /metrics Prometheus endpoint is planned. Today, rely on PostgreSQL metrics, agent heartbeats, and logs.

→ Next: REST API · gRPC API · Environment variables