Skip to content
Tyr

Development

Getting started

Terminal window
git clone https://github.com/terranchi/tyr.git
cd tyr

Prerequisites

  • Rust 1.90+ (via rustup)
  • protoc — protocol buffer compiler
  • PostgreSQL 14+ (locally or via Docker)
  • pnpm 9+ and Node 22+ — for the web UI
  • Docker — for compose stacks and CI parity

macOS:

Terminal window
brew install rustup protobuf pnpm postgresql@17

Ubuntu:

Terminal window
sudo apt install protobuf-compiler postgresql
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
curl -fsSL https://get.pnpm.io/install.sh | sh -

Workspace layout

crates/
├── tyr-agent/     # tyrd — eBPF agent (Linux-only build target for agent code)
├── tyr-cli/       # tyr   — admin CLI
├── tyr-common/    # shared types, policy compiler, Cedar bindings
└── tyr-server/    # tyr-server — control plane


proto/             # .proto files for gRPC
web/               # Svelte 5 dashboard (pnpm workspace)
examples/policies/ # Starter policies
deploy/            # Docker + docker-compose
docs/adr/          # Architecture decision records
docs-site/         # This documentation site (Astro Starlight)

Build

Terminal window
cargo build --workspace                  # all crates
cargo build --release -p tyr-server      # just the server
cd web && pnpm install && pnpm build     # web UI

Test

Tests require PostgreSQL. Quickest setup:

Terminal window
docker compose -f deploy/docker-compose.dev.yml up -d postgres
DATABASE_URL=postgres://tyr:tyr-dev-password@localhost:5432/tyr \
  cargo test --workspace

Or use the repo’s rtk wrapper script (sources env automatically).

Running one crate’s tests

Terminal window
DATABASE_URL=... cargo test -p tyr-server

Coverage

Terminal window
cargo install cargo-llvm-cov
DATABASE_URL=... cargo llvm-cov --workspace --lcov --output-path lcov.info

Pre-commit hook enforces ≥75% line coverage per crate.

Lint

Terminal window
cargo fmt --all -- --check
cargo clippy --workspace --all-targets -- -D warnings

Both run in CI and as pre-commit hooks. Run them locally before pushing.

Running locally end-to-end

Terminal window
# Start Postgres
docker compose -f deploy/docker-compose.dev.yml up -d postgres


# Server (terminal 1)
DATABASE_URL=postgres://tyr:tyr-dev-password@localhost:5432/tyr \
TYR_WEB_DIR=web/build \
TYR_REST_NO_TLS=true \
cargo run -p tyr-server


# Web UI dev server (terminal 2, for HMR)
cd web && pnpm dev


# Agent (terminal 3) — Linux-only
sudo -E cargo run -p tyr-agent -- \
  --server http://localhost:7700 \
  --name dev-laptop


# CLI
cargo run -p tyr-cli -- --server http://localhost:7701 agent list

Protocol buffers

When editing .proto files:

Terminal window
# the build.rs auto-regenerates; just rebuild
cargo build -p tyr-common

Architecture decision records

Major decisions live in docs/adr/:

Before major features, write a new ADR under docs/adr/. Propose via PR for discussion.

Commit style

  • Conventional-ish: prefer feat:, fix:, docs:, refactor:, test:, chore:.
  • One logical change per commit.
  • Tests accompany feature commits.

Pull requests

  • Open against main.
  • CI must be green — fmt, clippy, tests, coverage, docs build.
  • For breaking changes, update the CHANGELOG and note in PR description.

→ Next: ADRs · Releases