Skip to main content
Shadow agent quarantine lets you isolate unknown or suspicious agents from making LLM requests. Quarantined agents are blocked at the proxy layer via Redis — the same enforcement mechanism as the kill switch, but designed specifically for governance of unregistered or rogue agents.

​
How It Works

  1. When the proxy sees a request from an unknown agent (not in the registry), it can auto-quarantine the agent.
  2. A quarantine record is created with a reason and timestamp.
  3. The proxy blocks all subsequent requests from the quarantined agent with 403 Forbidden.
  4. An admin reviews the agent and either releases it from quarantine or permanently blocks it.

​
Quarantine an Agent

curl -X POST https://api.meshai.dev/agents/agt_unknown_7/quarantine \
  -H "Authorization: Bearer msh_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "reason": "Unknown agent detected making requests to OpenAI — not in registry"
  }'

{
  "success": true,
  "data": {
    "agent_id": "agt_unknown_7",
    "status": "quarantined",
    "reason": "Unknown agent detected making requests to OpenAI — not in registry",
    "quarantined_at": "2026-03-18T14:30:00Z",
    "quarantined_by": "system"
  }
}

​
Release from Quarantine

After reviewing a quarantined agent, release it to restore proxy access: 
curl -X POST https://api.meshai.dev/agents/agt_unknown_7/release-quarantine \
  -H "Authorization: Bearer msh_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

{
  "success": true,
  "data": {
    "agent_id": "agt_unknown_7",
    "status": "active",
    "released_at": "2026-03-18T15:00:00Z",
    "released_by": "admin@company.com"
  }
}

​
List Quarantined Agents

curl https://api.meshai.dev/agents/quarantined \
  -H "Authorization: Bearer msh_YOUR_API_KEY"

{
  "success": true,
  "data": [
    {
      "id": "agt_unknown_7",
      "name": "unknown-agent-7",
      "status": "quarantined",
      "reason": "Unknown agent detected making requests to OpenAI — not in registry",
      "quarantined_at": "2026-03-18T14:30:00Z",
      "request_count": 47,
      "estimated_cost_usd": 12.40
    }
  ],
  "meta": {
    "total": 1,
    "page": 1,
    "limit": 25
  }
}

​
What the Agent Sees

When a quarantined agent sends a request through the proxy: 
{
  "error": "Agent quarantined: Unknown agent detected making requests to OpenAI — not in registry",
  "agent_id": "agt_unknown_7",
  "status": 403
}

​
Audit Trail

Every quarantine action is logged:
Event TypeDescription
agent.quarantinedAgent placed in quarantine (includes reason and actor)
agent.quarantine.releasedAgent released from quarantine (includes actor)
Query quarantine-related events: 
curl "https://api.meshai.dev/governance/audit-trail?event_type=agent.quarantined" \
  -H "Authorization: Bearer msh_YOUR_API_KEY"

​
Enforcement Architecture

Quarantine uses the same Redis-backed enforcement as the kill switch:
  • Write path: API writes quarantine status to PostgreSQL and publishes to Redis.
  • Read path: Proxy checks Redis on every request — quarantined agents get an immediate 403.
  • Fail-open: If Redis is unavailable, the proxy falls back to allowing the request.
  • Latency: Quarantine takes effect within milliseconds of the API call.

​
Quarantine vs Kill Switch

FeatureQuarantineKill Switch
PurposeIsolate unknown/suspicious agents for reviewEmergency shutdown of known agents
TriggerAuto-detected shadow agents or manualManual or anomaly-driven
Release flowReview then releaseUnblock when resolved
Audit eventagent.quarantinedagent.blocked

​
Use Cases

  • Shadow agent detection — Auto-quarantine agents not in the registry.
  • Onboarding gate — New agents start quarantined until approved by security.
  • Incident containment — Quarantine suspicious agents while investigating.
  • Zero-trust enforcement — No agent gets proxy access without explicit registration and approval.