Run with an agent definition

This guide walks through the full loop: write a small agent definition, pack it into a local OCI artifact, and run it with Agent Guard. No Hub access required.

Prerequisites

• Agent Guard installed (see Quickstart).
• The kit CLI installed. Get it from kitops.org or brew install kitops.
• A workspace directory.

Step 1: Write the definition

Create a directory for the agent and add two files. The agent definition itself:

# my-agent/agent-definition.yaml
apiVersion: agentguard.jozu.dev/v1
kind: AgentDefinition
metadata:
  name: my-claude-agent
spec:
  framework: claude-code
  modules:
    - name: primary-llm
      type: llm
      source:
        model: anthropic/claude-sonnet-4-20250514
      auth:
        key: env.ANTHROPIC_API_KEY

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

And a Kitfile so kit knows what to pack:

# my-agent/Kitfile
manifestVersion: "1.0"
package:
  name: my-claude-agent
  version: v1
  description: My first agent definition
code:
  - path: agent-definition.yaml

Step 2: Pack it as a local OCI artifact

From the my-agent/ directory:

kit pack . -t my-claude-agent:v1

This produces an OCI artifact in your local kit store. No network calls. No Hub required. List your local artifacts to confirm:

kit list

You should see my-claude-agent:v1 in the output.

Step 3: Run with --agent-ref

agentguard run claude-code --agent-ref my-claude-agent:v1 --workspace ~/projects/myapp

Two things happen before the agent starts.

Agent Guard resolves the agent definition. It pulls my-claude-agent:v1 from your local kit store, reads the YAML, and walks any base inheritance (there is none in this example). Each module's source is recorded.

Agent Guard runs admission checks. Every module's source ref is evaluated against any ArtifactPolicy you have loaded. If a module references a registry you have not trusted, the run is blocked before the microVM boots. By default, Agent Guard ships with no ArtifactPolicy, so local refs and jozu.ml refs both pass. See Use pre-built policy tiers for how to add registry trust.

Once admission passes, the microVM boots, the policy bundle is loaded into the Agent Guard AI Gateway, and Claude Code starts with the configured LLM.

What happens with each module type

Each module type lands in a different place inside the microVM.

• llm modules configure the agent's LLM provider. For Claude, that means the model selection and the API key come from the agent definition rather than from whatever defaults Claude Code would otherwise use.
• mcp modules are written into the framework-specific MCP config file: workspace/.mcp.json for Claude Code, ~/.gemini/settings.json for Gemini, ~/.codex/config.toml for Codex. The agent picks them up on startup. The MCP server itself is either pulled from the registry and run locally inside the microVM, or wired to the remote endpoint, depending on the module's source.
• policy modules are unpacked into the policy directory the gateway watches. Their rules are evaluated on every tool call and every artifact pull during the agent's session, alongside any policies installed via agentguard policy add.
• skill modules are unpacked into the agent's skills directory inside the microVM. For Claude Code that means slash commands like /security-audit become available immediately.

Add an MCP server

Update the definition to include an MCP module:

spec:
  framework: claude-code
  modules:
    - name: primary-llm
      type: llm
      source:
        model: anthropic/claude-sonnet-4-20250514
      auth:
        key: env.ANTHROPIC_API_KEY

    - name: filesystem
      type: mcp
      source:
        modelkit: myorg/filesystem-mcp:v1
      config:
        allowed_directories: ${workspace}

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

The ${workspace} interpolation is substituted at runtime with the mounted workspace path inside the microVM.

For an MCP server you have access to over HTTP rather than as a packed bundle:

    - name: github
      type: mcp
      source:
        endpoint: https://mcp.github.com/mcp
      transport: http
      auth:
        type: headers
        headers:
          Authorization: env.GITHUB_TOKEN

The env.GITHUB_TOKEN reference is resolved against the host environment at run time, and Agent Guard passes the value into the microVM. You will need to also pass the variable explicitly with --pass-env GITHUB_TOKEN, or set up the credential in the agent's authentication chain.

After editing, repack and re-run:

kit pack . -t my-claude-agent:v2
agentguard run claude-code --agent-ref my-claude-agent:v2 --workspace ~/projects/myapp

Push to a Hub

Once the definition is working locally, push it to your Hub so teammates can pull it. See Pushing and pulling ModelKits for the full Kit CLI flow.

kit login jozu.ml
kit push my-claude-agent:v1 jozu.ml/yourorg/my-claude-agent:v1

Teammates can now run:

agentguard run claude-code --agent-ref jozu.ml/yourorg/my-claude-agent:v1 --workspace ~/projects/myapp

For private Hub installations, replace jozu.ml with your Hub's domain.

Common errors

See the Agent definitions section of Common errors for framework mismatches, missing auth variables, ArtifactPolicy blocks, and local store visibility issues.