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

> Connect Claude Code to a Mirage workspace through its shell, MCP or a FUSE mount.

| Way | Claude Code gets | Needs |
| - | - | - |
| [Shell](#shell) | its own Bash, run in the workspace | the `mirage` CLI |
| [MCP](#mcp) | Mirage's seven tools, beside its own | the `mirage` CLI, or Node.js for the plugin |
| [FUSE](#fuse) | its own tools, on the workspace as a folder | the `mirage` CLI and a [FUSE driver](https://docs.mirage.strukto.ai/home/setup/fuse.md) |

## Install

```bash uv theme={null}
uv tool install mirage-ai
```

```bash npm theme={null}
npm install -g @struktoai/mirage-cli
```

Both install `mirage` and [`mirage-bash`](https://docs.mirage.strukto.ai/home/access/cli#mirage-bash). Install [Claude Code](https://docs.claude.com/en/docs/claude-code/setup) 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:

```yaml workspace.yaml theme={null}
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.

```bash theme={null}
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:

```json .claude/settings.json theme={null}
{
  "env": {
    "CLAUDE_CODE_SHELL": "/Users/me/.local/bin/mirage-bash",
    "MIRAGE_WORKSPACE": "demo"
  }
}
```

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

```bash theme={null}
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](https://docs.mirage.strukto.ai/home/profiles.md), define it in the workspace:

```yaml workspace.yaml theme={null}
profiles:
  reviewer:
    mounts:
      /data: { mode: read }
  builder: {}
```

Then create a session under it and name the session:

```bash theme={null}
mirage session create demo --id agent -p reviewer
```

```json .claude/settings.json theme={null}
{
  "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](#mcp) and deny them, or use [FUSE](#fuse).

## MCP

**Plugin**

```text theme={null}
/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`.

**mirage mcp**

```bash theme={null}
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](https://docs.mirage.strukto.ai/home/access/mcp.md), beside its own tools.

With [Shell](#shell), serve the same session and deny the tools that would bypass it:

```bash theme={null}
claude mcp add mirage -- mirage mcp -w demo -s agent
```

```json .claude/settings.json theme={null}
{
  "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](https://docs.mirage.strukto.ai/home/setup/fuse.md). With uv, install `'mirage-ai[fuse]'`; with npm on macOS, also follow the [macFUSE 4 workaround](https://docs.mirage.strukto.ai/typescript/setup/fuse.md#macfuse-4-symlink-workaround). Then expose the workspace at a local folder:

```yaml workspace.yaml theme={null}
mounts:
  /:
    vfs: ram
    mode: write
    backend: fuse
    mountpoint: /tmp/mirage-demo
```

```bash theme={null}
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.


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