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

# ACP

> Run an ACP agent on a Mirage workspace from Zed, a JetBrains IDE, t3code or another ACP client, with no machine.

The [Agent Client Protocol](https://agentclientprotocol.com) is how an app
such as Zed, a JetBrains IDE or t3code drives a coding agent: the app starts the
agent and the two talk JSON-RPC over the agent's stdin and stdout.
`mirage acp` goes in place of the agent's command and starts the agent itself:

```text theme={null}
ACP client ◀── ACP ──▶ mirage acp ◀── ACP ──▶ agent
                           │                    │
                     file requests          MCP tools
                           └───▶ workspace ◀────┘
```

ACP carries the conversation: prompts, replies, tool calls and permission
requests, which pass through unchanged. The agent reaches the workspace two
ways underneath:

| When the agent | It goes through |
| - | - |
| Asks the client for a file (`fs/read_text_file`, `fs/write_text_file`) | `mirage acp`, which answers from the workspace and does not pass the request on |
| Calls `shell`, `read`, `write`, `edit`, `ls`, `grep` or `glob` | MCP, to the `mirage mcp` server added to its session |

Claude never asks the client for files, and its built-in tools are turned
off, so it works over MCP alone. Gemini CLI writes and edits files through
the client, but reads them and runs commands with its own tools.

The agent runs where the client starts it and nothing is uploaded, so no
[machine](https://docs.mirage.strukto.ai/home/setup/machine/overview.md) is needed. A workspace on a hosted
server works the same way, reached with the CLI's
[login](https://docs.mirage.strukto.ai/home/access/cli.md#log-in).

## Clients

| Client | Where the command goes |
| - | - |
| ![](https://mintcdn.com/struktoai/ZJtCSXqvSorId2ye/images/zed-logo.svg?fit=max\&auto=format\&n=ZJtCSXqvSorId2ye\&q=85\&s=1e85d240426ed459f97ac225cc378d7e)Zed | `agent_servers` in `~/.config/zed/settings.json`, with `"type": "custom"` |
| ![](https://mintcdn.com/struktoai/ZJtCSXqvSorId2ye/images/jetbrains-logo.svg?fit=max\&auto=format\&n=ZJtCSXqvSorId2ye\&q=85\&s=f611dbfa6f7bf525ec4d5ba09b528d65)JetBrains IDEs | `agent_servers` in `~/.jetbrains/acp.json` |
| ![](https://mintcdn.com/struktoai/ZJtCSXqvSorId2ye/images/t3code-logo.svg?fit=max\&auto=format\&n=ZJtCSXqvSorId2ye\&q=85\&s=17dcbcf84a232c59ca5077be7ddc8086)t3code | A local ACP command: see [t3code](https://docs.mirage.strukto.ai/home/agents/t3code.md) |

## Agents

| Agent | Its ACP command, after `--` |
| - | - |
| ![](https://mintcdn.com/struktoai/F9Lv_nTaj6By6crk/images/claude-logo.svg?fit=max\&auto=format\&n=F9Lv_nTaj6By6crk\&q=85\&s=24f21eb989bc7b3119bbd5d6cc6aa758)Claude | `claude-agent-acp`, from npm `@agentclientprotocol/claude-agent-acp` |
| ![](https://mintcdn.com/struktoai/F9Lv_nTaj6By6crk/images/openai-logo.svg?fit=max\&auto=format\&n=F9Lv_nTaj6By6crk\&q=85\&s=086e9344aa70f87e32186cd834e92dfb)Codex | `codex-acp`, from npm `@agentclientprotocol/codex-acp` |
| ![](https://mintcdn.com/struktoai/ZJtCSXqvSorId2ye/images/gemini-logo.svg?fit=max\&auto=format\&n=ZJtCSXqvSorId2ye\&q=85\&s=7a65caec09903ada19fc62e5c4e3adb2)Gemini CLI | `gemini --acp` |
| ![](https://mintcdn.com/struktoai/UoY6QG60_Zn_sW0e/images/grok-logo.svg?fit=max\&auto=format\&n=UoY6QG60_Zn_sW0e\&q=85\&s=6b7bae5219e20865c78f2a088d3de87f)Grok Build | `grok agent stdio` |
| ![](https://mintcdn.com/struktoai/VnauQRV1qeEFsLrG/images/opencode-logo.svg?fit=max\&auto=format\&n=VnauQRV1qeEFsLrG\&q=85\&s=23868ab566c0ff7c82b7ee0a28154864)OpenCode | `opencode acp` |

Only Claude's own tools are turned off. Another agent's own tools work on
the computer it runs on, beside the workspace's tools; turn them off in the
agent's settings to keep it to the workspace, such as `tools.exclude` for
Gemini CLI or `permission` for OpenCode.

## Set up

**1. Install the CLI**

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

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

**2. Create the workspace**

```yaml workspace.yaml theme={null}
mounts:
  /:
    vfs: ram
    mode: write
```

```bash theme={null}
mirage workspace create workspace.yaml --id demo
```

**3. Install the agent**

Install the agent's ACP command from the [agents](#agents) table, such as
Claude's:

```bash theme={null}
npm install -g @agentclientprotocol/claude-agent-acp
```

**4. Add the agent to the client**

```json Zed theme={null}
{
  "agent_servers": {
    "Claude on Mirage": {
      "type": "custom",
      "command": "mirage",
      "args": ["acp", "-w", "demo", "--", "claude-agent-acp"],
      "env": {}
    }
  }
}
```

```json JetBrains theme={null}
{
  "agent_servers": {
    "Claude on Mirage": {
      "command": "mirage",
      "args": ["acp", "-w", "demo", "--", "claude-agent-acp"]
    }
  }
}
```

Give the full path of `mirage` when the client does not start it from a
shell that has it on its `PATH`.

## Example

Fix a bug in a workspace file from Zed, with Claude.

**1. Put a file in the workspace**

```bash theme={null}
mirage shell -w demo -c 'mkdir -p /project && printf "def add(a, b):\n    return a - b\n" > /project/calc.py'
```

**2. Ask in Zed**

Open any folder, start a **Claude on Mirage** thread from the set up
above, and ask:

```text theme={null}
Fix the bug in /project/calc.py so add returns the sum.
```

Claude reads the file with the workspace's `read` tool and changes it
with `edit`. The folder open in Zed stays as it was.

**3. Check the workspace**

```bash theme={null}
mirage shell -w demo -c 'cat /project/calc.py'
```

```text theme={null}
def add(a, b):
    return a + b
```

## Options

```bash theme={null}
mirage acp [-w ID | -c CONFIG] [-s SESSION] [--root PATH] -- AGENT...
```

| Option | Default | Means |
| - | - | - |
| `-w`, `--workspace` | | The workspace to use. |
| `-c`, `--config` | `.mirage/workspace.yaml` | A config to create the workspace from, as `mirage mcp` takes one. |
| `-s`, `--session` | the workspace's default | The session the agent's files and tools act as, under its [profile](https://docs.mirage.strukto.ai/home/configuration/session.md). |
| `--root` | `/` | The workspace path the client's project folder stands for. |

An agent asks for a file by its absolute path on the client. A path inside
the session's folder lands under `--root`; any other absolute path is read
as a workspace path. Put `--` before the agent's command so its options stay
its own. The exit status is the agent's, and 127 when there is no such
command.

## How it behaves

* A request the agent makes of the client, other than a file read or write,
  reaches the client unchanged, as does everything the client sends.
* An MCP server of the client's named `mirage` is replaced by the
  workspace's; the others stay.
* A config with no `workspace_id` makes a workspace that lives as long as
  `mirage acp` does, as with `mirage mcp`.


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