What an agent definition is

An agent definition is a YAML file that describes what an agent runs with: the MCP servers it can use, the policies enforced on it, the skills it gets, the models it names, and the values it needs from the host. Agent Guard pulls the definition from an OCI registry (or your local kit store), resolves any base definition it inherits from, and configures the microVM accordingly before the agent starts.

Instead of documenting "install this MCP server, set this environment variable, and use this policy," you name one reference:

agentguard run jozu.ml/myorg/security-review-agent:v1 --workspace ~/projects/myapp

Everything the agent needs comes from that single versioned artifact, which you can sign.

The shape of an agent definition

apiVersion: agentguard.jozu.dev/v1
kind: AgentDefinition
metadata:
  name: security-review-agent
spec:
  framework: claude-code

  needs:
    - name: ANTHROPIC_API_KEY

  includes:
    - name: primary-llm
      type: llm
      source:
        model: anthropic/claude-sonnet-4-20250514

    - name: security-scanner
      type: mcp
      source:
        modelkit: jozu.ml/myorg/security-scanner-mcp:v1

    - name: review-skill
      type: skill
      source:
        modelkit: jozu.ml/myorg/security-audit-skill:v1

    - name: vm-policies
      type: policy
      source:
        modelkit: jozu.ml/jozu/agentguard-policies:vm-standard

The apiVersion is agentguard.jozu.dev/v1, not gerty.jozu.dev/v1. Policies use gerty.jozu.dev/v1 (see The policy engine); agent definitions are a separate schema with its own version.

The framework: value names the agent the definition runs: one of claude-code, codex, openclaw, or antigravity, the same names agentguard run takes. The definition's framework wins over an agent named on the command line: if you write framework: claude-code and run agentguard run codex --agent-ref ..., Agent Guard runs Claude Code and says so. framework: can also name a container image, such as jozu.ml/acme/triage-agent:1.0.0, to run your own application in place of an agent CLI; see Custom agent runtimes.

Every module has a name, unique within the definition and made of letters, digits, ., - and _. The name is how modules are addressed when a derived definition inherits from a base.

Definitions written with spec.modules and module-level auth still load, with a deprecation warning. Write spec.includes and spec.needs instead.

The four module types

• llm: Names a model, as <provider>/<model-id> in source.model. A definition can hold more than one. OpenClaw uses the first llm module as its model. Claude Code, Codex CLI and Antigravity CLI choose their own model, so for them an llm module does not change which model the agent uses. For a custom runtime, llm modules are the models the application may call; see Declare a runtime in an agent definition.
• mcp: Adds an MCP server to the agent's tool surface, reached through the Jozu AI Gateway. A ModelKit source (source.modelkit) is an MCP server bundle that the Jozu gateway runs inside the microVM. An endpoint source (source.endpoint with transport: http or transport: sse) is a remote server the Jozu gateway connects to; headers: adds request headers, whose values can reference needs as ${needs.NAME}. config: fills the options a bundle declares; ${workspace} in a value becomes the mounted workspace path. tools: limits the module to the tools it lists.
• policy: Adds a policy bundle: an OCI artifact containing ToolPolicy and GuardrailPolicy documents, enforced for the session alongside the policies installed with agentguard policy add. A derived definition cannot remove a policy module; it can replace one with a policy module of the same name.
• skill: Adds a skill bundle, packaged as a ModelKit, to the agent's skills directory inside the microVM: ~/.claude/skills for Claude Code, ~/.codex/skills for Codex CLI, ~/.openclaw/skills for OpenClaw, and ~/.gemini/config/skills for Antigravity CLI.

Values from the host

spec.needs lists the values the agent needs from your machine. Agent Guard resolves each need on the host before the microVM boots and sets it as an environment variable in the microVM. A need that an llm module's env references is the exception: it goes to the Jozu gateway only. A need substituted into an mcp module's header reaches both the gateway and the agent's environment:

needs:
  - name: GITHUB_TOKEN              # from the host variable of the same name
  - name: TICKETS_TOKEN
    from:
      envFrom: ACME_TICKETS_PAT     # from a differently named host variable
  - name: TICKET_QUEUE
    from:
      text: platform-oncall         # a literal
  - name: SENTRY_DSN
    optional: true                  # skipped, rather than an error, if unset

A required need that does not resolve stops the run before the microVM boots and names the host variable to set. Needs reach the agent without --pass-env.

Where agent definitions come from

Agent definitions are themselves packed as ModelKits using kit pack and pushed to a registry such as Jozu Hub:

kit pack . -t jozu.ml/myorg/security-review-agent:v1
kit push jozu.ml/myorg/security-review-agent:v1

A ref without a registry host (my-agent:v1, or myorg/my-agent:v1) resolves from your local kit store only. There is no default registry, so a ref meant to be pulled on another machine must name its registry. Local refs are useful for iteration and for air-gapped or offline workflows.

What a definition guarantees

The agent is reproducible. Every run of agentguard run jozu.ml/myorg/security-review-agent:v1 gets the same MCP servers, policies, skills, and needs.

The agent is verifiable. The definition is an OCI artifact with a digest. Sign it with cosign and verify it with --pub-key or agentguard trusted-keys, and Agent Guard checks the definition and each module it pulls before the microVM boots.

The agent is composable. A derived definition names a base in spec.base.modelkit. A module in the derived definition replaces the base's module of the same name, an entry with only a name removes it (except a policy module, which can only be replaced), and new names add modules. A base can carry a security baseline that every derived definition inherits.

What an agent definition is not

It is not a replacement for the per-agent configuration you might already have (such as Claude Code's ~/.claude/). The agent definition layers on top: when a definition specifies an MCP server, Agent Guard writes an entry for it into the agent's own config file inside the microVM at startup: <workspace>/.mcp.json for Claude Code, ~/.codex/config.toml for Codex CLI, and ~/.gemini/config/mcp_config.json for Antigravity CLI. The entry points at the Jozu gateway, not at the server. For Claude Code the file is mounted over <workspace>/.mcp.json inside the microVM, so the entries never reach your host; if the workspace has no .mcp.json, an empty one is created on the host as the mount point. OpenClaw does not load MCP servers from a definition.

It is not the right place for one-off run flags. To pass an extra environment variable for a single run, use --pass-env instead of editing the definition.

See Run with an agent definition for the full flow.