Run and operate a runtime

A custom runtime runs with the same agentguard run command as any agent definition. The difference is that the host fetches a container image before the microVM boots, so image resolution, caching, and some flags behave differently, and a run can fail on the image as well as on the definition.

Run it

Run the agent definition, not the image:

agentguard run jozu.ml/acme/triage-agent-def:1.0.0 -w ~/projects/incidents

The positional argument is the agent definition's ModelKit reference, the same as for any agent definition. The definition names the image in spec.framework. If you also name a CLI agent, as in agentguard run claude-code --agent-ref ..., the definition's image wins and the run says so.

Arguments after -- are passed to the application and replace the image's CMD:

agentguard run jozu.ml/acme/triage-agent-def:1.0.0 -- --queue platform-oncall --dry-run

The run's exit code is the application's exit code. When the sandbox itself fails, the run prints the reason and exits with status 1, which an application can also return, so the printed reason is what tells the two apart. When the application exits non-zero, Agent Guard adds no output of its own.

Flags

These behave as they do for any agent: --workspace / -w, --no-workspace, --env (named environment), --no-overlay, --vcpus, --ram, --pub-key, --plain-http, --policy-ref.

These behave differently for a custom runtime:

Flag	Behavior
--pass-env, --pass-cloud-creds	Set variables in the microVM but not in the application's container. Declare values the application needs in the definition's spec.needs.
--version, --agent-bin	Ignored. They select a CLI agent's binary, and there is none.
--no-agent	Boots a shell in the microVM without starting the image.
--shell	Not supported for a custom runtime.

Where the image comes from

Before the microVM boots, Agent Guard resolves spec.framework against the registry it names and prints the digest it resolved to:

Resolving custom runtime image: jozu.ml/acme/triage-agent:1.0.0
Runtime image jozu.ml/acme/triage-agent:1.0.0 resolved to sha256:3b1f...

Authentication. Agent Guard tries the credentials stored by kit login first, then those stored by docker login. Log in to the image's registry with either.

Plain HTTP. --plain-http applies to the registry host of the agent definition reference. The image is fetched over plain HTTP only when it is on that same host. An image on a different registry is fetched over HTTPS.

Digest pinning. The digest resolved on the host is the image's identity for the whole session. The guest imports the image and refuses to start it if the imported digest differs.

Admission. The agent definition goes through artifact admission and signature verification (--pub-key, ArtifactPolicy) like any agent definition, and so do its MCP, skill, and policy modules. The image itself does not; see Limitations.

The image cache

Fetched images are cached on the host in $AGENTGUARD_HOME/images/ (by default ~/.agentguard/images/), one archive per digest:

~/.agentguard/images/sha256-<digest>.tar
~/.agentguard/images/sha256-<digest>.json

A run whose image is already cached only looks up the manifest to learn the digest, and prints Runtime image ... is already cached. The min-version check runs on every run, cached or not. An interrupted fetch leaves no partial archive behind.

The guest keeps each imported image in the environment's store, so the first run of a new image in an environment takes longer than the runs after it. To reclaim host disk space, delete archives from ~/.agentguard/images/; the next run of that image fetches it again.

Resources

A session is bounded by its microVM: --vcpus (default 4) and --ram (default 3072 MiB). The container has no limits of its own inside the microVM. A large image needs a larger --ram, because the archive is copied into guest memory before it is imported.

State

The state directory persists with the environment. Use --env <name> to give a runtime its own named environment, so its state is kept apart from other agents' and survives between runs. With --no-overlay, state lasts one session.

Records

Record	Where	Contents
Policy audit	~/Library/Logs/AgentGuard/policy_audit.<session>.jsonl	One record per tool call and model decision, with the policy that matched, the decision, and the arguments.
Gateway log	~/Library/Logs/AgentGuard/policy_server.<session>.log	The Jozu AI Gateway's operational log, including modules it dropped and why.
Agent definition audit	~/Library/Logs/AgentGuard/agent_def_audit.jsonl	One record per resolved definition. Its framework field is the image reference.

agentguard top lists custom runtime sessions under their image reference. The session identifier in the file names is the one the application receives as AGENTGUARD_SESSION_ID, so the application's own logs can be joined to these records. See Logs and audit for the formats.