Agent Runtimes
OpenLoomi can delegate native agent tasks to its built-in Claude Agent SDK runtime or to locally installed CLI runtimes. Desktop users can select Claude, Codex, OpenCode, Hermes, or OpenClaw under Settings → Agent runtime. Claude's runtime is bundled with the desktop app; the other runtimes normally use their local CLI configuration and authentication. Hermes can also reuse the current user's saved Anthropic-compatible OpenLoomi API setting without copying it into Hermes files. The app performs bounded, read-only readiness checks before enabling a switch. Server/headless deployments use OPENLOOMI_AGENT_PROVIDER. A chat/API request cannot change the runtime.
Overview
Claude is the default agent runtime. Leaving OPENLOOMI_AGENT_PROVIDER unset is equivalent to setting it to claude. Codex is the secondary option when a direct, locally authenticated CLI runtime is preferred. Three more CLI runtimes — OpenCode, Hermes, and OpenClaw — round out the supported matrix for teams with existing CLI investments.
The supported runtimes sit at different layers:
- Claude is controlled through the Agent SDK, which launches the Claude runtime bundled with OpenLoomi Desktop as a child process.
- Codex, OpenCode, Hermes are CLI subprocesses that OpenLoomi spawns per task and reads a JSON event stream from.
- OpenClaw adds a Gateway that brokers sessions and device pairing.
Selecting a runtime chooses the AgentPlugin/IAgent implementation that executes a task; it does not turn that runtime into an OpenLoomi sandbox provider. The host and selected runtime still enforce their own filesystem, process, network, and approval boundaries.
| Provider | Role | Runtime path | Configuration source |
|---|---|---|---|
| Claude | Default | Agent SDK + bundled Claude runtime | Desktop setting / API / env |
| Codex | Secondary | codex exec --json | Desktop setting / Codex CLI |
| OpenCode | Optional | opencode run --format json | Desktop setting / OpenCode |
| Hermes | Optional | hermes acp | Desktop setting / Hermes |
| OpenClaw | Optional | openclaw acp plus a running Gateway | Desktop setting / OpenClaw |
Each runtime guide covers installation, authentication, OpenLoomi environment variables, permission behavior, verification, and troubleshooting:
- Claude Agent runtime — Default SDK runtime with built-in tools, skills, MCP, attachments, and streaming.
- Codex CLI runtime — Direct
codex execintegration with explicit sandbox modes. - OpenCode CLI runtime — Direct non-interactive CLI integration with JSON events.
- Hermes ACP runtime — Local ACP server integration with profile and model selection.
- OpenClaw ACP runtime — Gateway-backed ACP integration with session and device pairing.
Desktop runtime selection resolves in this order:
- The device preference saved from Settings
OPENLOOMI_AGENT_PROVIDER- Claude as the default
The device preference is local to that desktop installation. It does not alter deployment environment variables and only affects tasks started after the change. Select Use environment/default in Settings to delete the desktop override and return to the environment/default resolution path.
Agent runtimes and sandboxes are separate layers. Selecting a runtime chooses the AgentPlugin/IAgent implementation that executes a task; it does not turn that runtime into an OpenLoomi sandbox provider. The host and selected runtime still enforce their own filesystem, process, network, and approval boundaries.
Codex runtime vs. Codex plugin: This section describes OpenLoomi calling Codex as its runtime. The repository's
plugins/codexpackage works in the opposite direction: it gives Codex skills and a bridge for calling into OpenLoomi.
Related
- Plugins — the reverse direction: give Claude Code and Codex CLI a bridge for calling into OpenLoomi (memory, connectors, Pet)
- Getting Started — the
OPENLOOMI_AGENT_PROVIDERquick reference - Reference — back to the Reference index
- Skills — the reusable capabilities runtimes execute
- Embedding Providers — the embeddings used by Memory