Codex CLI Runtime

The Codex runtime adapter starts the locally installed CLI with codex exec --json, consumes its JSONL event stream, and maps Codex sessions, text, reasoning, tool activity, errors, and usage into OpenLoomi agent events. OpenLoomi does not install or authenticate Codex for you.

Install and authenticate

Install the official CLI and confirm it is available to the same OS user that starts OpenLoomi:

npm install -g @openai/codex
codex --version
codex login

Codex reuses saved CLI authentication. For controlled non-interactive environments, the CLI also accepts CODEX_API_KEY for codex exec; OpenLoomi preserves CODEX_* variables in the runtime's restricted child-process environment. Keep CODEX_API_KEY scoped to the OpenLoomi process and do not expose it to untrusted build or repository scripts.

Verify Codex independently before enabling the adapter:

codex exec --json --sandbox read-only --skip-git-repo-check \
  "Reply with exactly: CODEX_READY"

See the official Codex non-interactive mode documentation for codex exec, JSONL output, authentication, and sandbox behavior.

Select it in the desktop app

Open Settings → Agent runtime and choose Codex CLI. The page checks codex --version, codex login status, and codex exec --help without starting a model request. Follow the installation or login guidance, select Re-detect, and switch once the status is Ready. The change applies to new tasks. Ready confirms discovery, authentication, and JSON execution support, not that a model override or network path can complete a request; use the verification command above for that stronger check. Select Use environment/default to remove the desktop override later.

Configure OpenLoomi

Set environment variables before starting OpenLoomi:

OPENLOOMI_AGENT_PROVIDER=codex
OPENLOOMI_AGENT_CODEX_COMMAND=codex
OPENLOOMI_AGENT_CODEX_SANDBOX=workspace-write
OPENLOOMI_AGENT_CODEX_SKIP_GIT_REPO_CHECK=true
OPENLOOMI_AGENT_CODEX_FULL_AUTO=false
OPENLOOMI_AGENT_CODEX_TIMEOUT_MS=300000

Optional model and profile overrides:

OPENLOOMI_AGENT_CODEX_PROFILE=work
OPENLOOMI_AGENT_CODEX_MODEL=gpt-5.4

Leave either value unset to use the corresponding Codex CLI configuration. CODEX_HOME is also preserved, so an installation with a non-default Codex config and authentication directory can be selected at process startup.

Environment reference

Variable	Default	Behavior
`OPENLOOMI_AGENT_CODEX_COMMAND`	`codex`	Executable name or absolute path.
`OPENLOOMI_AGENT_CODEX_PROFILE`	Codex default	Passes the named Codex config profile with `-p`. Profiles remain useful for Linux/Windows network policy and model settings; the choice persists in `openloomi.config.toml` and per-profile env vars land in `codex-profile-env.plist` (macOS).
`OPENLOOMI_AGENT_CODEX_MODEL`	Codex default	Passes a model override with `-m`.
`OPENLOOMI_AGENT_CODEX_SANDBOX`	Platform-specific	Accepts `read-only`, `workspace-write`, or `danger-full-access`. Planning always uses `read-only`. Linux/Windows execution defaults to `workspace-write`. macOS execution maps the default and explicit `workspace-write` to `danger-full-access`, because the macOS sandbox blocks localhost and outbound network access. Set `read-only` to opt back into isolation when execution does not need those services.
`OPENLOOMI_AGENT_CODEX_SKIP_GIT_REPO_CHECK`	`true`	Allows OpenLoomi work directories outside a Git repository. Set `false` to enforce Codex's check.
`OPENLOOMI_AGENT_CODEX_FULL_AUTO`	`false`	Compatibility opt-in; only forwarded for an explicit bypass-permissions execution request.
`OPENLOOMI_AGENT_CODEX_TIMEOUT_MS`	unset	Positive integer process timeout in milliseconds.

codex exec --full-auto is a deprecated compatibility path in current Codex releases. Prefer an explicit sandbox and leave OPENLOOMI_AGENT_CODEX_FULL_AUTO=false. macOS execution uses danger-full-access so OpenLoomi and other network services remain reachable; run OpenLoomi inside an isolation boundary you control when that broader access is not acceptable, or explicitly select read-only for offline execution.

Executable paths, profiles, models, sandbox modes, Git checks, and timeouts are server-owned configuration. Values supplied in native-agent request bodies are ignored, so a caller cannot switch the runtime or weaken its policy.

Troubleshooting

Executable not found: run codex --version as the OpenLoomi service user, or set OPENLOOMI_AGENT_CODEX_COMMAND to the absolute executable path.
Login or model error: run the verification command above with the same HOME/USERPROFILE and CODEX_HOME used by OpenLoomi.
Not inside a trusted directory: keep OPENLOOMI_AGENT_CODEX_SKIP_GIT_REPO_CHECK=true for non-repository work directories, or run tasks in a Git repository and set it to false.
Run times out: increase OPENLOOMI_AGENT_CODEX_TIMEOUT_MS and verify the selected model is reachable from the Codex CLI itself.
no composio surface reachable / connectors flip back to needs_setup while OpenLoomi drives Codex — first confirm the active execution sandbox. On macOS, current OpenLoomi releases map workspace-write to danger-full-access; restart the updated desktop app if an older process is still using the blocked sandbox. An explicit read-only setting still blocks network access. On Linux/Windows, use a Codex profile with network access enabled or select a sandbox appropriate for the host's isolation boundary, then restart OpenLoomi and re-run the connector probe.

Agent Runtimes — runtime index
Codex Plugin — the reverse bridge for Codex CLI
Getting Started — install + first run
OpenLoomi CLI — drive the runtime from a shell