Codex
Codex runs shell commands, so it works best through the runbook CLI,
guided by the therunbook skill.
With the CLI and the skill (recommended)
Section titled “With the CLI and the skill (recommended)”-
Install the CLI and sign in:
Terminal window curl -fsSL https://github.com/angler-ai/the-runbook-app/releases/latest/download/install.sh | shrunbook login https://runbooks.example.comInstalling the CLI has the other ways, such as building from source.
-
Install the skill where Codex reads skills:
Terminal window runbook skill install --agent codex --therunbookWithout
--agent, it installs for every agent set up on this machine (Claude Code, Codex, Cursor). Run it again after upgrading the CLI.That writes
~/.agents/skills/therunbook/;--scope projectwrites.agents/skills/therunbook/in this repository instead. -
Give Codex its own credential, an agent-kind token, so its work is recorded as an agent’s and it can’t decide human approvals:
Terminal window runbook token create --agent --name codex --expires-in 30d \--scope runbooks:read --scope executions:read --scope executions:act --jsonExport the secret as
RUNBOOK_TOKENin the environment Codex runs in. -
Try it:
Terminal window codex "Work the next agent step of run exe_01JD2X6PZ5R8E2W4Y6A0C3D5F7."
Over MCP
Section titled “Over MCP”[mcp_servers.runbook]command = "runbook"args = ["mcp", "serve"]The server uses the CLI’s current context. It never acts with your own
runbook login: it needs the agent token from step 3 in RUNBOOK_TOKEN
in Codex’s environment.
[mcp_servers.runbook]url = "https://runbooks.example.com/mcp"Then sign in once:
codex mcp login runbookCodex registers itself with your server; you sign in with an email code and tick the scopes it may use.
[mcp_servers.runbook]url = "https://runbooks.example.com/mcp"bearer_token_env_var = "RUNBOOK_TOKEN"Running Codex unattended
Section titled “Running Codex unattended”codex exec runs one task headless, which is what a launcher needs:
codex exec "Work every ready agent step of run $EXE, then stop."See Your own agent for the launcher that starts it when work is available.