ak codex-agent-runtime serve

Use --list-only to inspect agent discovery. Without it, this command runs the stdio MCP server registered in Codex config and blocks until the client disconnects or the process is cancelled.

Usage

ak codex-agent-runtime serve [flags]

The command accepts no positional arguments.

Options

Shared flags are described in CLI conventions, but --json, --quiet, --yes, and --no-interactive do not change the serve or list renderer.

Inspect discovery

ak codex-agent-runtime serve --list-only

List-only output is plain text on stdout even with --json. It prints the resolved Codex home, plugin root, a project agents: line when a project agent directory was found, count, agent slugs, and the origin when known: the owning Kit, or (project) for a project agent. Those paths and names may be sensitive in support output.

Discovery reads three sources:

1. Project agents. The nearest <dir>/.codex/agents/ at or above the working directory, where Codex launches the runtime. The search stops at the repository root (the first directory with .git), before the user home directory, and at the filesystem root. The directory is served only when the Codex config under the selected Codex home marks that project, or its enclosing repository root, as trusted. AgentKit does not write that trust.
2. User agents under <codex-home>/agents/.
3. Staged Kit agents under <plugin-root>/<kit>/.codex/agents/.

project agents: <dir> means the project directory is served. project agents: skipped (<reason>) means it was found but not served, for example because the project is untrusted or not yet recorded, the .codex or agents directory is a symlink or Windows junction, or the directory cannot be read; the server writes the same reason to stderr at startup. Linked TOML files inside the project directory are ignored.

Discovery scans valid *.toml filenames. A project agent replaces a same-slug user agent, and the server notes the replacement on stderr. User agents take precedence over same-slug staged agents; staged Kit conflicts resolve by lexicographic Kit order. Missing roots are accepted as empty. An unreadable root fails exit 1. Unreadable individual agent files are still listed with an empty, permissive parsed policy.

Serve over stdio

ak codex-agent-runtime serve

Stdout is reserved for MCP protocol frames. Do not redirect log text into that stream. A startup line with server version and agent count is written to stderr. The process does not read interactive terminal input or ask for confirmation.

Each agent becomes agent_<slug>. A tool call accepts a required prompt and an optional named tool, reads the installed agent TOML, checks policy, and starts a fresh codex exec subprocess. The prompt is piped to that subprocess stdin; its stdout becomes MCP text content. A failed subprocess returns an MCP tool result with isError=true and captured stderr, while the server continues.

The serve command does not preflight the codex binary. It can start and list tools without Codex installed; the affected tool call fails when dispatch is attempted. Registration config gives each MCP tool call 600 seconds, but a manually connected client can use its own timeout.

Exit status

Dispatch dependency/provider exits are represented inside the MCP result, not as the long-running server's process exit.

Related commands

• Register automatic startup
• Complete serve facts
• Run a skill through an adapter