CLI reference

Every Agent Guard command and its flags.

Command summary

agentguard run <agent-or-ref> [flags] [-- args]   Run an agent under Agent Guard
agentguard register [flags]                       Authenticate and register with the configured Hub
agentguard policy add <ref> [flags]               Add a policy source (global or workspace-scoped)
agentguard policy remove <ref>|--all [flags]      Remove a policy source
agentguard policy list [flags]                    List configured policy sources
agentguard env list [flags]                       List named environments
agentguard env info <name>                        Show environment details and disk usage
agentguard env clear-state <name>                 Delete an environment's saved conversation history
agentguard env rename <old> <new>                 Rename an environment
agentguard env fork <source> --name <new>         Clone an environment
agentguard env delete <name>                      Delete an environment
agentguard trusted-keys add <path>                Add a cosign public key to the trusted set
agentguard trusted-keys list                      List trusted keys
agentguard trusted-keys remove <path>             Remove a trusted key
agentguard audit upload [flags]                   Sign and submit the latest policy audit log to the Hub
agentguard audit schedule install [flags]         Upload audit logs on a recurring schedule
agentguard audit schedule uninstall               Stop recurring audit uploads
agentguard audit schedule status                  Show whether recurring uploads are registered
agentguard status                                 Show policy sources, agents, and sandboxes
agentguard top [flags]                            Live view of running microVM resource usage
agentguard logs [flags]                           Tail audit, server, and microVM logs together
agentguard update [flags]                         Check for and install the latest release
agentguard uninstall [flags]                      Remove Agent Guard from the machine
agentguard --version                              Print the installed version
agentguard --help                                 Show help for any command or subcommand

agentguard run

Launches an agent inside Agent Guard's enforcement environment.

agentguard run <agent-or-ref> [flags] [-- args]

<agent-or-ref> is one of claude-code, codex, openclaw, or antigravity, or the reference of an agent definition, such as jozu.ml/acme/my-agent:v1, whose spec.framework names the agent. With an agent name as the positional, --agent-ref applies a definition, and the agent name fills in the framework when the definition declares none; a reference as the positional cannot be combined with --agent-ref. Arguments after -- are passed to the agent.

Every run needs a Jozu Hub session. If there is none, run opens the sign-in flow before the microVM boots; a non-interactive run fails instead. See agentguard register.

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 for persistent storage. Omitting it uses <agent>-<sha256(workspace)[:12]>. An environment can be used by one microVM at a time, and a name you choose is shared by every workspace that uses it.
--no-workspace	false	Do not mount a workspace. Uses the environment <agent>-default.
--no-overlay	false	Run without a persistent environment. Nothing carries over to the next run.
--no-persist-sessions	false	Do not keep conversation history in the environment.
--agent-ref <ref>	none	Apply an agent definition. See Run with an agent definition.
--pub-key <path>	none	Cosign public key to verify the agent definition and its modules against, together with the trusted keys. Repeatable.
--policy-ref <ref>	none	Add a policy source, scoped to the workspace, and keep it for future runs.
--no-sync	false	Skip the automatic policy sync for this run.
--plain-http	false	Use plain HTTP and skip TLS verification for the registry of the agent definition reference and of --policy-ref. For local registries only.
--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.
--forward <HOSTPORT:VMPORT>	none	Forward a host port to a port on the microVM's localhost. Repeatable.
--shell	false	Open a bash shell in the microVM, with the agent installed on PATH, instead of starting the agent.
--no-agent	false	Open a bash shell with no agent installed. Implies --shell.
--version <ver>	host claude, else pinned	Claude Code version to run. Omitting it uses the version installed on the host, or the release's pinned version.
--agent-bin <path>	none	Run a pre-built Linux ARM64 agent binary instead of downloading one.
--ram <MiB>	3072	Memory allocated to the microVM.
--vcpus <N>	4	Virtual CPUs allocated to the microVM.
--no-share-parent-git	false	In a git worktree, do not share the parent repository's .git directory. Git operations inside the microVM then fail.
--debug-io	false	Log vsock I/O to /tmp/agentguard-io.log, for debugging terminal problems.

When the agent definition names a container image as its framework, some of these flags behave differently: --pass-env and --pass-cloud-creds do not reach the application's container, --version and --agent-bin are ignored, --shell is not supported, and --no-agent boots a shell without starting the image. See Run and operate a runtime.

Examples:

# Default run, in the current directory
agentguard run claude-code

# Pass GitHub token and AWS credentials
export GH_TOKEN=$(gh auth token)
agentguard run claude-code \
  --pass-env GH_TOKEN \
  --pass-cloud-creds aws \
  --workspace ~/projects/myapp

# Run an agent definition from Hub
agentguard run jozu.ml/acme/my-agent:v1 --workspace ~/projects/myapp

# Debug a microVM problem with a shell
agentguard run claude-code --shell --workspace ~/projects/myapp

agentguard register

Authenticates this Agent Guard installation and registers it with the configured Jozu Hub. Every agentguard run needs the resulting session. run starts the same flow itself when there is no session; register lets you complete the sign-in once, ahead of time, on a machine where later runs are non-interactive, and re-register. To run without a session, set AGENTGUARD_NO_LOGIN (see Environment variables).

agentguard register [flags]

The command runs the OAuth device-authorization flow: it prints a URL (and opens it in your browser unless --no-browser is set), waits for approval, then saves the resulting tokens to $AGENTGUARD_HOME/session.json (by default ~/.agentguard/session.json) and registers the machine's public key with the Hub.

Flag	Default	What it does
--force	false	Rotate the keypair and re-register, replacing the existing identity. Use when moving a machine to a new Hub or recovering from a corrupt identity.
--device-name <name>	hostname	Override the device name shown in the Hub fleet view.
--no-browser	false	Print the verification URL without attempting to open it. Use on headless machines.

If Agent Guard is already registered and the session is valid, register exits immediately. An expired session is renewed under the same identity.

agentguard policy

Manages policy sources. See Manage policies for the full flow.

agentguard policy add

Adds a policy source and pulls it immediately. The policies are validated, including compiling their CEL, before the source is saved.

agentguard policy add <ref> [flags]

Flag	What it does
-w, --workspace <path>	Scope the policy to a workspace path. Use -w . for the current directory. Omitting adds to global scope.
--registry <host>	Registry host to use when the ref has none. Saved to config.json for future syncs.
-u, --username <user>	Registry username.
-p, --password <token>	Registry password or token. Prompted for when --username is given without it.
--pub-key <path>	Verify the policy artifact signature against this cosign public key.
--plain-http	Use plain HTTP and skip TLS verification for this source's registry. Saved on the source.

agentguard policy remove

agentguard policy remove <ref> [flags]
agentguard policy remove --all [flags]

Flag	What it does
-w, --workspace <path>	Remove from a specific workspace scope. Omitting removes from global.
--all	Remove every source at the specified scope.

agentguard policy list

agentguard policy list [flags]

Flag	What it does
-w, --workspace <path>	Show global sources plus the sources scoped to this workspace. Omitting shows global sources and every workspace's.

agentguard env

Manages named environments. Each named environment keeps a persistent overlay of /root, /usr/local, /opt, and the agent's home directory, holding installed packages, tool configuration, and conversation history across runs.

agentguard env list                           # All environments
agentguard env list --agent claude-code       # Filter by agent
agentguard env info <name>                    # Show details and disk usage
agentguard env clear-state <name>             # Delete saved conversation history
agentguard env rename <old> <new>             # Rename
agentguard env fork <source> --name <new>     # Clone
agentguard env delete <name>                  # Delete

env list marks the current directory's environment with *, and shows which environments are in use. env fork uses APFS copy-on-write where it can, so a clone is near-instant and uses no extra disk until it diverges; add --with-sessions to copy conversation history too. env delete and env clear-state ask for confirmation; -y skips it.

agentguard trusted-keys

Manages the cosign public keys Agent Guard trusts.

agentguard trusted-keys add <path>
agentguard trusted-keys list
agentguard trusted-keys remove <path>

When trusted keys are configured, agentguard run verifies the agent definition and its modules against them before the microVM boots, together with any --pub-key. Policy sources added with agentguard policy add are verified only with that command's own --pub-key.

agentguard audit

Submits the local policy audit log to the configured Jozu Hub.

agentguard audit upload [flags]

Flag	What it does
--session <id>	Upload the audit log for this session (the suffix of policy_audit.<session>.jsonl) rather than the most recent.
--file <path>	Read the audit log from this file. Cannot be combined with --session.
--dry-run	Build the bundle and print summary statistics without submitting it.
--quiet-when-empty	Exit with status 0 and no output when there is nothing to upload.

agentguard audit schedule uploads on a recurring schedule through a macOS LaunchAgent, ~/Library/LaunchAgents/ml.jozu.agentguard.audit-upload.plist, rather than a long-running process:

agentguard audit schedule install --interval 300   # every 300 seconds (the default)
agentguard audit schedule status
agentguard audit schedule uninstall

agentguard status

Shows the current state of Agent Guard on the machine: configured policy sources and when they last synced, the pinned Claude Code version, the agents detected on the host and their sandboxes, and a summary of saved conversation history.

agentguard status

Run this first when something is not working as expected.

agentguard top

Live view of microVM resource usage for running sessions.

agentguard top [flags]

Columns are PID, agent, state, environment, workspace, vCPUs, allocated RAM, RSS, CPU usage, and uptime. Stop it with Ctrl-C.

Flag	Default	What it does
--interval <seconds>	2	Refresh interval.
-1, --once	false	Print one snapshot and exit.

agentguard logs

Tails the policy audit log, the policy server log, and the microVM serial console together.

agentguard logs [flags]

Flag	Default	What it does
-n, --lines <N>	20	Number of recent lines to show from the policy server log before following.
--no-serial	false	Hide microVM serial console output (kernel messages and in-guest init).
-p, --previous <N>	0 (current)	Print the Nth previous serial log and exit rather than following. -p 1 prints the last session's serial output.
--guardrails	false	Show only GuardrailPolicy decisions from the audit log, without tool-call events, server log or serial output.

The raw audit log is JSONL at ~/Library/Logs/AgentGuard/policy_audit.<session>.jsonl. See Read logs and audit trails.

agentguard update

Checks for a newer Agent Guard release and installs it.

agentguard update [flags]

Flag	What it does
--dry-run	Report what would be installed without installing it.
-y, --yes	Skip the confirmation prompt.
--version <ver>	Install this exact version: an upgrade, a reinstall, or a downgrade. latest reinstalls the newest release.

agentguard uninstall

Removes Agent Guard from the machine, including its Keychain entries and the audit-upload LaunchAgent.

agentguard uninstall [flags]

Flag	What it does
--keep-config	Keep ~/.agentguard with config.json, so policy sources survive a reinstall. Cached policy files are still deleted.
--dry-run	Show what would be removed without removing it.

The audit log under ~/Library/Logs/AgentGuard/ is preserved regardless of flags. See Uninstall and clean up for what gets removed and what stays.

Global flags

These work on any command.

Flag	What it does
-h, --help	Show help for any command or subcommand.
-v, --version	At the top level, print the installed Agent Guard version and exit. agentguard run and agentguard update take their own --version <ver>.

Environment variables

Variable	Default	What it does
AGENTGUARD_HOME	~/.agentguard	State directory. Override it to move all state, for example on a machine with no writable home directory. With it set, logs are written under $AGENTGUARD_HOME/logs.
AGENTGUARD_NO_SYNC	unset	When set to 1, disables the automatic policy sync on every run. Equivalent to passing --no-sync every time.
AGENTGUARD_NO_LOGIN	unset	When set, agentguard run skips the Jozu Hub session check. For CI; fleet heartbeats are not sent without a registered instance.
AGENTGUARD_NO_UPDATE_CHECK	unset	When set, disables the check for a newer release.
JOZU_HUB_URL	https://api.jozu.ml	The Jozu Hub API that register, run, and audit talk to.
ANTHROPIC_API_KEY	unset	Credential for Claude Code and OpenClaw. When set, Claude Code uses it instead of a cached OAuth token. Forwarded automatically to Claude Code and OpenClaw.
OPENAI_API_KEY	unset	Credential for Codex CLI. When set, it is used instead of cached or host credentials. Forwarded automatically to Codex CLI; for OpenClaw, pass it with --pass-env.