Run an agent

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

agentguard run <agent> --workspace <path>

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

This page covers what differs per agent: how each authenticates, what gets installed on first run, and where credentials are cached. For shared behavior (workspace mounting, named environments, passing credentials) see the linked pages.

Common flags

These work for every agent.

Flag	Default	What it does
--workspace <path>	none	Directory the agent can read and write. Required for any non-trivial use.
--env <name>	auto-generated	Named environment to use. Omitting auto-generates <agent>-<sha256(workspace)[:12]>.
--agent-ref <ref>	none	Pull and apply an agent definition from an OCI registry. See Run with an agent definition.
--policy-ref <ref>	none	Pull a policy ref for this run, scoped to the workspace.
--pass-env <KEY>	none	Pass a host environment variable into the microVM. Repeatable. See Pass credentials.
--pass-cloud-creds <provider>	none	Pass cloud provider credentials. Valid: aws, gcp, azure, vault, kubernetes, all.
--no-sync	false	Skip the automatic policy sync for this run.
--shell	false	Drop into a shell inside the microVM instead of starting the agent.
--ram <MiB>	3072	Memory allocated to the microVM.

See CLI reference for the full flag list.

What persists between runs

Each workspace gets a named environment under ~/.agentguard/vm/environments/. Installed packages (apt-get install, npm install), the agent's auth token, tool configurations, and any custom files in /root or /usr/local carry forward from one run to the next. Conversation history and telemetry do not persist. Manage environments with the agentguard env commands; see CLI reference.

Claude Code

Claude Code ships as a single static Linux ARM64 binary, which Agent Guard downloads from GCS on first run and caches at ~/.agentguard/vm/claude-code-<version>. Pre-download it without running an agent using agentguard fetch claude-code.

Authentication

The first run opens the standard Claude Code OAuth flow. After completion, the token is cached in your macOS Keychain under the service AgentGuard and the account vm-claude-code-credentials. Subsequent runs read the keychain entry and skip the prompt.

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

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

Agent Guard passes the variable to the microVM in memory over vsock; it is never written to disk on the host or persisted in the microVM overlay.

Binary verification

Release builds pin a SHA256 checksum for the default Claude Code version. Override with --version <ver> to use a different version; Agent Guard records the checksum on first download and verifies it on every subsequent run. A mismatch is fatal: the binary is deleted, and the next run re-downloads it.

If Claude Code is already installed on your host, Agent Guard matches the host version. Otherwise it uses the build-time pinned version.

Gemini CLI

Gemini is a Node.js application. Agent Guard runs npm install -g @google/gemini-cli inside the microVM on first run and caches the install in the overlay. First run takes about 30 seconds; subsequent runs are instant.

Authentication

Log in to Gemini on your host once before running it inside Agent Guard:

npm install -g @google/gemini-cli
gemini login

This populates ~/.gemini/oauth_creds.json on your Mac. Agent Guard reads that file on first microVM startup and copies the OAuth credential into the microVM. From that point on, the token is cached in your macOS Keychain under the account vm-gemini-credentials.

To use an API key, set GEMINI_API_KEY before running:

export GEMINI_API_KEY=...
agentguard run gemini --workspace ~/projects/myapp

Codex CLI

Codex is a Node.js wrapper around a native Rust binary. Agent Guard installs both inside the microVM on first run via npm install -g @openai/codex and the platform-specific @openai/codex-linux-arm64. Both persist via the overlay.

Authentication

Either log in on the host before running:

npm install -g @openai/codex
codex login

This writes ~/.codex/auth.json on the host. Agent Guard reads that file on first run, copies the auth into the microVM, and caches it in your macOS Keychain under vm-codex-credentials.

Or set an API key directly:

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

OpenClaw

OpenClaw is a Node.js agent. Agent Guard runs npm install -g openclaw inside the microVM on first run.

Authentication

OpenClaw stores credentials at ~/.openclaw/openclaw.json inside the microVM. There is no host-side login flow today; supply credentials via environment variables or by editing the config file inside the microVM. If OpenClaw is configured to use a provider with an API key, pass it with --pass-env:

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

Quick reference

Agent	Install behavior	Host login command	Keychain account	API key env var
Claude Code	Single binary, downloaded from GCS on first run	OAuth flow on first run inside the microVM	vm-claude-code-credentials	ANTHROPIC_API_KEY
Gemini CLI	npm install -g @google/gemini-cli inside the microVM	gemini login on host	vm-gemini-credentials	GEMINI_API_KEY
Codex CLI	npm install -g @openai/codex inside the microVM	codex login on host	vm-codex-credentials	OPENAI_API_KEY
OpenClaw	npm install -g openclaw inside the microVM	None	None	Provider-specific (--pass-env)