Architecture

Agent Guard sits between the agent and the rest of your machine. On Apple Silicon, it uses Apple's Virtualization framework to boot a microVM: a small Linux ARM64 guest dedicated to one agent session. You do not need Docker, QEMU, or any other virtualization software installed.

 macOS host                          MicroVM (ARM64)
+------------------+          +---------------------------+
| agentguard CLI   |          | /init (PID 1)             |
|   |              |  vsock   |   |-- Agent Guard         |
|   +-- vm         +----------+   |   AI gateway          |
|   +-- transfers  |  :2048   |   |-- agent (claude/      |
|   +-- terminal   |  :1024   |   |   gemini/codex/       |
|   +-- virtiofs   |          |   |   openclaw)           |
+------------------+          +---------------------------+

What is in the binary

The Agent Guard binary embeds everything it needs to boot the microVM:

Component	Approximate size	Purpose
Linux kernel	2.5 MB	ARM64 kernel for Apple Virtualization.framework
Initrd	10 MB	Init binary and static busybox; bootstraps the microVM and mounts the disk rootfs
Agent Guard AI Gateway	40 MB	Evaluates tool calls and inspects LLM traffic from inside the microVM
Agent Guard hook handler	15 MB	Runs inside the microVM, calls the gateway for every tool invocation
Debian rootfs	~500 MB	Linux userspace the agent runs against

The rootfs makes up most of the binary's size. On first run, Agent Guard extracts it to ~/.agentguard/vm/rootfs.img and reuses that cached copy from then on. The cached image is version-pinned to the binary that produced it, so upgrades extract a fresh image. Nothing is fetched from the network at boot.

Boot sequence

1. Host extracts the kernel and initrd to ~/.agentguard/vm/.
2. Virtualization.framework boots the microVM. Boot takes about one second after the rootfs is cached.
3. Guest init mounts the filesystems, runs DHCP, and syncs the clock.
4. Host transfers the agent binary, the gateway binary, the policy files, and any passed credentials into the guest over vsock port 2048.
5. Host shares your workspace into the guest as a live mount via virtiofs.
6. Guest starts the Agent Guard AI Gateway, installs the agent's hook handler, and launches the agent. The terminal connects via vsock port 1024.

Workspace sharing

Your workspace is shared via virtiofs, not copied. The mount is bidirectional and live: a file the agent writes inside the microVM appears immediately in the host directory, and a file you edit on the host appears immediately to the agent. There is no sync step on exit.

If virtiofs is unavailable, Agent Guard falls back to a vsock-based tar transfer that copies the workspace into the microVM and copies changes back when the microVM exits. Pass --no-live-sync to force this fallback.

Persistence

Each workspace gets a named environment under ~/.agentguard/vm/environments/<env-name>/. The directories the agent normally writes into (its home dir, /usr/local, /opt, and /root) are live-mounted from there into the microVM. So things you'd expect to stick around between runs do:

• Packages you install with apt-get install, npm install -g, pip install, go install, and so on.
• The agent's auth tokens and tool configurations under its home directory.
• Any other files the agent drops into those persistent paths.

Everything else inside the microVM is ephemeral by design. The rest of the filesystem, in-memory state, network sockets, and the per-session credentials Agent Guard mints at boot all disappear when the microVM exits. That keeps each run on a known starting state and avoids accumulating cruft you didn't ask for.

If you want a clean slate, delete or fork the named environment with the agentguard env commands.

Networking

The microVM gets outbound internet through a user-space network stack that Agent Guard runs on the host. Nothing the microVM does touches the host's network interfaces directly; every packet goes through that stack first. DNS resolves through the same path. Inbound from the host to the microVM is limited to the vsock channels Agent Guard sets up. The Agent Guard AI Gateway runs on a localhost port inside the microVM and is not reachable from the host.

Resource requirements

Component	Memory
MicroVM total	3072 MiB by default, configurable via --ram <MiB>
Agent Guard AI Gateway	~140 MB RSS at idle
Rootfs (demand-paged)	~300 MB typical; pages loaded as accessed
Agent (Claude Code)	200 to 400 MB depending on session
Available for tools	~2 GB for apt installs, npm, pip, language servers

If you are running multiple agents at once or another memory-intensive workload, raise --ram. The microVM cannot dynamically reclaim memory from the host.