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                      # Extracted gerty-bifrost macOS binary
├── 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       # Gerty-bifrost binary transferred into 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 auth, sync config
├── state.json                     # Hook/agent installation state
└── home-staging/                  # Temporary credential staging (cleaned per-run)

To move the state directory (CI machine, shared dev server, custom layout), set AGENTGUARD_HOME:

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

Every command honors the override. Nothing is written outside the configured directory except the audit log (see below).

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	Used as the Claude Code credential when no OAuth token is cached.
GEMINI_API_KEY	unset	Used as the Gemini CLI credential when no OAuth token is cached.
OPENAI_API_KEY	unset	Used as the Codex CLI credential when no OAuth token is cached.
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. They are never written to disk on the host or 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-gemini-credentials	Gemini CLI OAuth token cached across microVM environments.
vm-codex-credentials	Codex CLI auth token cached across microVM environments.

Registry credentials supplied via agentguard policy add -u <user> -p <token> are also stored in the Keychain. The exact account format is internal.

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. Paths are not configurable today.

File	Purpose	Path
Policy audit log	Every policy decision. JSONL, one record per line.	~/Library/Logs/AgentGuard/policy_audit.jsonl
Policy server log	In-VM Agent Guard AI Gateway operational log. Plain text.	~/Library/Logs/AgentGuard/policy_server.log
MicroVM serial console	Guest boot output and kernel messages. Plain text.	~/.agentguard/vm/serial.log

The audit log lives under ~/Library/Logs/AgentGuard/ rather than the state directory because it survives uninstall. 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.