Configuration reference

Agent Guard's runtime configuration lives in three places: a state directory on disk, the macOS Keychain, and environment variables. This page describes each and how they interact. Day-to-day, you do not edit any of these files directly; Agent Guard's commands (policy add, trusted-keys add, etc.) manage them for you.

State directory

~/.agentguard/
├── bin/
│   └── gerty                      # Policy engine, extracted for the host
├── vm/
│   ├── Image                      # Decompressed Linux kernel
│   ├── initrd-ag.cpio.gz          # Init ramdisk
│   ├── rootfs.img                 # Debian rootfs (~500 MB, extracted from the binary on first run)
│   ├── rootfs.version             # Version tag of cached rootfs
│   ├── serial.log                 # Last microVM session serial output
│   ├── gerty-linux-arm64.gz       # Policy engine transferred into the microVM
│   ├── agentguard-linux-arm64.gz  # Agent Guard hook handler transferred into microVM
│   ├── claude-<version>           # Cached agent binary
│   ├── claude-<version>.gz        # Pre-compressed copy for fast vsock transfer
│   ├── checksums.json             # TOFU checksum cache for agent binaries
│   └── environments/              # Per-agent named environments
│       └── <agent>-<hash>/        #   Overlay subdirs: root, usr-local, opt, home
├── policies/
│   ├── global/                    # Global policies (always active)
│   │   └── <sanitized-ref>/
│   └── workspaces/                # Workspace-scoped policies
│       └── <path-hash>/
│           └── <sanitized-ref>/
├── sessions/                      # Running microVM session metadata (<pid>.json)
├── config.json                    # Policy sources, registry hosts, sync config
├── state.json                     # Hook/agent installation state
└── home-staging-*/                # Temporary credential staging, removed when the run ends

To move the state directory, set AGENTGUARD_HOME:

export AGENTGUARD_HOME=/opt/agentguard
agentguard policy add jozu.ml/jozu/agentguard-policies:vm-standard

Every command honors the override, including for logs: with AGENTGUARD_HOME set, the audit and server logs are written to $AGENTGUARD_HOME/logs/ instead of ~/Library/Logs/AgentGuard/, so they are removed on uninstall with the rest of that directory. Credentials cached in the macOS Keychain and ModelKits in the kit CLI's local store are not under the state directory either way.

config.json

Holds the configured policy sources, the registry hosts they came from, and sync state. Agent Guard manages this file through policy add and policy remove. Manual edits are not supported in v1; use the CLI.

To inspect what is currently configured:

agentguard policy list
agentguard trusted-keys list
agentguard status

These three cover what you would otherwise read from config.json directly.

Environment variables

Variable	Default	What it does
AGENTGUARD_HOME	~/.agentguard	Override the state directory.
AGENTGUARD_NO_SYNC	unset	When set to 1, disables policy sync on every run.
ANTHROPIC_API_KEY	unset	Credential for Claude Code and OpenClaw. When set, Claude Code uses it instead of a cached OAuth token.
OPENAI_API_KEY	unset	Credential for Codex CLI. When set, it is used instead of cached or host credentials.
HTTPS_PROXY / HTTP_PROXY / NO_PROXY	unset	Honored for outbound registry connections and propagated into the microVM.

Variables passed with --pass-env <KEY> or --pass-cloud-creds <provider> are transferred to the microVM in memory over vsock; Agent Guard does not write their values to disk on the host. A credential file that a --pass-cloud-creds variable points at is the exception: it is copied to a staging directory under the state directory for the length of the run and removed when the run ends. Neither is persisted in the microVM overlay. See Pass credentials into the microVM.

macOS Keychain

Agent Guard caches secrets in the Keychain under the service AgentGuard.

Account	What it holds
vm-claude-code-credentials	Claude Code OAuth token cached across microVM environments.
vm-codex-credentials	Codex CLI auth token cached across microVM environments.
vm-antigravity-credentials	Antigravity CLI session cached across microVM environments.

Registry credentials supplied via agentguard policy add -u <user> -p <token> are not stored in the Keychain. They go to the kit CLI's credential store, the same one kit login writes.

View an entry with security:

security find-generic-password -s AgentGuard -a vm-claude-code-credentials -w

Delete an entry to force re-authentication on next run:

security delete-generic-password -s AgentGuard -a vm-claude-code-credentials

agentguard uninstall removes every entry under the AgentGuard service unless --keep-config is passed.

Log paths

Agent Guard writes three log files. The paths below are the defaults; AGENTGUARD_HOME moves all three (see State directory).

File	Purpose	Path
Policy audit log	Every policy decision. JSONL, one record per line.	~/Library/Logs/AgentGuard/policy_audit.<session>.jsonl
Policy server log	Operational log of the Jozu AI Gateway inside the microVM. Plain text.	~/Library/Logs/AgentGuard/policy_server.<session>.log
MicroVM serial console	Guest boot output and kernel messages. Plain text.	~/.agentguard/vm/serial.log

By default the audit and server logs live under ~/Library/Logs/AgentGuard/ rather than the state directory, so that they survive uninstall. Each session writes its own files, named after the session. See Read logs and audit trails for the reasoning.

Registry configuration

Agent Guard talks to OCI-compliant registries for two things: pulling policy artifacts (agentguard policy add) and pulling agent definitions (agentguard run --agent-ref).

The registry host is captured the first time you reference it and reused on subsequent syncs. To talk to a private registry, pass -u and -p on policy add:

agentguard policy add hub.acme.com/sec-team/policies:v3 \
  -u deploy-bot \
  -p "$REGISTRY_TOKEN"

For registries that only serve plain HTTP (internal mirrors, air-gapped setups), add --plain-http. Plain HTTP is not the default for security reasons.

Resource configuration

Property	Default	Override
MicroVM RAM	3072 MiB	--ram <MiB> on agentguard run
Rootfs cache	~/.agentguard/vm/rootfs.img	Set via AGENTGUARD_HOME

If 3GB RAM is too much for a constrained machine, lower with --ram 2048. Below 2GB, package installs (apt-get, npm install of large packages) will OOM.