Custom agent runtimes

A custom runtime is an application you package as a container image and run under Agent Guard, in place of one of the CLI agents Agent Guard integrates (Claude Code, Codex CLI, OpenClaw, Antigravity CLI). The application can be anything: a Python script, a Node service, a compiled binary. Agent Guard runs it inside the same microVM, behind the same Jozu AI Gateway and policies, as any other agent.

To run a custom runtime, write an OCI image reference, instead of a framework name, in an agent definition's spec.framework:

spec:
  framework: jozu.ml/acme/triage-agent:1.0.0

The rest of the definition keeps its usual shape: its llm modules name the models the application may call, its mcp modules name the tools, its policy modules name the rules, and its skill modules name the skills.

In this section

• Build your first custom runtime: build, declare, and run a minimal runtime.
• Build a runtime image: what the image must provide, and how the application reaches models and tools.
• Declare a runtime in an agent definition: naming the image, and the models, tools, skills, policies, and values it gets.
• Run and operate a runtime: running it, image caching, resources, state, and records.
• Environment and mount reference: every variable and directory the container receives.
• Limitations: the boundaries a custom runtime does not enforce.

How a run works

 host                                   microVM
┌──────────────────────┐   ┌─────────────────────────────────────────────┐
│ agentguard run <ref> │   │                                             │
│                      │   │  ┌─────────────────┐   ┌─────────────────┐  │
│ 1. resolve the image │   │  │ your image      │──▶│ gateway         │──┼──▶ model providers
│    to a digest       │──▶│  │ (rootless       │   │ 127.0.0.1:9091  │  │
│ 2. fetch and cache it│   │  │  container)     │   │ models, tools,  │──┼──▶ MCP servers
│ 3. boot the microVM  │   │  └─────────────────┘   │ policy, audit   │  │
│                      │   │                        └─────────────────┘  │
└──────────────────────┘   └─────────────────────────────────────────────┘

1. On the host, Agent Guard resolves the agent definition, then resolves the image named in spec.framework to a linux/arm64 manifest digest and fetches it into a local cache.
2. The microVM boots with the Jozu gateway running. The guest imports the image, checks that its digest is the one the host resolved, and starts it as a rootless container.
3. The application finds the Jozu gateway through environment variables. It sends model requests to the OpenAI-compatible route, authenticated with a per-session token that is minted at boot and valid only against that session's gateway, and tool calls to the MCP route.
4. The Jozu gateway resolves each model name against the definition's llm modules and refuses a model the definition does not declare. It applies GuardrailPolicy to model requests and responses and ToolPolicy to tool calls, and writes audit records. When the application exits, its exit code becomes the exit code of agentguard run.

What the application can and cannot reach

The container holds no provider credential. The definition's llm modules carry the credentials, and the Jozu gateway keeps them, so a leaked environment dump or a compromised dependency has no provider key to take.

The container can call only the models the definition declares. The application names a model by its module name, and the Jozu gateway maps that name to the real provider and model. A request for any other model is refused and recorded.

The container's tool calls go through the Jozu gateway. Every mcp module is reachable at one gateway endpoint, and the definition's policies are evaluated there.

The container sees four directories: the workspace, a state directory that persists with the environment, a cache directory that is emptied every session, and a read-only directory holding skills and the Jozu gateway's CA bundle. It does not see the agent home, the Jozu gateway's own files, or the MCP servers' files.

See Limitations for the boundaries a custom runtime does not enforce, including network reach and resource limits.