FAQ

Common questions about Agent Guard, grouped by topic. For step-by-step walkthroughs see the rest of the docs; this page is the quick-lookup answer set.

Install and platform

Which platforms are supported today?

macOS on Apple Silicon (M1 or later). Linux and Windows support are on the roadmap. Intel Macs are not supported because Apple Virtualization.framework's behavior on Intel is materially different from Apple Silicon.

Do I need Docker?

No. Agent Guard uses Apple's native Virtualization.framework directly. You only need Docker if you are building Agent Guard from source and rebuilding the rootfs image.

How much disk space does Agent Guard need?

Plan for about 1GB on first install. The Agent Guard binary itself is roughly 500MB because it bundles the kernel, initrd, and the Debian rootfs together. On first run it extracts the rootfs to ~/.agentguard/vm/, which takes another ~500MB. Named environments grow over time as you install packages inside them; budget a few hundred MB per active environment.

Can I use Agent Guard offline?

Yes, after first install. The first agentguard run extracts the rootfs image from the binary (no network call), and agentguard policy add requires registry access to pull policies. After that, everything runs locally. Use --no-sync (or AGENTGUARD_NO_SYNC=1) to skip the per-run policy refresh when offline.

For fully air-gapped setups, also turn off Hub audit sync by setting hub.audit_sync to false in config.json.

Policies

What language do I write policies in?

YAML for the policy structure, CEL for the assertions inside rules. CEL is Google's expression language used by Kubernetes admission controllers and OPA Gatekeeper, among others.

How do I test a policy without publishing it?

Drop the YAML file in ~/.agentguard/policies/global/<source-name>/ (for global scope) or ~/.agentguard/policies/workspaces/<hash>/<source-name>/ (for workspace scope) and run the agent. Agent Guard re-parses every policy on every run, so there is no compile or reload step.

For workspace scope, the <hash> is the SHA-256 of the absolute workspace path. The easier path is to use agentguard policy add with a local kit ref.

Can I block specific MCP servers?

Yes. Use an ArtifactPolicy to gate which MCP servers can load into the runtime, and a ToolPolicy with tool.mcp_server in the match block to control individual tools exposed by a specific MCP server.

Why is my policy not firing?

Three things to check:

• The match block isn't matching. Add a temporary Audit rule with assert: "false" to see whether the policy is reached at all.
• The CEL expression is silently passing. Print the evaluation context by running with --verbose and watching the policy server log.
• The policy file is in the wrong location and Agent Guard isn't loading it. Confirm with agentguard policy list.

How do I roll back a bad policy?

If you published the bad policy as a tagged ref, push the previous version under a new tag and have developers policy remove the bad ref and policy add the good one. If the bad policy was published as a moving tag (:latest, :v3), republish the previous version under that tag and the next agentguard run syncs it automatically.

Agents

Which coding agents are supported?

Claude Code, Gemini CLI, Codex CLI, and OpenClaw. See Run an agent for the per-agent setup. Adding a new agent is a small amount of work; the runtime is agent-agnostic.

Does Agent Guard work with agents I write myself?

If your agent uses the hook protocol that Claude Code, Gemini, Codex, and OpenClaw use (tool calls evaluated against an HTTP policy endpoint), yes. Anything that wraps an LLM and exposes a tool-calling interface can be slotted into Agent Guard with a small adapter.

How does Agent Guard handle the agent's auth credentials?

OAuth tokens are cached in the macOS Keychain on the host under the service AgentGuard. On microVM boot, the relevant token is staged into the microVM in memory over vsock. Session data (conversation history, telemetry) is not copied into the microVM and is not persisted on the host outside the Keychain entries. See Pass credentials into the microVM for the full credential flow.

Performance

How long does a microVM boot take?

About 1 second on M1 or newer. The first agentguard run is slower because it extracts the rootfs image from the binary (~500MB) and decompresses the kernel. Every subsequent boot uses cached assets.

Does Agent Guard slow down agent tool calls?

Yes, by approximately 11 microseconds per tool call at 5K RPS (the embedded Bifrost gateway's measured overhead inside the Agent Guard AI Gateway). For interactive agent sessions this is imperceptible. For high-throughput automated workflows, the overhead is in the noise compared to LLM inference latency.

Why is npm install slow inside the microVM?

The first install of any package downloads from npm over the microVM's NAT-ed connection. Subsequent runs reuse the install via the overlay (cached at /usr/local/lib/node_modules). If you find yourself doing repeated fresh installs, fork an environment that already has the packages installed.

How much RAM does the microVM use?

3072 MiB by default. Change it with --ram <MiB> on agentguard run, for example --ram 2048 to drop to 2 GiB or --ram 4096 to give the microVM 4 GiB. Below 2 GiB, package installs and language servers will OOM. Agent Guard does not balloon down dynamically; the allocation is fixed at boot time.

Security

Can the agent escape the microVM?

The agent is running in a Linux microVM under Apple's Virtualization.framework. Escaping requires a hypervisor bug, which is the same trust boundary that backs Docker Desktop, Lima, OrbStack, and every cloud provider's VM offering. Agent Guard does not introduce a new escape surface beyond Apple's framework.

Can the agent read my SSH keys?

No, not unless you explicitly pass them with --pass-env or include them in the workspace. The microVM does not have access to your home directory.

Can the agent tamper with the audit log?

No. The audit log lives on the host outside the microVM (~/Library/Logs/AgentGuard/policy_audit.jsonl). The agent cannot reach that file from inside the microVM.

A user with shell access on the host can still modify the file. Each record carries a hash of the previous record, so tampering is detectable on review even when the file is mutable.

Are policies signed?

Optionally, with cosign. Pass --pub-key to agentguard policy add, or configure a trusted-keys store with agentguard trusted-keys add. When trusted keys are configured, every remote policy source is verified on every sync.

Does Agent Guard send my data anywhere?

By default, no. Policy sync pulls from the configured registry. If you configure a Hub, audit records sync to that Hub on a recurring schedule. Nothing else leaves the machine. Agent Guard does not phone home, does not send telemetry to Jozu, and does not have any reporting channel beyond the user-configured Hub.

Operations

Where do I find the audit log?

~/Library/Logs/AgentGuard/policy_audit.jsonl. One JSON record per line. See Read logs and audit trails for the schema and example queries.

How do I share Agent Guard configuration across a team?

Publish your policies as an OCI artifact to a shared Hub. Distribute the agentguard policy add commands as part of your onboarding script, MDM profile, or repo setup. Every developer machine picks up policy updates on the next run.

See the persona walkthroughs in the README for security admin, team lead, and platform engineer flows.

Can I run multiple agents in parallel?

Yes. Each agentguard run spawns its own microVM. Memory is the binding constraint: by default each microVM gets 3072 MiB, tunable per run with --ram <MiB> (e.g. --ram 2048 for a leaner session). On a 32 GB Mac, you can run multiple agents simultaneously without trouble. On a 16 GB Mac, two concurrent microVMs at the default is the practical ceiling — lower --ram if you need to fit a third.

What happens to my workspace when the agent exits?

With the default live mount, workspace changes are written through to the host file system in real time. No sync step. When the agent exits, your workspace is already in its final state.

With --no-live-sync (vsock tar mode), workspace changes are copied in once at startup and copied back once on exit.

How do I uninstall Agent Guard?

agentguard uninstall

This removes the binary, the state directory, and the Keychain entries. The audit log under ~/Library/Logs/AgentGuard/ is preserved on purpose. See Uninstall and clean up for what stays.

Hub and enterprise

Do I need Jozu Hub to use Agent Guard?

No. Agent Guard works without a Hub. The Hub adds centralized policy distribution, signed audit storage, and a registry for agent definitions and MCP servers. Individual developers and small teams can run Agent Guard against the public jozu.ml for policy pulls and store audit data locally.

Can I use a private OCI registry instead of Jozu Hub?

Yes for policy artifacts and agent definitions: any OCI 1.1-compliant registry (Harbor, ECR, GitHub Container Registry) works. Some advanced features (Rapid Inference Containers, pull-time policies, custom Hub scanning) require a private Jozu Hub specifically.

How does Agent Guard fit alongside Jozu Hub and KitOps?

KitOps packages AI artifacts into ModelKits, Hub stores and governs them, Agent Guard enforces policies on what runs inside the runtime. See Where Agent Guard fits in Jozu for the full picture.

Is Agent Guard FIPS-compliant?

A FIPS 140-3 build using BoringCrypto is available (make build-fips). Contact Jozu for distribution of the FIPS-validated binary if your environment requires it.

Reporting issues and getting help

Where do I file bugs?

github.com/jozu-ai/agentguard/issues. Include version, platform, the failing command, and relevant log excerpts. See Common errors for the level of detail that makes an issue actionable.

Where do I ask questions?

For product questions, contact your Jozu account team or open a GitHub Discussion on the agentguard repo. For policy authoring help, the examples in the pre-built tiers (jozu/agentguard-policies:vm-*) are the best starting reference.