Operations Runbook¶

This runbook covers the free, local-first operating path first. Optional production components are documented separately and should only be enabled when a user chooses to run them.

Local Operating Mode¶

Start the local demo:

make demo-local

Start from source with the mock provider:

make build
./bin/aegisflow --config examples/configs/single-tenant.yaml

Verify health:

curl -fsS http://localhost:8080/health
curl -fsS http://localhost:8081/health

Verify a mock chat request:

./examples/requests/openai-compatible-curl.sh

Cost-Free Defaults¶

The default local path uses:

mock provider
YAML policies
in-memory rate limiting
local audit/evidence chain
Prometheus metrics on the admin port
Docker Compose for local services

Real providers, hosted tracing, Redis, PostgreSQL, Kubernetes, and external policy engines are optional.

Metrics¶

Prometheus metrics are available on the admin port:

curl -fsS http://localhost:8081/metrics | grep '^aegisflow_'

Recommended local checks:

aegisflow_requests_total
aegisflow_request_duration_seconds

See observability.md for the included Prometheus scrape config and Grafana dashboard JSON.

Audit And Evidence¶

Verify the audit chain:

curl -fsS -X POST http://localhost:8081/admin/v1/audit/verify \
  -H "X-API-Key: demo-key-001"

List evidence sessions:

curl -fsS http://localhost:8081/admin/v1/evidence/sessions \
  -H "X-API-Key: demo-key-001"

Export a session:

./bin/aegisctl evidence export <session-id> --file evidence.json
./bin/aegisctl evidence report <session-id> --file evidence.md

Built-In Snapshot Backups¶

When resilience.enabled is true, the admin API can create and list local JSON snapshots. This is useful for lightweight local state capture.

Enable resilience with a config such as configs/resilience-example.yaml, then create a snapshot:

curl -fsS -X POST http://localhost:8081/admin/v1/resilience/backup \
  -H "X-API-Key: demo-key-001"

List snapshots:

curl -fsS http://localhost:8081/admin/v1/resilience/backups \
  -H "X-API-Key: demo-key-001"

Snapshots are stored under the configured resilience.backup_dir.

PostgreSQL Backup¶

PostgreSQL remains optional for audit and usage records. Approval and signed evidence state can use local SQLite through state.enabled. Back up SQLite only after stopping AegisFlow or through SQLite-aware snapshot tooling. Copying live database file without WAL files can produce incomplete backup.

Create a dump from the Docker Compose database:

docker compose -f deployments/docker-compose.yaml exec postgres \
  pg_dump -U aegisflow -d aegisflow -Fc -f /tmp/aegisflow.dump

docker compose -f deployments/docker-compose.yaml cp \
  postgres:/tmp/aegisflow.dump ./aegisflow.dump

Restore into a fresh local database:

docker compose -f deployments/docker-compose.yaml cp \
  ./aegisflow.dump postgres:/tmp/aegisflow.dump

docker compose -f deployments/docker-compose.yaml exec postgres \
  pg_restore -U aegisflow -d aegisflow --clean --if-exists /tmp/aegisflow.dump

After restore:

curl -fsS -X POST http://localhost:8081/admin/v1/audit/verify \
  -H "X-API-Key: demo-key-001"

Incident Response¶

If a policy allows something unexpected:

Stop the local stack or remove gateway ingress.
Export audit and evidence records.
Verify the audit/evidence chain.
Tighten the relevant YAML policy.
Add or update a regression example.
Restart with the updated config and replay the blocked request.

Upgrade Checks¶

Before upgrading:

make fmt-check
go test ./... -race -count=1
go run golang.org/x/vuln/cmd/govulncheck@latest ./...
bash scripts/compose_smoke.sh

After upgrading:

curl -fsS http://localhost:8080/health
curl -fsS http://localhost:8081/metrics | grep '^aegisflow_'