> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mirage.strukto.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Claude Managed Agents in Python

> Make a Mirage workspace the self-hosted environment of an agent on Claude Managed Agents.

[Claude Managed Agents](https://platform.claude.com/docs/en/managed-agents/overview) runs the agent loop on Anthropic's servers. In a [self-hosted environment](https://platform.claude.com/docs/en/managed-agents/self-hosted-sandboxes), a worker on private infrastructure runs the agent's tool calls. `mirage_tools(ws)` gives that worker Mirage's `bash`, `read`, `write`, `edit`, `glob` and `grep`, so every call runs in the workspace, under its profile, mounts and policies. The worker only connects out to Anthropic.

## Install

```bash theme={null}
uv add 'mirage-ai[claude-managed-agents]'
```

## Usage

Create a self-hosted environment, generate its environment key, and create an agent with the `agent_toolset_20260401` toolset, as [Anthropic's guide](https://platform.claude.com/docs/en/managed-agents/self-hosted-sandboxes) shows. Then serve the environment's sessions from a workspace:

```python theme={null}
import asyncio
import os

from anthropic import AsyncAnthropic
from anthropic.lib.environments import EnvironmentWorker

from mirage import MountMode, RAMVFS, Workspace
from mirage.agents.claude_managed_agents import mirage_tools


async def main() -> None:
    ws = Workspace({"/workspace": RAMVFS()}, mode=MountMode.WRITE)
    environment_key = os.environ["ANTHROPIC_ENVIRONMENT_KEY"]
    try:
        async with AsyncAnthropic(auth_token=environment_key) as client:
            await EnvironmentWorker(
                client,
                environment_id=os.environ["ANTHROPIC_ENVIRONMENT_ID"],
                environment_key=environment_key,
                tools=mirage_tools(ws),
            ).run()
    finally:
        await ws.close()


asyncio.run(main())
```

The worker authenticates with the environment key alone, so the Claude API key stays off the worker's machine. Create sessions that target the environment from anywhere else; the worker claims each one and answers its tool calls.

## Tools

* The tools keep the toolset's names. One the session's [profile](https://docs.mirage.strukto.ai/home/policy/overview.md) would always refuse is left out: a read-only workspace gets no `write` or `edit`.
* `bash` runs Mirage's shell, so a line sees the workspace's mounts and commands, not the worker's machine. A `restart` is refused, since the session keeps its directory and variables. A relative path resolves against the session's working directory, which `cd` moves.
* `write` overwrites a file only after the agent read all of it, and `write` and `edit` refuse a file that changed since the agent read it. `stale_write_protection=False` turns that off.
* `session_id=` runs the tools as another session, with its profile.
* `web_search` and `web_fetch` still run on Anthropic's servers. Turn them off in the agent's toolset to keep the agent to the workspace.

## Exports

| Symbol | Purpose |
| - | - |
| `mirage_tools` | The agent toolset's file and shell tools, run in a Mirage session. |

## Examples

* [`redis_report.py`](https://github.com/strukto-ai/mirage/blob/main/examples/python/agents/claude_managed_agents/redis_report.py) creates the agent and a session, serves the session from a RAM and Redis workspace, asks the agent to total `/workspace/orders.csv` into `/redis/report.md`, and prints the report from Redis.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.