Audit log (ClickHouse)

When you self-host, policy decisions are written to a ClickHouse instance backing the audit dashboard. The commands below start a local one via Docker for dev and self-hosting; in production, point the platform at your own ClickHouse cluster. On Hexgate Cloud this is fully managed — nothing to run. For the conceptual overview see audit trail; for the engineering spec see internals/audit-pipeline.

make clickhouse-up        # start the server (first run also creates the schema)
make clickhouse-cli       # interactive SQL shell
make clickhouse-down      # stop (keeps data)
make clickhouse-reset     # wipe and recreate (also re-applies the schema)

Schema lives in platform/clickhouse/init/schema.sql.

Schema init runs once. The Docker image applies init/schema.sql exactly once, on first container start with an empty data volume — editing the SQL afterwards is ignored on existing environments. To apply a schema change, either make clickhouse-reset (wipes data) or connect with make clickhouse-cli and run the migration SQL by hand. In production, treat schema changes as a deliberate maintenance step against your ClickHouse cluster.

The service binds to 127.0.0.1 only, on host ports 8124 (HTTP) and 9001 (native) rather than ClickHouse’s default 8123/9000, so it coexists with any other local ClickHouse instance (e.g. a Langfuse-bundled one).

Ingest endpoint

Once both make clickhouse-up and make platform-api are running, the ingest endpoint POST /v1/audit/decisions accepts one decision per request:

curl -X POST localhost:8000/v1/audit/decisions \
  -H "Authorization: Bearer fty_test_..." \
  -H "Content-Type: application/json" \
  -d '{"event_id":"9f1e3c5a-4d2b-4b8e-9c8a-1f4e2d8a7c3b",
       "occurred_at":"2026-05-29T14:00:00Z",
       "agent_name":"example_agent","tool_name":"read_file","outcome":"deny"}'
# → 202 {"event_id":"9f1e3c5a-..."}

Integration tests (pytest -m integration) round-trip rows through the live ClickHouse — opt-in so the default make platform-api-test stays offline-friendly.

Seed data

make seed-audit         # insert 820 rows of mock audit data
make seed-audit-clear   # delete seed rows

Inserts 800 normal rows spread over 30 days (Alice, Bob, Charlie across all tools) plus 20 anomaly rows where Bob probes restricted tools (refund_customer, create_ticket) with a default role in a 5-minute window 10 days ago.

Platform

Self-hosting

Audit log (ClickHouse)

Ingest endpoint

Seed data

​Ingest endpoint

​Seed data

Ingest endpoint

Seed data