> ## 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.

# Shadow Agent Quarantine

> Quarantine unknown or suspicious agents and control their access through the proxy

Shadow agent quarantine lets you isolate unknown or suspicious agents from making LLM requests. Quarantine is a manual admin action - the same Redis-backed enforcement as the kill switch, but tracked and labeled separately for governance of unregistered or rogue agents.

## 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.

<Note>
  Quarantine is not applied automatically today - there is no auto-quarantine of newly discovered shadow agents. An admin decides to quarantine an agent explicitly.
</Note>

## Quarantine an Agent

<CodeGroup>
  ```bash curl theme={null}
  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"
    }'
  ```

  ```python SDK theme={null}
  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",
  )
  ```
</CodeGroup>

<ResponseExample>
  ```json Response theme={null}
  {
    "success": true,
    "data": {
      "agent_id": "01ARZ3NDEKTSV4RRFFQ69G5FAV",
      "quarantined": true,
      "reason": "Unknown agent detected making requests to OpenAI - not in registry"
    }
  }
  ```
</ResponseExample>

## Release from Quarantine

After reviewing a quarantined agent, release it to restore proxy access:

<CodeGroup>
  ```bash curl theme={null}
  curl -X POST https://api.meshai.dev/api/v1/agents/01ARZ3NDEKTSV4RRFFQ69G5FAV/release-quarantine \
    -H "Authorization: Bearer msh_YOUR_API_KEY"
  ```

  ```python SDK theme={null}
  client.release_quarantine(agent_id="01ARZ3NDEKTSV4RRFFQ69G5FAV")
  ```
</CodeGroup>

<ResponseExample>
  ```json Response theme={null}
  {
    "success": true,
    "data": {
      "agent_id": "01ARZ3NDEKTSV4RRFFQ69G5FAV",
      "quarantined": false
    }
  }
  ```
</ResponseExample>

## List Quarantined Agents

<CodeGroup>
  ```bash curl theme={null}
  curl https://api.meshai.dev/api/v1/agents/quarantined \
    -H "Authorization: Bearer msh_YOUR_API_KEY"
  ```

  ```python SDK theme={null}
  quarantined = client.list_quarantined_agents()
  ```
</CodeGroup>

<ResponseExample>
  ```json Response theme={null}
  {
    "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"
      }
    ]
  }
  ```
</ResponseExample>

## What the Agent Sees

When a quarantined agent sends a request through the proxy:

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

## Audit Trail

Quarantine and release actions do not currently emit their own audit events. If you need a record of quarantine actions, track them through your own tooling around the API calls, or query the agent's current `quarantine_reason` via `GET /agents/quarantined`.

## Enforcement Architecture

Quarantine uses the same Redis-backed enforcement as the kill switch:

* **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

| Feature          | Quarantine                                   | Kill Switch                         |
| ---------------- | -------------------------------------------- | ----------------------------------- |
| **Purpose**      | Isolate unknown/suspicious agents for review | Block a known agent immediately     |
| **Trigger**      | Manual admin action                          | Manual admin action                 |
| **Release flow** | Review then release                          | Unblock when resolved               |
| **Audit event**  | None today                                   | `agent.blocked` / `agent.unblocked` |

## 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.