Audit & Observability

InitRunner automatically logs every agent run to a local SQLite database. Audit records capture what happened, how much it cost, and whether it succeeded — giving you full observability into agent behavior.

What Gets Logged

Every agent run produces an audit record with these fields:

Field	Type	Description
`run_id`	`str`	Unique run identifier (12-character hex)
`agent_name`	`str`	Name from `metadata.name`
`timestamp`	`datetime`	UTC timestamp of run start
`prompt`	`str`	Input prompt (subject to redaction)
`output`	`str`	Agent output (subject to redaction)
`tokens_in`	`int`	Input tokens consumed
`tokens_out`	`int`	Output tokens consumed
`tool_calls`	`list`	Tool invocations with name, args, and result
`duration_ms`	`int`	Wall-clock duration in milliseconds
`success`	`bool`	Whether the run completed without error
`error`	`str \| null`	Error message if the run failed
`trigger_type`	`str`	How the run was initiated: `prompt`, `cron`, `file_watch`, `webhook`, `autonomous`

Storage

Audit records are stored in a SQLite database:

Default path: ~/.initrunner/audit.db
Custom path: --audit-db ./custom-audit.db
Disable entirely: --no-audit

# Default audit database
initrunner run role.yaml -p "Hello"

# Custom audit database path
initrunner run role.yaml -p "Hello" --audit-db ./my-audit.db

# Disable audit logging
initrunner run role.yaml -p "Hello" --no-audit

The same flags work with initrunner daemon and initrunner serve.

Export

Export audit records as JSON or CSV for analysis, reporting, or ingestion into external systems.

initrunner audit export

Flag	Type	Default	Description
`--agent`	`str`	(all)	Filter by agent name
`--trigger-type`	`str`	(all)	Filter by trigger type (`prompt`, `cron`, `file_watch`, `webhook`, `autonomous`)
`--since`	`str`	(none)	Start date (ISO 8601, e.g. `2025-01-01`)
`--until`	`str`	(none)	End date (ISO 8601)
`--limit`	`int`	`1000`	Maximum records to export
`-f, --format`	`str`	`"json"`	Output format: `json` or `csv`
`-o, --output`	`str`	stdout	Output file path

Examples

# Export all records as JSON
initrunner audit export

# Export last 7 days for a specific agent as CSV
initrunner audit export --agent monitor-agent --since 2025-01-08 -f csv -o report.csv

# Export only cron-triggered runs
initrunner audit export --trigger-type cron --limit 500

# Export to a file
initrunner audit export -o audit-export.json

Pruning

Remove old audit records to manage database size.

Manual Pruning

initrunner audit prune
initrunner audit prune --retention-days 30 --max-records 50000

Flag	Type	Default	Description
`--retention-days`	`int`	`90`	Delete records older than this
`--max-records`	`int`	`100000`	Keep at most this many records (oldest removed first)

Automatic Pruning

Configure auto-pruning via the security policy in your role YAML:

security:
  audit:
    retention_days: 30
    max_records: 50000

Field	Type	Default	Description
`retention_days`	`int`	`90`	Delete records older than this many days
`max_records`	`int`	`100000`	Maximum audit records to retain

Auto-pruning runs at daemon startup and periodically during long-running daemons.

Redaction

Audit logs can contain sensitive information. InitRunner supports two redaction mechanisms to sanitize records before they are written.

PII Redaction

Enable built-in PII pattern detection:

security:
  content:
    pii_redaction: true

This redacts common PII patterns in both prompts and outputs before writing to the audit database:

Pattern	Example	Redacted As
Email addresses	`user@example.com`	`[EMAIL]`
Social Security Numbers	`123-45-6789`	`[SSN]`
Phone numbers	`+1-555-123-4567`	`[PHONE]`
API keys	`sk-abc123...`	`[API_KEY]`

Custom Redaction Patterns

Add regex patterns to redact domain-specific sensitive data:

security:
  content:
    redact_patterns:
      - "\\b[A-Z]{2}\\d{6}\\b"        # internal account IDs
      - "\\btoken_[a-zA-Z0-9]+\\b"     # internal tokens

Custom patterns are applied in addition to PII redaction (if enabled). Matches are replaced with [REDACTED].

Viewing Audit Logs

Beyond the CLI export command, audit logs are accessible through:

TUI — the Audit panel provides a scrollable, filterable log viewer
Web Dashboard — the Audit Viewer offers search, pagination, and CSV/JSON export
Direct SQLite access — query ~/.initrunner/audit.db with any SQLite client

# Quick peek at recent records
sqlite3 ~/.initrunner/audit.db "SELECT agent_name, trigger_type, success, duration_ms FROM audit ORDER BY timestamp DESC LIMIT 10"

On this page