OpenAI opened the Agents API to every developer yesterday, September 10. MarkTechPost's write-up describes it as a managed service built on the open-source Codex harness: sessions, context compaction, recovery and subagents are OpenAI's job, and the developer supplies tools and picks where the code runs. Three places are on offer. An OpenAI-hosted sandbox, partner sandboxes at Blaxel, Cloudflare, Daytona, DigitalOcean, E2B, Modal, Oracle, Runloop and Vercel, or your own machines, which run codex exec-server and dial out over a WebSocket. E2B's integration docs show what the last option looks like in practice: a worker boots with codex exec-server baked in, the first session takes about 40 seconds while the controller starts it, and the worker stays warm on a 30-minute timeout. You follow progress through streaming or webhooks. There is no separate fee beyond tokens, tools and container time.
So the harness is now a service. The same harness also ships as a CLI, and that CLI's flags move. This week shell.online shipped a fix for exactly that problem, and it is small enough to walk through in full.
A form that was right when it was written
The accounts app in shell.online can start a coding-agent session on one of your linked machines from the browser. You pick the machine, pick the tool, fill in a short form, and the app builds a command line, shows it to you, and posts it. The machine's agent picks it up on its next poll and runs it inside a shared terminal. Four tools are supported today, Claude Code, GPT Codex, Hermes Agent and OpenClaw, listed in KNOWN_HARNESSES in the server and mirrored in the CLI's harness.go.
Until v0.11.2, the Codex form offered one option beyond resuming a session: a "Full auto" toggle that appended --full-auto. The form was candid about where that came from. A note under it read: "These flags come from the published interface for GPT Codex rather than from its own help output, so check the command below before starting."
The note was honest, and the flag was dead. OpenAI's release notes for rust-v0.147.0, dated August 7, say: "Remove the deprecated codex exec --full-auto flag; use --sandbox workspace-write instead." Pull request #80 tried it against codex 0.153.4 and got the same answer from the root command:
$ codex --full-auto --help
error: unexpected argument '--full-auto' found
The consequence is specific to this shape of product. The form runs in your browser. The command runs on a different machine, against whatever Codex is installed there. The app does not know that version. The detection code checks whether a tool is on PATH and deliberately never executes it, because "running an agent binary to read a version string, so a browser can render a label, buys nothing worth the risk, and several of these take seconds to start." So a bad flag is not caught in the form. It goes through POST /api/commands, waits for the poll, and fails on the machine it was sent to.
Read the interface from the binary, not the docs
The fix in PR #80, shipped in v0.11.2 on September 10, was to install both tools, read their real --help, and rebuild the two kinds so the warning could be deleted rather than kept.
Codex now gets what codex --help and codex resume --help accept: resume by id or --last, --sandbox with read-only, workspace-write or danger-full-access, --ask-for-approval with on-request or never, and --search. A model field arrived in the same release. Options are placed after resume <id>, because the subcommand takes the same flags as the root command, and that is the one order that works for both a fresh and a resumed run. An empty select emits no flag at all, so "codex default" means whatever the installed version defaults to, not a value we guessed.
Hermes was a free-text box before. It now has a subcommand picker (chat, gateway, sessions, dashboard, status, doctor, acp) plus --resume, --continue, --model, --worktree and --yolo. Two parser rules are encoded in the builder and tested. Every option belongs to the top-level parser, so all of them go before the subcommand: hermes sessions --yolo is an error, hermes --yolo sessions is fine. And --continue takes an optional value, which the Hermes CLI reference writes as --continue [name], so a bare one is greedy. hermes --continue sessions resumes a session called "sessions". The builder emits it last, and only when there is no subcommand and no explicit session for it to swallow.
The test that used to assert which kinds were built from a published interface is gone. Its replacement generates every command shape from every builder and asserts none of them contains --full-auto. The PR body records that all 17 shapes the two builders can produce were run against the installed binaries and accepted.
Why this belongs next to the Agents API
The Agents API answers the version problem by owning the harness. When OpenAI runs codex exec-server in a sandbox it provisioned, the flags and the binary always match. That is a real advantage of the managed box. It is also the thing you give up the moment the agent runs on a machine you own, which is what the self-hosted option exists for, and what our launcher is for.
For that case there are two habits and no shortcut. Build the command from the interface of the tool you will actually run, and test the generated shapes against the binary rather than the docs. The session-kinds module makes the second habit cheap: each kind is a form plus a pure function from its fields to a command line, kept apart from the modal so that the command which will run on someone's machine is testable without a DOM.
The other half is seeing the failure where it happens. A command that dies on a remote machine with "unexpected argument" is only useful if the output comes back to you, which is what wrapping the run in a live terminal link is for. That is the reason we build shell.online at Pilot Protocol in the first place: an agent running somewhere else needs a place to show its work, and sometimes the work is one line of error text.
Top comments (0)