Run with an agent definition

This guide walks through the full loop: write a small agent definition, pack it into your local kit store, and run it with Agent Guard. No Hub access is needed until you share it.

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
  includes:
    - 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.0
package:
  name: my-claude-agent
  version: 1.0.0
  description: My first agent definition
code:
  - path: agent-definition.yaml

Step 2: Pack it into your local kit store

From the my-agent/ directory:

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

This produces an OCI artifact in your local kit store, with no network calls. List your local artifacts to confirm:

kit list

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

Step 3: Run it

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

The definition's framework selects Claude Code, so no agent name is needed. Agent Guard then works in three steps:

1. Resolve. It pulls my-claude-agent:v1 from your local kit store, reads the YAML, and walks any base definition it inherits from (there is none in this example).
2. Admit. The definition and every module's source reference are evaluated against the ArtifactPolicy documents you have installed with agentguard policy add, and verified against your cosign keys if you have configured any. Any reference that fails either check blocks the run before the microVM boots. Agent Guard ships with no ArtifactPolicy, so with none installed and no keys configured, every reference passes. See Use pre-built policy tiers for how to add registry trust.
3. Boot. Agent Guard pulls the modules, boots the microVM with the policy bundle loaded into the Jozu AI Gateway, and starts Claude Code. The run header lists the policy under [agent], with the digest it was pulled at.

How the policy module applies

A policy module is pulled for this run and loaded into the Jozu gateway when the microVM boots, alongside the policies installed with agentguard policy add. Its ToolPolicy and GuardrailPolicy rules apply for the whole session. It is not saved as a policy source, so agentguard policy list does not show it. For what each module type does, see What an agent definition is.

Add an MCP server

Update the definition to include an MCP module:

spec:
  framework: claude-code
  includes:
    - name: filesystem
      type: mcp
      source:
        modelkit: jozu.ml/myorg/filesystem-mcp:v1
      config:
        allowed_directories: ${workspace}

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

config sets the options the MCP bundle declares. ${workspace} is replaced with the mounted workspace path inside the microVM.

For an MCP server you reach over HTTP rather than as a packed bundle, declare the credential as a need and reference it in a header:

spec:
  framework: claude-code
  needs:
    - name: GITHUB_TOKEN
  includes:
    - name: github
      type: mcp
      source:
        endpoint: https://mcp.example.com/mcp
      transport: http
      headers:
        Authorization: "Bearer ${needs.GITHUB_TOKEN}"

Agent Guard reads GITHUB_TOKEN from your environment before the microVM boots, and the Jozu gateway sends it on every request to that server. The need is also set in the agent's environment. If the variable is not set, the run stops and says which one to set. You do not need --pass-env for it.

After editing, repack and re-run:

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

Push to a Hub

Once the definition is working locally, push it to Jozu Hub so it can be pulled from any machine. See Pushing and pulling ModelKits for the full Kit CLI flow.

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

Anyone with access to the repository can run:

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

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

Next steps

• Common errors: agent definitions covers framework mismatches, missing needs, ArtifactPolicy blocks, and local store visibility.
• What an agent definition is describes every module type, needs, and inheritance from a base definition.
• Custom agent runtimes run your own application from a definition in place of an agent CLI.