Agent Runtimes
OpenLoomi can delegate native agent tasks to its built-in Claude Agent SDK runtime or to locally installed CLI runtimes. Runtime selection is deployment configuration: set OPENLOOMI_AGENT_PROVIDER before starting OpenLoomi, then restart the process after changing it. The runtime cannot be selected or reconfigured from a chat/API request.
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 runs in-process via the Agent SDK — OpenLoomi owns the lifecycle.
- 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 | Claude Agent SDK query() | OpenLoomi API settings / env |
| Codex | Secondary | codex exec --json | Environment and Codex CLI |
| OpenCode | Optional | opencode run --format json | Environment and OpenCode |
| Hermes | Optional | hermes acp | Environment and Hermes |
| OpenClaw | Optional | openclaw acp plus a running Gateway | Environment and 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.
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