Quickstart

This guide takes you from install to a policy controlled agent environment in about five minutes. It uses Claude Code in a MicroVM on macOS with a sample workspace. The same flow applies to Gemini, Codex, and OpenClaw. See Run an agent for what changes per agent.

Prerequisites

• macOS on Apple Silicon (M1 or later).
• A workspace directory you don't mind an agent reading and writing. A small project with a git repo works well.

Install Agent Guard

Run the install script:

curl -fsSL https://raw.githubusercontent.com/jozu-ai/agentguard/main/scripts/install.sh | bash

Verify:

agentguard --version

One-time setup

The first time you run agentguard run, Agent Guard extracts a ~500MB Linux disk image bundled inside its binary and caches it at ~/.agentguard/vm/rootfs.img. This takes a few seconds; subsequent runs reuse the cached image.

Add a starter policy

Agent Guard publishes four pre-built policy tiers on jozu.ml. The Standard tier is the right default for this guide:

agentguard policy add jozu.ml/jozu/agentguard-policies:vm-standard

Confirm the policy loaded:

agentguard policy list

You should see:

SCOPE    REF                                                  LAST SYNC
global   jozu.ml/jozu/agentguard-policies:vm-standard         2026-05-15 10:42

The policy is now active for every agentguard run, regardless of workspace.

Run Claude Code

Point Agent Guard at a workspace and launch:

agentguard run claude-code --workspace ~/projects/sample-app

You authenticate with Anthropic the same way you would running Claude Code directly. The token is cached in your macOS Keychain, so subsequent runs skip the auth step.

Once Claude is inside the microVM, ask it to do something the Standard tier blocks:

Force-push the current branch to origin/main.

Agent Guard denies the tool call. Your terminal will show:

[policy] BLOCK  tool=Bash  command="git push --force origin main"
     rule=no-force-push
     message="Force push is prohibited by security policy"

The agent receives the error and stops. You can then redirect it: use a regular push, open a PR, or skip the operation.

Type exit to leave the microVM. Workspace changes sync live, so nothing is lost on exit.

What just happened

The run did five things in sequence:

1. Agent Guard booted a Linux microVM and shared your workspace into it as a live mount. The agent saw /workspace and nothing else from your laptop.
2. The Agent Guard AI Gateway started inside the microVM. Every tool call Claude tried to make went through the gateway first.
3. The gateway evaluated each call against the Standard policy tier. Reads, allowed shell commands, and approved network calls passed. The force push matched a rule, was blocked, and the agent received an error.
4. Every decision was written to ~/Library/Logs/AgentGuard/policy_audit.jsonl for later review.
5. When you exited, the microVM was destroyed. Installed packages and Claude's auth token persisted via a named environment, so the next run starts where this one left off.

Next steps

• Try a stricter or more permissive tier: Use pre-built policy tiers
• Write your own policy: Write your first policy
• Run a different agent: Run an agent
• Understand what is actually running: Architecture