ak codex-agent-runtime serve

ak codex-agent-runtime serve

Run the Codex agent MCP server over stdio.

Synopsis

What it does: Exposes each discovered kit or user agent as an MCP tool named agent_<slug>. Codex invokes a tool and the runtime spawns codex exec with the agent's system prompt plus user prompt, then returns the result. Cold-start cost: each dispatch spawns a fresh codex exec subprocess (roughly 1-3s per call); a warm/long-lived runtime is a tracked mitigation.

Who it's for: Power devs running the Codex adapter or scripting doctor/CI checks.

When to use it: Codex starts this automatically when registered via ak codex-agent-runtime register. Use --list-only to enumerate discovered agents without starting the MCP transport.

Examples: ak codex-agent-runtime serve # start MCP server on stdio ak codex-agent-runtime serve --list-only # print agents and exit without serving ak codex-agent-runtime serve --list-only --codex-home ~/.codex --plugin-root ~/.claude/plugins # override both dirs

What changes on disk: Read-only. Does not write to disk; starts a long-running MCP stdio server that dispatches to codex exec subprocesses. Use it for scripted doctor/CI checks with --list-only.

Output modes: pretty default on TTY (colors, ASCII markers) plain auto when stdout piped or --no-interactive json --json (single-object envelope, NDJSON-safe)

Exit codes: 0 success 1 runtime error 2 invalid flags 3 user-cancel (SIGINT, prompt-cancel) 1 MCP transport error or agent discovery failure

ak codex-agent-runtime serve [flags]

Options

      --codex-home string    Override $CODEX_HOME (defaults to ~/.codex)
  -h, --help                 help for serve
      --json                 Emit machine-readable JSON (implies --no-interactive)
      --list-only            Print discovered agents and exit without serving MCP
      --no-interactive       Disable interactive prompts (CI-safe)
      --plugin-root string   Override $AGENTKIT_PLUGIN_DIR (defaults to ~/.claude/plugins)
  -q, --quiet                Suppress non-error output on stderr
  -V, --verbose              Extra diagnostic output on stderr (loses to --quiet)
  -y, --yes                  Assume yes for all prompts

SEE ALSO

• ak codex-agent-runtime - Codex agent MCP dispatch runtime.