The Audit Log Every AI Agent Needs

The first time you let an AI agent loose, you don't know what to log. The fifth time, you wish you'd been logging. The fiftieth time, an agent does something weird and you go looking for the log and the log is incomplete and you can't tell what happened.

This post is the structure I converged on. It's small. It's been useful.

What goes in the log

Every action that the system would care about if subpoenaed. For an AI agent supervisor, that's:

• Agent created — name, command, owner, capabilities granted
• Agent spawned — pid, working directory, sandbox profile
• Sandbox block — kernel said no to file write outside workspace, etc.
• Capability granted — user explicitly added screen_capture to agent X
• Capability revoked — user removed it
• Permission asked — agent requested approval
• Permission decided — approved/denied, by whom, on what device
• Agent killed — by user / by ceiling / by machine reboot
• Agent exited — exit code, runtime
• Sandbox toggled OFF/ON — master switch event

Notably not in the log: every keystroke. Every model token. The 30-day SQLite history is for that. The audit log is for events with consequences.

The hash chain

Each row stores: payload + hash of (previous_hash || payload).

row[N].hash = sha256(row[N-1].hash || serialize(row[N].body))
row[0].hash = sha256("" || serialize(row[0].body))

Two properties:

• Tamper-evident. Editing any past row changes its hash, which breaks every subsequent hash. A verifier reading the chain top-to-bottom catches the break exactly at the modified row.
• Append-only by construction. You can't insert a row in the middle without knowing the next row's previous_hash field — and the next row's hash is downstream of the inserted row's payload, so you'd have to rewrite all subsequent rows.

Each row stores: seq, ts, actor (uid or "system"), action, target, body (action-specific JSON), prevHash, hash.

The verifier

A worker walks the chain hourly:

prev := ""
for seq := 0; seq < lastSeq; seq++ {
  row := getRow(seq)
  expected := sha256(prev || serialize(row.body))
  if expected != row.hash {
    alertVerificationFailed(seq)
    return
  }
  prev = row.hash
}
markVerifiedThrough(lastSeq, time.Now())

If verification fails, page someone. The 99.999% case is "everything is fine" but that's the case where the log is most useful for tomorrow's question.

Where the log lives

For Celistra: every row is a Firestore doc at audit/{seq}. The hourly verifier is a Cloud Function. The "view audit log" UI is an SSE stream from the daemon (live tail) plus a paginated query of older rows.

For self-hosted: the same code (@axy/audit-chain in TS, axy-audit-chain in Python) writes to whatever store you back it with — Firestore, Postgres, S3-versioned objects.

What this enables

"Did the agent really push to main?" Find rows where action=permission-asked + target=git-push + decided=approved. There's the row. There's who approved. There's when.

"When did the sandbox come down?" Find rows where action=sandbox-toggled. The most recent shows on/off and who flipped it.

"What capabilities did agent X have when it ran on Tuesday?" Find the spawn row for that agent on that date. The capabilities resolved at spawn time are in the body.

"How many block decisions has the sandbox made this week?" Count rows where action=sandbox-block. (Cheap on Firestore with a composite index on action + ts.)

What this doesn't enable

The log is a record of things the system did, not of things the agent's model thought. Internal model reasoning isn't logged. If you need that level, you're past audit and into observability — Langfuse, LangSmith, OpenLIT.

The log also doesn't replace privacy. PII in body stays there. If you can't afford to retain certain fields, redact at append time.

Why open-source the chain code

Because the value of an audit chain is the property "I can verify it." If only the vendor has the code, the vendor is also the only one who can verify. Open-source means anyone can verify the chain you exported. The TS lib is <200 LoC; the Python lib is <200 LoC. Both Apache-2.0.

What we ship

The Celistra daemon writes to a local audit log + the Firebase project's audit collection. The hourly verifier runs as a Cloud Function. The dashboard's "Activity" panel is an SSE stream from the daemon. The @axy/audit-chain library is the same code Ujex uses for its agent-infra audit trail.