What is AI agent governance?

AI agent governance is the set of policies, controls, and audit mechanisms that decide which agent actions are allowed before they execute. It includes tool selection (which actions are governed), authorization rules (what passes policy), and operator visibility (logs, control plane, policy reload).

Do I need to fork or rewrite my agent to add governance?

No. IntentFrame's Hermes integration uses a plugin that wraps existing tool handlers. The agent proposes actions; IntentFrame validates them; the original handler runs only on ALLOW. You write policy YAML rather than modifying agent source code.

What's the difference between governed tools and policy?

Governed tools control which agent tools are routed through IntentFrame for validation. Policy controls which routed actions are allowed or blocked. A tool must be governed for IntentFrame to see it; a governed tool must then pass policy before it executes.

Deploying AI Agent Governance: A Hermes + IntentFrame Walkthrough

Server racks in a data center — deploying AI agent governance

AI agent governance breaks down in production for predictable reasons: policy lives in prompts, enforcement lives inside the agent, and nobody can answer "what did the agent try to do last Tuesday?"

This walkthrough deploys a working governance stack on Hermes Agent using IntentFrame — external policy enforcement before consequential tools run. No fork, no tool rewrites.

Architecture in 30 seconds

Hermes chat (:9119)          IntentFrame Control Plane (:9720)
       │                              │
       ▼                              ▼
  Hermes gateway              Policy / governance UI
       │
       ▼
 intentframe-gate plugin  →  Adapter (UDS)  →  IntentFrame backend
       │                                              │
       └──── ALLOW → delegate to native handler ◄─────┘
             BLOCK → error returned, action never runs

Four components, three of which run outside Hermes:

Component	Role
intentframe-gate plugin	Wraps governed tools; requires `reason`; validates before delegate
Adapter sidecar	Maps Hermes tool args → IntentFrame validate payloads
IntentFrame backend	Evaluates policy; returns ALLOW/BLOCK
Control plane	Operator UI for stack status, governed tools, policy, audit logs

Hermes chat and the control plane are separate processes and ports. Governance state lives under ~/.intentframe/, never mixed with ~/.hermes/.

Prerequisites

Requirement	Notes
Linux or macOS	Network + curl for install script
OpenAI API key	Required for Hermes chat
~5 minutes	First install includes Hermes if not present

Step 1: Install

One command installs Hermes (if needed), the integration pack, CLI, and control plane:

curl -fsSL https://github.com/intentframe/agent-integrations/raw/main/scripts/install-hermes-plugin.sh | bash

The installer:

Symlinks intentframe-integrations to your PATH
Seeds governance templates under ~/.intentframe/integrations/hermes/
Starts the control plane at http://127.0.0.1:9720

Headless / CI (skip wizard + browser):

curl -fsSL https://github.com/intentframe/agent-integrations/raw/main/scripts/install-hermes-plugin.sh | bash -s -- --headless

Step 2: Start the enforcement stack

export OPENAI_API_KEY=your-openai-api-key
intentframe-integrations up hermes

This starts the IntentFrame backend, Hermes adapter, and gateway — the enforcement stack. It does not start chat UI; that's separate.

Open the control plane:

http://127.0.0.1:9720

Overview shows stack health. /governance lists governed tools. /policy shows active policy. /audit tails the IntentFrame server log.

IntentFrame control plane overview — stack health and governed tools

Step 3: Open Hermes chat

hermes dashboard

http://127.0.0.1:9119/chat

You're now running AI agent governance on the default catalog: terminal, execute_code, write_file, patch, and cronjob.

Step 4: Understand two independent controls

This confuses almost everyone at first. There are two gates:

Control	What it means	Runtime file
Governed tools	Which Hermes tools route through IntentFrame	`~/.intentframe/integrations/hermes/governance/tools.yaml`
Policy	Which routed actions are allowed or blocked	`~/.intentframe/integrations/hermes/policy.yaml`

A tool must be governed for IntentFrame to see it.
A governed tool must then pass policy before it executes.

List governed tools:

intentframe-integrations governance list hermes

Disable governance for a tool (runs native Hermes, no IntentFrame gate):

intentframe-integrations governance disable hermes write_file
intentframe-integrations stop
intentframe-integrations up hermes

Governance changes require restarting the adapter and gateway. Policy changes do not.

Step 5: Write your first policy

IntentFrame policy is deny-by-default. Actions must appear under allowed_actions:

intentframe_schema_version: 1
agent_id: hermes
 
allowed_actions:
  RUN_COMMAND:
    safe: false
    constraints:
      blocked_patterns:
        - sudo
        - "rm -rf /"
      deny_capabilities:
        - "capability:data_read:credential_material"
        - "capability:system_mutate:privilege_config"
 
  WRITE_HOST_FILE:
    safe: false
    constraints:
      allowed_host_paths:
        - "~/*"
 
  DELETE_HOST_FILE:
    safe: false
    constraints:
      allowed_host_paths:
        - "~/*"
 
  HERMES_CRONJOB:
    safe: false
 
intent_limits:
  - limit_id: no-secret-exfil
    domain: data_access
    description: Block reading secrets or credential material
    raw: Do not read credentials, tokens, cookies, secret files, or upload private data to untrusted destinations.
    effect: block

Key concepts:

allowed_actions — action families IntentFrame will consider
constraints — deterministic limits (paths, patterns, capabilities)
intent_limits — plain-English rules for semantic Guardian review
safe: false — consequential; gets full review pipeline

Show current policy:

intentframe-integrations policy show hermes

Apply a custom file:

intentframe-integrations policy set hermes /path/to/my-policy.yaml
intentframe-integrations policy reload hermes

Policy reloads immediately — no gateway restart.

Step 6: Verify governance is working

Run three probes in Hermes chat:

Prompt	Expected
`Use terminal once: sudo echo test`	BLOCK — privilege escalation
`Use write_file once to write "blocked" to /etc/test-probe`	BLOCK — path outside policy
`Use terminal once: ls -la ~`	ALLOW — read-only listing

Check /audit in the control plane. You should see IntentFrame intent boxes with deterministic BLOCK gates for the first two probes.

IntentFrame control plane audit view — intent boxes and block gates

For a full captured session with exact tool payloads and audit log excerpts, see our runtime authorization incident teardown.

Step 6b: Operate day-to-day

Common operator commands:

# Stack lifecycle
intentframe-integrations up hermes
intentframe-integrations stop
intentframe-integrations control-plane status
 
# Policy
intentframe-integrations policy show hermes
intentframe-integrations policy reload hermes
intentframe-integrations policy reset hermes
 
# Governance toggles
intentframe-integrations governance enable hermes terminal
intentframe-integrations governance disable hermes cronjob

Control plane mutations delegate to these CLI commands — governance logic isn't duplicated in the UI.

Production considerations

Start selective. The default catalog covers the highest-risk Hermes tools. Expand governance incrementally; each new tool needs mapper + policy work, not just a yaml toggle.

Separate operator access from agent access. Control plane binds to 127.0.0.1 by default. Set INTENTFRAME_CONTROL_PLANE_TOKEN before exposing beyond localhost.

Treat audit logs as source of truth. When an action is blocked, the IntentFrame server log records the gate (deterministic constraint, command shield, or semantic Guardian) independently of what the model tells the user.

Plan for autonomous tools. cronjob governance matters because scheduled agents act without a human in the loop. A cron job that passes policy at creation time still runs under the same governance stack on each execution.

What you deployed

In fifteen minutes you moved from prompt-based hope to AI agent governance with:

External authorization before shell, file, code, and cron actions
Declarative policy you can reload without redeploying Hermes
An operator control plane with audit visibility
A validate-only model: IntentFrame judges; Hermes executes locally after ALLOW

That's the minimum viable governance stack — structural separation, not more instructions.

Image credits

Photos from Unsplash (license):

Hero: imgix

Control plane screenshots are from the IntentFrame Hermes integration product UI.

Frequently asked questions

What is AI agent governance?: AI agent governance is the set of policies, controls, and audit mechanisms that decide which agent actions are allowed before they execute. It includes tool selection (which actions are governed), authorization rules (what passes policy), and operator visibility (logs, control plane, policy reload).
Do I need to fork or rewrite my agent to add governance?: No. IntentFrame's Hermes integration uses a plugin that wraps existing tool handlers. The agent proposes actions; IntentFrame validates them; the original handler runs only on ALLOW. You write policy YAML rather than modifying agent source code.
What's the difference between governed tools and policy?: Governed tools control which agent tools are routed through IntentFrame for validation. Policy controls which routed actions are allowed or blocked. A tool must be governed for IntentFrame to see it; a governed tool must then pass policy before it executes.

Ready to put a boundary around your agent's actions?

See how IntentFrame checks every action against hard limits and plain-English policy before it runs. Related GitHub repos you might want to check: IntentFrame core · Hermes agent integration

Explore IntentFrame