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

# OpenAI Codex

> Connect Codex to a Mirage workspace through the CLI, SSH or a FUSE mount.

| Way | Codex gets | Needs |
| - | - | - |
| [CLI](#cli) | Mirage's seven tools, beside its own | the `mirage` CLI |
| [SSH](#ssh) | its own tools, run in the workspace | the daemon's [SSH server](/home/access/ssh) |
| [FUSE](#fuse) | its own tools, on the workspace as a folder | a [FUSE driver](/home/setup/fuse) |

## Install

```bash theme={null}
uv tool install 'mirage-ai[fuse]'
```

Install [Codex](https://github.com/openai/codex) separately.

## Workspace

```yaml workspace.yaml theme={null}
mode: write
mounts:
  /:
    vfs: ram
    backend: fuse                 # FUSE only
    mountpoint: /tmp/mirage-demo  # FUSE only
  /s3:
    vfs: s3
    mode: read
    config:
      bucket: my-bucket
```

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

## CLI

```bash theme={null}
codex mcp add mirage -- mirage mcp -w demo
```

Codex gets `shell`, `read`, `write`, `edit`, `ls`, `grep` and `glob` from the workspace's [MCP server](/home/access/mcp).

Or install the Mirage plugin, which adds a skill and reads `.mirage/workspace.yaml` from your project instead:

```bash theme={null}
codex plugin marketplace add strukto-ai/mirage
codex plugin add mirage@mirage
```

## SSH

Turn on the daemon's [SSH server](/home/access/ssh#turn-it-on), then add it as a Codex environment:

```toml ~/.codex/environments.toml theme={null}
default = "mirage"
include_local = false

[[environments]]
id = "mirage"
program = "ssh"
args = ["-T", "-p", "2222", "demo@127.0.0.1", "-s", "codex-exec"]
```

```bash theme={null}
codex -C /
```

Codex's shell commands, file reads and patches run in the workspace, under the SSH key's profile. This works in the Codex CLI, not the app. The protocol is experimental and follows Codex 0.147.

## FUSE

```bash theme={null}
cd /tmp/mirage-demo && codex
```

Every file and shell call Codex makes goes through Mirage: `/tmp/mirage-demo/s3` is the bucket. In the Codex app, open the mountpoint as the project folder. `mirage workspace delete demo` 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.