Skip to main content
The Claude Agent SDK builds agents on the same loop as Claude Code. Mirage hands it a Workspace as an in-process MCP server, so every file and shell call the agent makes runs in the workspace, not on the host. To run the claude CLI itself on a workspace, see Claude Code.

Install

Usage

build_options returns a ClaudeAgentOptions that registers the Mirage server, turns off Claude’s built-in tools, allows Mirage’s and sets a system prompt describing the mounts:
build_options(ws, session_id="agent") runs the tools as that session, under its profile. Create the session first with ws.session. system_prompt= replaces the default prompt.

Tools

The server serves the session’s seven tools, session.tools: shell, read, write, edit, ls, grep and glob, named mcp__mirage__<tool> in the SDK. It carries only the ones the session’s profile leaves it, so a read-only workspace gets no write or edit.

Other MCP servers

MirageServer is the server alone. Put it next to other servers in a ClaudeAgentOptions of its own:
tools=[] keeps Claude’s built-in tools out, and allowed_tools lets the listed servers run without a permission prompt.

Keep Claude’s Bash

To keep Claude’s own Bash tool and run it in a workspace, point the SDK at mirage-bash, as for Claude Code. Mirage’s other tools come over mirage mcp in place of Claude’s file tools. Both reach one workspace that the Mirage daemon serves:
  • Bash runs in the workspace. Mirage’s read, write, edit, ls, grep and glob replace Claude’s Read, Edit, Write, Glob and Grep, so every file the agent touches goes through Mirage.
  • Mount the project and /tmp at their own paths, as the Claude Code page shows, so cd carries over.
  • To run under a profile, create a session with mirage workspace session create -w demo -s agent -p reviewer, set MIRAGE_SESSION to agent and add -s agent to the mirage mcp arguments.

Exports

Examples

  • all_tools.py has a Sonnet agent call each of the seven tools on a RAM workspace and checks the file it leaves.