> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hexgate.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Audit log (ClickHouse)

> Policy decisions persisted for the audit dashboard.

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](/platform/hosted) this is fully managed — nothing to run. For
the conceptual overview see [audit trail](/concepts/audit-trail); for the
engineering spec see [internals/audit-pipeline](/internals/audit-pipeline).

```bash theme={null}
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`.

<Note>
  **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.
</Note>

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:

```bash theme={null}
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

```bash theme={null}
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.