# Chat Host Integrations

This page documents the intended product path for `pyro-mcp`:

- validate the host with the CLI
- warm the daily loop with `pyro prepare debian:12`
- run `pyro mcp serve`
- connect a chat host
- let the agent work inside disposable workspaces

`pyro-mcp` currently has no users. Expect breaking changes while this chat-host
path is still being shaped.

Use this page after you have already validated the host and guest execution
through [install.md](install.md) or [first-run.md](first-run.md).

Recommended first commands before connecting a host:

```bash
pyro doctor --environment debian:12
pyro prepare debian:12
```

## Recommended Modes

Use a named mode when one workflow already matches the job:

```bash
pyro host connect codex --mode repro-fix
pyro host connect codex --mode inspect
pyro host connect claude-code --mode cold-start
pyro host connect claude-code --mode review-eval
```

The mode-backed raw server forms are:

```bash
pyro mcp serve --mode repro-fix
pyro mcp serve --mode inspect
pyro mcp serve --mode cold-start
pyro mcp serve --mode review-eval
```

Use the generic no-mode path only when the named mode feels too narrow.

## Generic Default

Bare `pyro mcp serve` starts `workspace-core`. From a repo root, it also
auto-detects the current Git checkout so the first `workspace_create` can omit
`seed_path`. That is the product path.

```bash
pyro mcp serve
```

If the host does not preserve cwd, fall back to:

```bash
pyro mcp serve --project-path /abs/path/to/repo
```

If you are outside a repo checkout entirely, start from a clean clone source:

```bash
pyro mcp serve --repo-url https://github.com/example/project.git
```

Use `--profile workspace-full` only when the chat truly needs shells, services,
snapshots, secrets, network policy, or disk tools.

## Helper First

Use the helper flow before the raw host CLI commands:

```bash
pyro host connect codex --mode repro-fix
pyro host connect codex --mode inspect
pyro host connect claude-code --mode cold-start
pyro host connect claude-code --mode review-eval
pyro host print-config opencode --mode repro-fix
pyro host doctor
pyro host repair opencode
```

These helpers wrap the same `pyro mcp serve` entrypoint, make named modes the
first user-facing story, and still leave the generic no-mode path available
when a mode is too narrow.

## Claude Code

Preferred:

```bash
pyro host connect claude-code --mode cold-start
```

Repair:

```bash
pyro host repair claude-code
```

Package without install:

```bash
claude mcp add pyro -- uvx --from pyro-mcp pyro mcp serve --mode cold-start
claude mcp list
```

If Claude Code launches the server from an unexpected cwd, use:

```bash
claude mcp add pyro -- uvx --from pyro-mcp pyro mcp serve --mode cold-start --project-path /abs/path/to/repo
```

Already installed:

```bash
claude mcp add pyro -- pyro mcp serve
claude mcp list
```

Reference:

- [claude_code_mcp.md](../examples/claude_code_mcp.md)

## Codex

Preferred:

```bash
pyro host connect codex --mode repro-fix
```

Repair:

```bash
pyro host repair codex
```

Package without install:

```bash
codex mcp add pyro -- uvx --from pyro-mcp pyro mcp serve --mode repro-fix
codex mcp list
```

If Codex launches the server from an unexpected cwd, use:

```bash
codex mcp add pyro -- uvx --from pyro-mcp pyro mcp serve --mode repro-fix --project-path /abs/path/to/repo
```

Already installed:

```bash
codex mcp add pyro -- pyro mcp serve
codex mcp list
```

Reference:

- [codex_mcp.md](../examples/codex_mcp.md)

## OpenCode

Preferred:

```bash
pyro host print-config opencode
pyro host repair opencode
```

Use the local MCP config shape from:

- [opencode_mcp_config.json](../examples/opencode_mcp_config.json)

Minimal `opencode.json` snippet:

```json
{
  "mcp": {
    "pyro": {
      "type": "local",
      "enabled": true,
      "command": ["uvx", "--from", "pyro-mcp", "pyro", "mcp", "serve", "--mode", "repro-fix"]
    }
  }
}
```

If `pyro-mcp` is already installed, replace `uvx --from pyro-mcp pyro` with
`pyro` in the same config shape.

If OpenCode launches the server from an unexpected cwd, add
`"--project-path", "/abs/path/to/repo"` after `"serve"` in the same command
array.

## Generic MCP Fallback

Use this only when the host expects a plain `mcpServers` JSON config, when the
named modes are too narrow, and when it does not already have a dedicated
example in the repo:

- [mcp_client_config.md](../examples/mcp_client_config.md)

Generic `mcpServers` shape:

```json
{
  "mcpServers": {
    "pyro": {
      "command": "uvx",
      "args": ["--from", "pyro-mcp", "pyro", "mcp", "serve"]
    }
  }
}
```

## When To Use `workspace-full`

Stay on bare `pyro mcp serve` unless the chat host truly needs:

- persistent PTY shell sessions
- long-running services and readiness probes
- secrets
- guest networking and published ports
- stopped-workspace disk inspection or raw ext4 export

When that is necessary:

```bash
pyro mcp serve --profile workspace-full
```

## Recipe-Backed Workflows

Once the host is connected, move to the five real workflows in
[use-cases/README.md](use-cases/README.md):

- cold-start repo validation
- repro plus fix loops
- parallel isolated workspaces
- unsafe or untrusted code inspection
- review and evaluation workflows

Validate the whole story with:

```bash
make smoke-use-cases
```

For the machine-warmup plus reset/retry path specifically:

```bash
make smoke-daily-loop
```