Codex CLI parallel agents, run from one board
Codex works a prompt and exits, which makes it simple to parallelize and hard to track. PortBay gives every run a card: dispatched headless, worked in a running project, finished with a comment.
One board
How do I run Codex CLI agents in parallel?
Codex exec runs headless and exits, so anything that can launch a process can run several at once — the hard part is not starting them, it is knowing afterwards which run worked which task, what it changed, and whether it finished at all. Worktrees plus terminal tabs give you parallelism and no record. PortBay gives every run a card instead. Each card is a Markdown file in .portbay/tasks/; move one to To Do and PortBay launches the Codex CLI headless, pointed at that card, inside the project's running local environment: a real .test domain with trusted HTTPS, a per-project database, captured mail. The run reads .portbay/HANDOFF.md first, comments what it changed, and advances the card, and a strike system stops a failing card after 3 runs by default. Settings → Integrations writes Codex's MCP config, so a connected session can claim cards itself.
Verified against the product, 2026-07-10.
One card, one headless Codex run
Assign Codex, move the card to To Do, and the run launches with no terminal tab. Progress, comments and the move to Done all land on the card.
Your first headless Codex run
Six steps from a clean Mac to a headless Codex run you can review at a real URL. Every command runs as written.
- Install PortBay
- Add your project
- Connect Codex over MCP (optional)
- Write a card and assign Codex
- Move the card to To Do
- Review the work at a real URL
Install PortBay
Homebrew installs the app and the bundled portbay CLI. Prefer a direct download? Grab the DMG from GitHub Releases and drag PortBay.app into Applications.
brew tap portbay-app/portbay && brew install --cask portbayAdd your project
Click Add project in the app, pick the folder, and confirm the detected type, hostname and port. Save, then start it. Your project now answers at its own .test URL over HTTPS. The CLI does the same from a terminal.
portbay add ~/code/myappConnect Codex over MCP (optional)
Settings → Integrations detects the agent CLIs on your Mac and writes the MCP config for each client. For Codex the entry lands in its config file, pointing at the bundled portbay-mcp binary. A connected session can read the board, claim cards and move them forward.
~/.codex/config.toml → [mcp_servers.portbay]Write a card and assign Codex
Describe the task the way you would brief a teammate. Assign Codex on the card itself, or set it as the board default so every card without its own agent uses it. The card is a plain Markdown file in your repo.
.portbay/tasks/paginate-orders-api.mdMove the card to To Do
Auto-dispatch launches Codex headless the moment the card lands: a subprocess, not a tab. Manual mode queues the card and asks you to confirm each run. A concurrency cap decides how many runs go at once.
Review the work at a real URL
The agent edits your repo, checks its work against the running project, comments what it changed, and appends a hand-off entry to .portbay/HANDOFF.md. Open the project URL and review. Turn on Require review to hold agent-reported work for your approval.
https://myapp.testParallel Codex, without the board
Codex's exec mode means anything that can launch a process can run it, and that is the trap: the runs start in seconds and the bookkeeping eats the speedup.
The board keeps what headless runs lose: which card each run worked, what it changed, and where the next run should start.
# one worktree per task, one tab per agentgit worktree add ../myapp-search feature/searchgit worktree add ../myapp-emails feature/emails cd ../myapp-search && codex # tab 1cd ../myapp-emails && codex # tab 2 # which run finished? which stalled? did the work run at all?# task state lives in your memory and a scrollback buffer
The pieces underneath
Asked before downloading
How does PortBay launch Codex?
As a headless CLI subprocess pointed at the card, using the Codex install you already have. PortBay detects the agent CLIs on your Mac and lets you set the binary path by hand for anything it can't find. It ships no model of its own.
Can Codex and Claude Code share one board?
Yes. Assign an agent per card, or set a board default. PortBay recognizes eleven agents out of the box, Claude Code, Codex, Cursor, Gemini and Aider among them, plus a Custom option that runs any other CLI from a command template.
Does my code leave my Mac when Codex runs from the board?
PortBay sends nothing. The board, cards and comments live on your Mac. The Codex CLI talks to its own model provider under your existing account, the same as when you run it in a terminal.
What stops a Codex run from looping on a failing task?
Strikes. Each run that ends without Done adds one; at the cap, 3 by default, the card stops auto-dispatching and lands in Blocked with a comment. An optional rescue attempt hands the last try to a stronger agent, and a teacher step writes the lesson into .portbay/LEARNINGS.md.
Give your projects and your agents a real local home.
Download for macOSFree & open source · macOS 11+ on Apple Silicon · Pro from $10/mo