---
summary: "How Mnemo separates model providers, models, channels, and agent runtimes"
title: "Agent runtimes"
read_when:
  - You are choosing between Mnemo, Codex, ACP, or another native agent runtime
  - You are confused by provider/model/runtime labels in status or config
  - You are documenting support parity for a native harness
---

An **agent runtime** is the component that owns one prepared model loop: it
receives the prompt, drives model output, handles native tool calls, and returns
the finished turn to Mnemo.

Runtimes are easy to confuse with providers because both show up near model
configuration. They are different layers:

| Layer         | Examples                                     | What it means                                                       |
| ------------- | -------------------------------------------- | ------------------------------------------------------------------- |
| Provider      | `openai`, `anthropic`, `github-copilot`      | How Mnemo authenticates, discovers models, and names model refs. |
| Model         | `gpt-5.5`, `claude-opus-4-6`                 | The model selected for the agent turn.                              |
| Agent runtime | `mnemo`, `codex`, `copilot`, `claude-cli` | The low level loop or backend that executes the prepared turn.      |
| Channel       | Telegram, Discord, Slack, WhatsApp           | Where messages enter and leave Mnemo.                            |

You will also see the word **harness** in code. A harness is the implementation
that provides an agent runtime. For example, the bundled Codex harness
implements the `codex` runtime. Public config uses `agentRuntime.id` on
provider or model entries; whole-agent runtime keys are legacy and ignored.
`mnemo doctor --fix` removes old whole-agent runtime pins and rewrites
legacy runtime model refs to canonical provider/model refs plus model-scoped
runtime policy where needed.

There are two runtime families:

- **Embedded harnesses** run inside Mnemo's prepared agent loop. Today this
  is the built-in `mnemo` runtime plus registered plugin harnesses such as
  `codex` and `copilot`.
- **CLI backends** run a local CLI process while keeping the model ref
  canonical. For example, `anthropic/claude-opus-4-8` with
  a model-scoped `agentRuntime.id: "claude-cli"` means "select the Anthropic
  model, execute through Claude CLI." `claude-cli` is not an embedded harness id
  and must not be passed to AgentHarness selection.

The `copilot` harness is a separate, opt-in external plugin harness for the
GitHub Copilot CLI; see [GitHub Copilot agent runtime](/plugins/copilot)
for the user-facing decision between PI, Codex, and GitHub Copilot agent runtime.

## Codex surfaces

Most confusion comes from several different surfaces sharing the Codex name:

| Surface                                          | Mnemo name/config                 | What it does                                                                                                   |
| ------------------------------------------------ | ------------------------------------ | -------------------------------------------------------------------------------------------------------------- |
| Native Codex app-server runtime                  | `openai/*` model refs                | Runs OpenAI embedded agent turns through Codex app-server. This is the usual ChatGPT/Codex subscription setup. |
| Codex OAuth auth profiles                        | `openai` OAuth profiles              | Stores ChatGPT/Codex subscription auth that the Codex app-server harness consumes.                             |
| Codex ACP adapter                                | `runtime: "acp"`, `agentId: "codex"` | Runs Codex through the external ACP/acpx control plane. Use only when ACP/acpx is explicitly asked.            |
| Native Codex chat-control command set            | `/codex ...`                         | Binds, resumes, steers, stops, and inspects Codex app-server threads from chat.                                |
| OpenAI Platform API route for non-agent surfaces | `openai/*` plus API-key auth         | Used for direct OpenAI APIs such as images, embeddings, speech, and realtime.                                  |

Those surfaces are intentionally independent. Enabling the `codex` plugin makes
the native app-server features available; `mnemo doctor --fix` owns legacy
legacy Codex route repair and stale session pin cleanup. Selecting
`openai/*` for an agent model now means "run this through Codex" unless a
non-agent OpenAI API surface is being used.

The common ChatGPT/Codex subscription setup uses Codex OAuth for auth, but keeps
the model ref as `openai/*` and selects the `codex` runtime:

```json5
{
  agents: {
    defaults: {
      model: "openai/gpt-5.5",
    },
  },
}
```

That means Mnemo selects an OpenAI model ref, then asks the Codex app-server
runtime to run the embedded agent turn. It does not mean "use API billing," and
it does not mean the channel, model provider catalog, or Mnemo session store
becomes Codex.

When the bundled `codex` plugin is enabled, natural-language Codex control
should use the native `/codex` command surface (`/codex bind`, `/codex threads`,
`/codex resume`, `/codex steer`, `/codex stop`) instead of ACP. Use ACP for
Codex only when the user explicitly asks for ACP/acpx or is testing the ACP
adapter path. Claude Code, Gemini CLI, OpenCode, Cursor, and similar external
harnesses still use ACP.

This is the agent-facing decision tree:

1. If the user asks for **Codex bind/control/thread/resume/steer/stop**, use the
   native `/codex` command surface when the bundled `codex` plugin is enabled.
2. If the user asks for **Codex as the embedded runtime** or wants the normal
   subscription-backed Codex agent experience, use `openai/<model>`.
3. If the user explicitly chooses **Mnemo for an OpenAI model**, keep the model ref
   as `openai/<model>` and set provider/model runtime policy to
   `agentRuntime.id: "mnemo"`. A selected `openai` OAuth profile is routed
   internally through Mnemo's Codex-auth transport.
4. If legacy config still contains **legacy Codex model refs**, repair it to
   `openai/<model>` with `mnemo doctor --fix`; doctor keeps the Codex auth
   route by adding provider/model-scoped `agentRuntime.id: "codex"` where the
   old model ref implied it.
   Legacy **`codex-cli/*` model refs** repair to the same `openai/<model>` Codex
   app-server route; Mnemo no longer keeps a bundled Codex CLI backend.
5. If the user explicitly says **ACP**, **acpx**, or **Codex ACP adapter**, use
   ACP with `runtime: "acp"` and `agentId: "codex"`.
6. If the request is for **Claude Code, Gemini CLI, OpenCode, Cursor, Droid, or
   another external harness**, use ACP/acpx, not the native sub-agent runtime.

| You mean...                             | Use...                                       |
| --------------------------------------- | -------------------------------------------- |
| Codex app-server chat/thread control    | `/codex ...` from the bundled `codex` plugin |
| Codex app-server embedded agent runtime | `openai/*` agent model refs                  |
| OpenAI Codex OAuth                      | `openai` OAuth profiles                      |
| Claude Code or other external harness   | ACP/acpx                                     |

For the OpenAI-family prefix split, see [OpenAI](/providers/openai) and
[Model providers](/concepts/model-providers). For the Codex runtime support
contract, see [Codex harness runtime](/plugins/codex-harness-runtime#v1-support-contract).

## Runtime ownership

Different runtimes own different amounts of the loop.

| Surface                     | Mnemo embedded                             | Codex app-server                                                            |
| --------------------------- | --------------------------------------------- | --------------------------------------------------------------------------- |
| Model loop owner            | Mnemo through the Mnemo embedded runner | Codex app-server                                                            |
| Canonical thread state      | Mnemo transcript                           | Codex thread, plus Mnemo transcript mirror                               |
| Mnemo dynamic tools      | Native Mnemo tool loop                     | Bridged through the Codex adapter                                           |
| Native shell and file tools | Mnemo path                                 | Codex-native tools, bridged through native hooks where supported            |
| Context engine              | Native Mnemo context assembly              | Mnemo projects assembled context into the Codex turn                     |
| Compaction                  | Mnemo or selected context engine           | Codex-native compaction, with Mnemo notifications and mirror maintenance |
| Channel delivery            | Mnemo                                      | Mnemo                                                                    |

This ownership split is the main design rule:

- If Mnemo owns the surface, Mnemo can provide normal plugin hook behavior.
- If the native runtime owns the surface, Mnemo needs runtime events or native hooks.
- If the native runtime owns canonical thread state, Mnemo should mirror and project context, not rewrite unsupported internals.

## Runtime selection

Mnemo chooses an embedded runtime after provider and model resolution:

1. Model-scoped runtime policy wins. This can live in a configured provider
   model entry or in `agents.defaults.models["provider/model"].agentRuntime` /
   `agents.list[].models["provider/model"].agentRuntime`. A provider wildcard
   such as `agents.defaults.models["vllm/*"].agentRuntime` applies after exact
   model policy, so dynamically discovered provider models can share one
   runtime without overriding exact per-model exceptions.
2. Provider-scoped runtime policy comes next at
   `models.providers.<provider>.agentRuntime`.
3. In `auto` mode, registered plugin runtimes can claim supported provider/model
   pairs.
4. If no runtime claims a turn in `auto` mode, Mnemo uses `mnemo` as the
   compatibility runtime. Use an explicit runtime id when the run must be
   strict.

Whole-session and whole-agent runtime pins are ignored. That includes
`MNEMO_AGENT_RUNTIME`, session `agentHarnessId`/`agentRuntimeOverride` state,
`agents.defaults.agentRuntime`, and `agents.list[].agentRuntime`. Run
`mnemo doctor --fix` to remove stale whole-agent runtime config and convert
legacy runtime model refs where Mnemo can preserve the intent.

Explicit provider/model plugin runtimes fail closed. For example,
`agentRuntime.id: "codex"` on a provider or model means Codex or a clear
selection/runtime error; it is never silently routed back to Mnemo.

CLI backend aliases are different from embedded harness ids. The preferred
Claude CLI form is:

```json5
{
  agents: {
    defaults: {
      model: "anthropic/claude-opus-4-8",
      models: {
        "anthropic/claude-opus-4-8": {
          agentRuntime: { id: "claude-cli" },
        },
      },
    },
  },
}
```

Legacy refs such as `claude-cli/claude-opus-4-7` remain supported for
compatibility, but new config should keep the provider/model canonical and put
the execution backend in provider/model runtime policy.

Legacy `codex-cli/*` refs are different: doctor migrates them to `openai/*` so
they run through the Codex app-server harness instead of preserving a Codex CLI
backend.

`auto` mode is intentionally conservative for most providers. OpenAI agent
models are the exception: unset runtime and `auto` both resolve to the Codex
harness. Explicit Mnemo runtime config remains an opt-in compatibility route for
`openai/*` agent turns; when paired with a selected `openai` OAuth profile,
Mnemo routes that path internally through the Codex-auth transport while
keeping the public model ref as `openai/*`. Stale OpenAI runtime session pins are
ignored by runtime selection and can be cleaned with `mnemo doctor --fix`.

If `mnemo doctor` warns that the `codex` plugin is enabled while
legacy Codex model refs remain in config, treat that as legacy route state. Run
`mnemo doctor --fix` to rewrite it to `openai/*` with the Codex runtime.

## GitHub Copilot agent runtime

The external `@mnemo-bot/copilot` plugin registers an opt-in `copilot` runtime
backed by the GitHub Copilot CLI (`@github/copilot-sdk`). It claims the
canonical subscription `github-copilot` provider and is **never** selected by
`auto`. Opt in per-model or per-provider via `agentRuntime.id`:

```json5
{
  agents: {
    defaults: {
      model: "github-copilot/gpt-5.5",
      models: {
        "github-copilot/gpt-5.5": {
          agentRuntime: { id: "copilot" },
        },
      },
    },
  },
}
```

The harness claims its provider, runtime, CLI session key, and auth profile
prefix in `extensions/copilot/doctor-contract-api.ts`, which
`mnemo doctor` auto-loads. For configuration, auth, transcript mirroring,
compaction, the doctor probe surface, and the broader PI vs Codex vs Copilot
SDK decision, see [GitHub Copilot agent runtime](/plugins/copilot).

## Compatibility contract

When a runtime is not Mnemo, it should document what Mnemo surfaces it supports.
Use this shape for runtime docs:

| Question                               | Why it matters                                                                                    |
| -------------------------------------- | ------------------------------------------------------------------------------------------------- |
| Who owns the model loop?               | Determines where retries, tool continuation, and final answer decisions happen.                   |
| Who owns canonical thread history?     | Determines whether Mnemo can edit history or only mirror it.                                   |
| Do Mnemo dynamic tools work?        | Messaging, sessions, cron, and Mnemo-owned tools rely on this.                                 |
| Do dynamic tool hooks work?            | Plugins expect `before_tool_call`, `after_tool_call`, and middleware around Mnemo-owned tools. |
| Do native tool hooks work?             | Shell, patch, and runtime-owned tools need native hook support for policy and observation.        |
| Does the context engine lifecycle run? | Memory and context plugins depend on assemble, ingest, after-turn, and compaction lifecycle.      |
| What compaction data is exposed?       | Some plugins only need notifications, while others need kept/dropped metadata.                    |
| What is intentionally unsupported?     | Users should not assume Mnemo equivalence where the native runtime owns more state.            |

The Codex runtime support contract is documented in
[Codex harness runtime](/plugins/codex-harness-runtime#v1-support-contract).

## Status labels

Status output may show both `Execution` and `Runtime` labels. Read them as
diagnostics, not as provider names.

- A model ref such as `openai/gpt-5.5` tells you the selected provider/model.
- A runtime id such as `codex` tells you which loop is executing the turn.
- A channel label such as Telegram or Discord tells you where the conversation is happening.

If a run still shows an unexpected runtime, inspect the selected provider/model
runtime policy first. Legacy session runtime pins no longer decide routing.

## Related

- [Codex harness](/plugins/codex-harness)
- [Codex harness runtime](/plugins/codex-harness-runtime)
- [GitHub Copilot agent runtime](/plugins/copilot)
- [OpenAI](/providers/openai)
- [Agent harness plugins](/plugins/sdk-agent-harness)
- [Agent loop](/concepts/agent-loop)
- [Models](/concepts/models)
- [Status](/cli/status)
