Shadow Agent Quarantine

​

How It Works

1. An admin calls POST /agents/{id}/quarantine with a reason after identifying an unknown or suspicious agent.
2. The API marks the agent quarantined in the database and also writes a block to Redis for instant proxy enforcement.
3. The proxy blocks all subsequent requests from the quarantined agent with 403 Forbidden.
4. An admin reviews the agent and calls POST /agents/{id}/release-quarantine to restore access.

​

Quarantine an Agent

curl -X POST https://api.meshai.dev/api/v1/agents/01ARZ3NDEKTSV4RRFFQ69G5FAV/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"
  }'

from meshai import MeshAI

client = MeshAI(api_key="msh_...")

client.quarantine_agent(
    agent_id="01ARZ3NDEKTSV4RRFFQ69G5FAV",
    reason="Unknown agent detected making requests to OpenAI - not in registry",
)

{
  "success": true,
  "data": {
    "agent_id": "01ARZ3NDEKTSV4RRFFQ69G5FAV",
    "quarantined": true,
    "reason": "Unknown agent detected making requests to OpenAI - not in registry"
  }
}

​

Release from Quarantine

curl -X POST https://api.meshai.dev/api/v1/agents/01ARZ3NDEKTSV4RRFFQ69G5FAV/release-quarantine \
  -H "Authorization: Bearer msh_YOUR_API_KEY"

client.release_quarantine(agent_id="01ARZ3NDEKTSV4RRFFQ69G5FAV")

{
  "success": true,
  "data": {
    "agent_id": "01ARZ3NDEKTSV4RRFFQ69G5FAV",
    "quarantined": false
  }
}

​

List Quarantined Agents

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

quarantined = client.list_quarantined_agents()

{
  "success": true,
  "data": [
    {
      "id": "01ARZ3NDEKTSV4RRFFQ69G5FAV",
      "name": "unknown-agent-7",
      "quarantine_reason": "Unknown agent detected making requests to OpenAI - not in registry",
      "registered_at": "2026-03-10T09:00:00Z"
    }
  ]
}

​

What the Agent Sees

{
  "error": "Agent is blocked: quarantined: Unknown agent detected making requests to OpenAI - not in registry"
}

​

Audit Trail

​

Enforcement Architecture

• Write path: API writes quarantine status to PostgreSQL and publishes a block 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

​

Use Cases

• Shadow agent response - Quarantine agents you discover are not in the registry.
• Onboarding gate - Quarantine new agents until reviewed by security.
• Incident containment - Quarantine suspicious agents while investigating.
• Zero-trust enforcement - No agent gets proxy access without explicit registration and review.