ReferenceCLI commands
BetaYou are reading docs for the beta channel (
2.4.1-beta.1) — updated automatically on every beta release.Switch to stable →CLI commands
ak codex-agent-runtime
Codex agent MCP dispatch runtime.
Registers each discovered kit or user agent as an MCP tool over stdio so Codex can invoke it by tool name. Backed by codex exec subprocesses per agent call. Use the subcommands to serve the runtime, register it in Codex config, or remove it.
Who it's for: Power devs integrating AgentKit with the Codex AI runtime.
When to use it: After running ak kit init for a Codex-targeted kit, register the runtime once so Codex sessions can invoke kit agents as MCP tools.
What changes on disk: Read-only at this group level; subcommands document their own disk effects.
Examples
ak codex-agent-runtime serve # start MCP server on stdio
ak codex-agent-runtime register # write config.toml entry
ak codex-agent-runtime unregister # remove config.toml entryFlags
| Flag | Description |
|---|---|
-h, --help | help for codex-agent-runtime |
Output modes
| Mode | Behavior |
|---|---|
pretty | default on TTY (colors, ASCII markers) |
plain | auto when stdout piped or --no-interactive |
json | --json (single-object envelope, NDJSON-safe) |
Exit codes
| Code | Meaning |
|---|---|
0 | success |
1 | runtime error |
2 | invalid flags |
3 | user-cancel (SIGINT, prompt-cancel) |
Related commands
ak— AgentKit CLIak codex-agent-runtime register— Idempotently register ak-agent-runtime in ~/.codex/config.toml.ak codex-agent-runtime serve— Run the Codex agent MCP server over stdio.ak codex-agent-runtime unregister— Idempotently remove ak-agent-runtime from ~/.codex/config.toml.