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.<session>.jsonl
Policy server log	Operational log for the Jozu AI Gateway inside the microVM: startup, policy loads, evaluation errors. Plain text.	~/Library/Logs/AgentGuard/policy_server.<session>.log
MicroVM serial console	Guest boot output and any kernel-level messages from inside the microVM. Plain text.	~/.agentguard/vm/serial.log

With AGENTGUARD_HOME set, the audit and server logs are written to $AGENTGUARD_HOME/logs/, and the serial log to $AGENTGUARD_HOME/vm/serial.log.

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

Tailing logs

agentguard logs

Tails the most recent session's audit log and policy server log, and the serial log, together, formatted for terminal reading. The audit and server logs it follows are the newest when it starts, so restart it after starting a new run; the serial log follows across sessions on its own. --no-serial hides the serial log, and --guardrails shows only GuardrailPolicy decisions. Run the agent in one terminal and agentguard logs in another to watch decisions as they are made.

To watch just the most recent audit log:

tail -f "$(ls -t ~/Library/Logs/AgentGuard/policy_audit.*.jsonl | head -1)"

Each boot starts a fresh serial log. The previous session's is kept as serial.log.1, the one before as serial.log.2, and so on; agentguard logs -p 1 prints the previous one.

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

tail -f "$(ls -t ~/Library/Logs/AgentGuard/policy_audit.*.jsonl | head -1)" | jq -c '{ts: .timestamp, tool: .tool, action: .action, rule: .rule}'

What the audit log records

Each line in an audit log 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. Each session writes its own file, so concurrent runs do not interleave. To look across runs, read every file: cat ~/Library/Logs/AgentGuard/policy_audit.*.jsonl.

Log retention

Agent Guard does not prune audit logs, server logs, or rotated serial logs: each session adds files that stay until you remove them. On a machine that runs many sessions, archive older sessions yourself:

# Compress audit and server logs older than 30 days
find ~/Library/Logs/AgentGuard/ -name 'policy_*' -mtime +30 ! -name '*.gz' -exec gzip {} +

If you have a log aggregation tool (Splunk, Datadog, Sumo, OpenSearch), point it at ~/Library/Logs/AgentGuard/policy_audit.*.jsonl and let it handle 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 files are the authoritative copy regardless.

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

Why the audit log is protected

The agent cannot reach the audit log from inside the microVM, 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.

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.