Run an agent

Agent Guard runs Claude Code, Codex CLI, OpenClaw, and Antigravity CLI. The launch flow is the same for all four:

agentguard run <agent> --workspace <path>

<agent> is one of claude-code, codex, openclaw, or antigravity. Agent Guard boots a Linux microVM, mounts the workspace, and starts the agent inside.

Every run needs a Jozu Hub session. If there is none, or it has expired, agentguard run opens the sign-in flow before the microVM boots. A non-interactive run fails instead, so run agentguard register on that machine first, or set AGENTGUARD_NO_LOGIN to skip the session check (see CLI reference).

This page covers what differs per agent: how each is installed, how it authenticates, and what carries over between runs. For passing other credentials, see Pass credentials.

Common flags

These work for every agent.

Flag	Default	What it does
-w, --workspace <path>	current directory	Directory the agent can read and write, mounted at the same path in the microVM.
-e, --env <name>	per agent and workspace	Named environment to use. Omitting it uses <agent>-<sha256(workspace)[:12]>, so each agent gets its own environment in each workspace.
--agent-ref <ref>	none	Pull and apply an agent definition. See Run with an agent definition.
--policy-ref <ref>	none	Add a policy source, scoped to the workspace, and keep it for future runs.
--pass-env <KEY>	none	Pass a host environment variable into the microVM. Repeatable.
--pass-cloud-creds <provider>	none	Pass cloud provider credentials: aws, gcp, azure, vault, kubernetes, or all. Repeatable and comma-separated.
--no-sync	false	Skip the automatic policy sync for this run.
--shell	false	Open a bash shell in the microVM, with the agent installed on PATH, instead of starting the agent.
--ram <MiB>	3072	Memory allocated to the microVM.
--vcpus <N>	4	Virtual CPUs allocated to the microVM.

See CLI reference for the full flag list.

What persists between runs

Each agent gets a named environment per workspace under ~/.agentguard/vm/environments/. Installed packages (apt-get install, npm install), tool configuration, and files under /root, /usr/local, and /opt carry forward from one run to the next. Manage environments with the agentguard env commands; see CLI reference.

Agent credentials are not kept in the environment. Inside the microVM they live on a memory-backed filesystem that is discarded when the microVM stops. Between runs they are kept in your macOS Keychain, under the service AgentGuard, so signing in once works in every environment.

Conversation history persists in the environment for Claude Code, Codex CLI, and Antigravity CLI, so an agent can resume an earlier session. Each run says where it is kept and how to clear it:

Conversation history persists in this environment (claude-code-e8dfa5bbf44d). Clear it with: agentguard env clear-state claude-code-e8dfa5bbf44d

Pass --no-persist-sessions to keep a run's history out of the environment. Session files older than 30 days are pruned. OpenClaw keeps no history between runs.

Claude Code

Claude Code is a Linux ARM64 binary. Agent Guard downloads it on the host on first use, caches it at ~/.agentguard/vm/claude-code-<version>, and transfers it into the microVM on every run.

Version and verification

Agent Guard runs the version passed with --version; otherwise the version of claude installed on your host; otherwise the version the Agent Guard release pins.

The pinned version's SHA256 checksum is built into the release. Any other version is checked on first use: its checksum is recorded in ~/.agentguard/vm/checksums.json and verified on every later run. A mismatch is fatal: the cached binary is deleted, and the next run downloads it again.

Authentication

With no cached credential, Claude Code runs its OAuth sign-in inside the microVM, and Agent Guard copies the sign-in URL to your Mac's clipboard. After you complete it, the token is kept in your macOS Keychain under the account vm-claude-code-credentials, and later runs reuse it. A Claude Code login on your host is not reused.

To use an API key instead, set ANTHROPIC_API_KEY before running:

export ANTHROPIC_API_KEY=sk-ant-...
agentguard run claude-code --workspace ~/projects/myapp

Agent Guard forwards the variable automatically, in memory over vsock; it is not written to disk on the host. With an API key set, the cached OAuth token is not used.

Codex CLI

Codex is a Node.js wrapper around a native binary. On first run Agent Guard installs @openai/codex and its linux-arm64 package with npm inside the microVM. Both are cached in the environment.

Authentication

Agent Guard looks for Codex credentials in this order:

1. ~/.codex/auth.json on your host, written by codex login. It is read on every run.
2. The token Agent Guard kept from an earlier run, in your macOS Keychain under the account vm-codex-credentials.
3. Neither: Codex runs its OAuth sign-in inside the microVM, and the result is kept in the Keychain for later runs.

To use an API key instead, set OPENAI_API_KEY. Agent Guard forwards it automatically, and neither ~/.codex/auth.json nor the Keychain token is used:

export OPENAI_API_KEY=sk-...
agentguard run codex --workspace ~/projects/myapp

OpenClaw

OpenClaw is a Node.js agent. On first run Agent Guard installs the version of openclaw it pins, with npm inside the microVM.

Authentication

OpenClaw has no sign-in flow and no Keychain entry. It uses a provider API key:

• ANTHROPIC_API_KEY is forwarded automatically.
• OPENAI_API_KEY must be passed with --pass-env.

Agent Guard writes OpenClaw's configuration, ~/.openclaw/openclaw.json, on every run, and sets up the model for whichever key is present. Changes you make to that file inside the microVM do not carry over to the next run.

agentguard run openclaw --pass-env OPENAI_API_KEY --workspace ~/projects/myapp

Antigravity CLI

Antigravity CLI is a native binary, agy. On first run the microVM downloads it from Antigravity's release manifest, checks its SHA512 against the manifest, and caches it in the environment.

Authentication

Antigravity CLI signs in with OAuth only; it has no API-key alternative. Agent Guard looks for a session in this order:

1. Your host's Antigravity session. Run agy on your Mac once and complete the browser sign-in; Agent Guard reads the session agy keeps in your Keychain.
2. The session Agent Guard kept from an earlier run, in your macOS Keychain under the account vm-antigravity-credentials.
3. Neither: sign in inside the microVM when agy prompts.

Agent Guard also copies settings.json, mcp_config.json, and hooks.json from your host's ~/.gemini/config/ into the microVM.

To continue an earlier conversation, use /resume inside agy.

Quick reference

Agent	<agent>	Install	Sign-in	Keychain account	API key
Claude Code	claude-code	Binary downloaded on the host, checksum-verified	In the microVM	vm-claude-code-credentials	ANTHROPIC_API_KEY
Codex CLI	codex	npm, inside the microVM	codex login on the host, or in the microVM	vm-codex-credentials	OPENAI_API_KEY
OpenClaw	openclaw	npm, inside the microVM	None	None	ANTHROPIC_API_KEY, or OPENAI_API_KEY with --pass-env
Antigravity CLI	antigravity	Binary downloaded in the microVM, checksum-verified	agy on the host, or in the microVM	vm-antigravity-credentials	None