Read logs and audit trails

Agent Guard writes three log files. Each captures a different layer of what happened during a run.

File	What it contains	Path
Policy audit log	Every policy decision for every tool call (allow, deny, audit, elicit). JSONL, one record per line.	~/Library/Logs/AgentGuard/policy_audit.jsonl
Policy server log	Operational log for the in-VM Agent Guard AI Gateway: startup, policy loads, evaluation errors. Plain text.	~/Library/Logs/AgentGuard/policy_server.log
MicroVM serial console	Guest boot output and any kernel-level messages from inside the microVM. Plain text.	~/.agentguard/vm/serial.log

The audit log is the file that matters most. It is the single source of truth for what your agent tried to do and what Agent Guard decided about each call.

Tailing logs

agentguard logs

Tails the audit log and the policy server log together, formatted for terminal reading. Useful while iterating on a policy: run the agent in one terminal, tail logs in another, watch decisions stream in.

To watch just the audit log:

tail -f ~/Library/Logs/AgentGuard/policy_audit.jsonl

agentguard logs does not cover the serial log because it lives outside the audit log directory. To watch it directly when the microVM is having trouble booting:

tail -f ~/.agentguard/vm/serial.log

To correlate policy decisions with microVM resource pressure, run agentguard top in one terminal and tail the audit log in another:

tail -f ~/Library/Logs/AgentGuard/policy_audit.jsonl | jq -c '{ts: .timestamp, tool: .tool, action: .action, rule: .rule}'

What the audit log records

Each line in policy_audit.jsonl is a single tool call decision. The record captures the timestamp, the agent that issued the call, the tool name, the tool arguments, the policy decision (allow, deny, audit, or elicit), and the rule that matched if any.

Records are appended in real time as the agent makes tool calls. Multiple sessions writing concurrently are merged into the same file when the microVM exits, so the file is the consolidated view across every run.

Querying the audit log with jq

JSONL works well with jq. A few queries that come up regularly.

Every deny in the last run:

tail -50 ~/Library/Logs/AgentGuard/policy_audit.jsonl | jq 'select(.action == "deny")'

Count decisions by action:

jq -s 'group_by(.action) | map({action: .[0].action, count: length})' \
  ~/Library/Logs/AgentGuard/policy_audit.jsonl

Every Bash command the agent tried during a specific run (replace the timestamp with one near the run):

jq 'select(.tool == "Bash" and .timestamp > "2026-05-21T14:00:00Z")' \
  ~/Library/Logs/AgentGuard/policy_audit.jsonl

Which rules fired most often (good for tuning policies that fire too aggressively):

jq -s 'map(select(.rule != null)) | group_by(.rule) | map({rule: .[0].rule, count: length}) | sort_by(.count) | reverse' \
  ~/Library/Logs/AgentGuard/policy_audit.jsonl

Log retention

Agent Guard appends to the audit log indefinitely. There is no built-in rotation today. For long-running developer workstations the file grows slowly enough that this is fine. For shared CI runners or machines running many agent sessions per day, rotate the log yourself:

# Move the current log aside, gzip it, start fresh
cd ~/Library/Logs/AgentGuard/
mv policy_audit.jsonl policy_audit.$(date +%Y%m%d).jsonl
gzip policy_audit.*.jsonl

If you have a log aggregation tool (Splunk, Datadog, Sumo, OpenSearch), point it at the audit log path and let it handle rotation and retention.

Forwarding to a centralized audit repository

If Agent Guard is configured with a Hub, audit records sync to the Hub-side audit repository on a recurring schedule, independent of when any individual microVM session exits. Records that fail to sync (network unavailable, Hub down) stay in the local file and are retried on the next scheduled attempt. The local file is the authoritative copy regardless.

For air-gapped environments where Agent Guard runs without any Hub connectivity, export the JSONL file as part of your existing audit collection process.

Why the audit log is protected

The agent cannot reach the audit log from inside its sandbox, and every record carries a hash of the prior record so tampering is detectable on review. See Threat model for the protection guarantees in detail.

One thing specific to this file: agentguard uninstall does not delete ~/Library/Logs/AgentGuard/. The audit trail survives reinstall and is available for forensic review of a compromised machine. To wipe it, delete the directory manually.

Reading the microVM serial log

The serial log is useful for diagnosing microVM boot problems specifically. If the microVM fails to start, the kernel boot output here usually says why.

cat ~/.agentguard/vm/serial.log

Common patterns to look for: filesystem mount failures, DHCP timeouts, init binary crashes. None of these are application-level problems with your agent or policies, so the serial log is mostly relevant when reporting a bug to Agent Guard or when something has gone wrong below the agent layer.