Claude Code

Way	Claude Code gets	Needs
Shell	its own Bash, run in the workspace	the `mirage` CLI
MCP	Mirage’s seven tools, beside its own	the `mirage` CLI, or Node.js for the plugin
FUSE	its own tools, on the workspace as a folder	the `mirage` CLI and a FUSE driver

Install

uv tool install mirage-ai

npm install -g @struktoai/mirage-cli

Both install mirage and mirage-bash. Install Claude Code separately.

Shell

mirage-bash takes the place of bash, so every command Claude Code’s Bash tool runs goes to a workspace session. Mount the project and /tmp at their own paths, beside your data:

workspace.yaml

mounts:
  /Users/me/project: { vfs: disk, mode: write, config: { root: /Users/me/project } }
  /tmp: { vfs: disk, mode: write, config: { root: /tmp } }
  /data: { vfs: ram, mode: write }

The project mount gives Claude’s Bash and its own Read and Edit tools the same files at the same paths.
Claude Code keeps its working directory in /tmp between commands, so cd carries over.

mirage workspace create workspace.yaml --id demo

Point Claude Code at it in the project’s settings, with the path command -v mirage-bash prints:

.claude/settings.json

{
  "env": {
    "CLAUDE_CODE_SHELL": "/Users/me/.local/bin/mirage-bash",
    "MIRAGE_WORKSPACE": "demo"
  }
}

Then run claude in the project. For one run instead:

MIRAGE_WORKSPACE=demo CLAUDE_CODE_SHELL="$(command -v mirage-bash)" claude

Session and profile

Commands run as the workspace’s default session. To run them under a profile, define it in the workspace:

workspace.yaml

profiles:
  reviewer:
    mounts:
      /data: { mode: read }
  builder: {}

Then create a session under it and name the session:

mirage session create demo --id agent -p reviewer

.claude/settings.json

{
  "env": {
    "CLAUDE_CODE_SHELL": "/Users/me/.local/bin/mirage-bash",
    "MIRAGE_WORKSPACE": "demo",
    "MIRAGE_SESSION": "agent"
  }
}

Each command runs in a copy of the session, from Claude’s working directory. cd carries over, since Claude Code tracks it; export lasts for that one command, as in Claude Code’s own shell.
The profile applies to every command. A line it refuses fails whole, with exit 126 and the reason on stderr.
mirage session update demo agent -p builder moves the session to another profile while Claude runs.

Claude Code’s Read, Edit, Write, Glob and Grep still run on the host, outside the profile. To route them through Mirage too, add MCP and deny them, or use FUSE.

MCP

Plugin
mirage mcp

/plugin marketplace add strukto-ai/mirage
/plugin install mirage@mirage

The plugin adds a filesystem skill, a VFS authoring skill and an MCP server that runs npx -y @struktoai/mirage-cli mcp on your project’s .mirage/workspace.yaml.

claude mcp add mirage -- mirage mcp -w demo

Add -s agent to serve the tools as a session, under its profile.

Claude Code gets shell, read, write, edit, ls, grep and glob from the workspace’s MCP server, beside its own tools. With Shell, serve the same session and deny the tools that would bypass it:

claude mcp add mirage -- mirage mcp -w demo -s agent

.claude/settings.json

{
  "permissions": {
    "deny": ["Read", "Edit", "Write", "Glob", "Grep", "mcp__mirage__shell"]
  }
}

Claude then reads and edits through Mirage’s tools and runs commands through its own Bash, all as session agent.

FUSE

Install your platform’s FUSE driver. With uv, install 'mirage-ai[fuse]'; with npm on macOS, also follow the macFUSE 4 workaround. Then expose the workspace at a local folder:

workspace.yaml

mounts:
  /:
    vfs: ram
    mode: write
    backend: fuse
    mountpoint: /tmp/mirage-demo

mirage workspace create workspace.yaml --id demo-fuse
cd /tmp/mirage-demo && claude

File operations inside /tmp/mirage-demo go through Mirage, with Claude’s own tools. The mount does not restrict the agent’s access to other host paths. mirage workspace delete demo-fuse unmounts it. On macOS the daemon holds one FUSE mount at a time.

Getting Started

Agents

VFS

Integration

CLIs

Mirage Shell

Agent Profiles

Policy

Runtimes

Configuration

Notifications

Help

Install

Shell

Session and profile

MCP

FUSE

​Install

​Shell

​Session and profile

​MCP

​FUSE

Install

Shell

Session and profile

MCP

FUSE