Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.meshai.dev/llms.txt

Use this file to discover all available pages before exploring further.

The kill switch lets you immediately block an agent from making any LLM requests through the MeshAI proxy. Blocks are cached in Redis for instant enforcement — the proxy returns 403 Forbidden for any request from a blocked agent.

​
How It Works

  1. You call POST /agents/{id}/block with a reason.
  2. The API writes the block to the database and publishes it to Redis.
  3. The proxy checks Redis on every incoming request — blocked agents get an immediate 403.
  4. An agent.blocked audit event is emitted automatically.
  5. To restore access, call POST /agents/{id}/unblock — an agent.unblocked event is emitted.

​
Block an Agent

curl -X POST https://api.meshai.dev/agents/agt_abc123/block \
  -H "Authorization: Bearer msh_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "reason": "Anomalous behavior detected — cost spike 10x above baseline"
  }'

{
  "success": true,
  "data": {
    "agent_id": "agt_abc123",
    "status": "blocked",
    "reason": "Anomalous behavior detected — cost spike 10x above baseline",
    "blocked_at": "2026-03-18T14:30:00Z",
    "blocked_by": "user@company.com"
  }
}

​
Unblock an Agent

curl -X POST https://api.meshai.dev/agents/agt_abc123/unblock \
  -H "Authorization: Bearer msh_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

{
  "success": true,
  "data": {
    "agent_id": "agt_abc123",
    "status": "active",
    "unblocked_at": "2026-03-18T15:00:00Z",
    "unblocked_by": "user@company.com"
  }
}

​
What the Agent Sees

When a blocked agent sends a request through the proxy, it receives: 
{
  "error": "Agent blocked: Anomalous behavior detected — cost spike 10x above baseline",
  "agent_id": "agt_abc123",
  "status": 403
}
This is compatible with all LLM SDK error handling — OpenAI, Anthropic, and other clients will raise their standard authentication/permission errors.

​
Audit Trail

Every block and unblock action emits an audit event:
Event TypeDescription
agent.blockedAgent was blocked (includes reason and actor)
agent.unblockedAgent block was removed (includes actor)
Query block-related audit events: 
curl "https://api.meshai.dev/governance/audit-trail?event_type=agent.blocked" \
  -H "Authorization: Bearer msh_YOUR_API_KEY"

​
Enforcement Architecture

The kill switch uses Redis for sub-millisecond enforcement:
  • Write path: API writes block to PostgreSQL and publishes to Redis.
  • Read path: Proxy checks Redis on every request (before policy evaluation).
  • Fail-open: If Redis is unavailable, the proxy falls back to allowing the request (same as policy cache behavior).
  • Latency: Block takes effect within milliseconds of the API call.

​
Use Cases

  • Incident response — Immediately stop a compromised or malfunctioning agent.
  • Cost containment — Block an agent that is burning through budget unexpectedly.
  • Compliance — Emergency shutdown to satisfy regulatory requirements (EU AI Act Article 14).
  • Anomaly response — Automated block triggered by anomaly detection (coming soon).