tyrd (agent)

tyrd is the eBPF-powered agent. It runs on every host you want to govern.

Usage

tyrd --server <URL> --name <NAME> [FLAGS]

Flags

Flag	Env	Default	Description
`--server <URL>`	`TYR_SERVER`	required	gRPC URL of tyr-server (`http://…:7700` or `https://…:7700`)
`--name <NAME>`	`TYR_AGENT_NAME`	hostname	Human label for this daemon
`--enforce`	—	off	Turn on deny enforcement (audit-only otherwise)
`--tls-capture`	—	off	Attach uprobes to TLS libraries for SNI extraction
`--config <PATH>`	—	`/etc/tyr/tyrd.yaml`	Path to YAML config
`--data-dir <DIR>`	—	`/var/lib/tyr`	Where to store identity, cert, event buffer

Additional env vars:

Env	Description
`TYR_ENROLLMENT_TOKEN`	Bootstrap token for first-boot enrollment
`RUST_LOG`	Log level: `error`, `warn`, `info`, `debug`, `trace`

Config file

/etc/tyr/tyrd.yaml:

unregistered_agents: audit       # audit | quarantine | deny
heartbeat_interval_s: 30
buffer_size_mb: 500
debug_mode: false
enrollment_token: "tyr_et_..."
ca_cert_path: /etc/tyr/ca.pem
data_dir: /var/lib/tyr

Key	Default	Description
`unregistered_agents`	`audit`	Behavior for processes that don’t match a known agent_type
`heartbeat_interval_s`	`30`	gRPC heartbeat interval
`buffer_size_mb`	`500`	On-disk event buffer for offline periods
`debug_mode`	`false`	Verbose logging (equivalent to `RUST_LOG=debug`)
`enrollment_token`	—	Bootstrap token, consumed once
`ca_cert_path`	—	Server CA certificate path
`data_dir`	`/var/lib/tyr`	Agent state dir (cert, key, buffered events)

CLI flags override config file values. Config file values override defaults.

Required capabilities

On Linux:

CAP_BPF + CAP_SYS_ADMIN — attach eBPF programs.
CAP_NET_ADMIN — socket hooks.
CAP_PERFMON — perf ring buffer.
CAP_SYS_PTRACE — read /proc/<pid> for process enrichment.
CAP_SYS_RESOURCE — RLIMIT_MEMLOCK for BPF maps.

Running as root is simplest; AmbientCapabilities in the systemd unit is the cleanest alternative.

State on disk

/var/lib/tyr/:

├── identity.json         # agent_id, registered_at
├── client.key            # private key (0600)
├── client.crt            # client certificate
├── ca.pem                # server CA (also in /etc/tyr/)
└── events/               # on-disk buffer (offline storage)

Deleting this directory forces re-enrollment on next start.

Logs

Goes to stderr. In systemd: journalctl -u tyr-agent.

Key log events:

enrollment succeeded, agent_id=...
policy loaded, version=..., rules=...
lost connection to server, buffering events
reconnected, replayed N events
drift hit: kind=..., agent_verdict=..., server_verdict=... (only logged client-side if debug_mode)

Exit codes

Code	Meaning
0	Clean shutdown (SIGTERM)
1	Fatal startup error (can’t load BPF, bad config)
2	Enrollment failed
3	Kernel incompatible (missing LSM BPF)

→ Next: Configuration · Environment variables