OpenCode runs the card, in an app that is already up
PortBay spawns `opencode run` with the card's brief as its argument, in a project serving at a real URL with a database attached. Open source on both sides of the dispatch.
How do I run OpenCode against a board of tasks?
PortBay detects the `opencode` binary on your PATH and offers it in the agent picker. Assign it to a card and move that card to To Do: PortBay spawns `opencode run "<the card>"` headless, with the working directory set to your project. OpenCode has a tool-calling loop and edits files, which means the thing that limits it is usually not the model but whether there is anything to call — and that is what PortBay provides. The project is already serving on its own .test hostname behind a certificate macOS trusts, a per-project database is attached and its connection variables injected, and outgoing mail is captured locally, so the agent can request the route it just wrote. Each card takes its own git worktree under .portbay/worktrees/, so several agents work one repo without collision, and a strike system stops a card after three failed runs. Both PortBay and OpenCode are open source, and nothing in the round trip leaves your Mac except the model call OpenCode makes on your own key.
opencode run, dispatched from a card
The card is the argument. The environment is what the tool loop has to work with once the run starts.
Your first OpenCode card
Five steps from a clean Mac to an OpenCode run you can open in a browser. Every command runs as written.
- Install PortBay
- Add your project and press play
- Check opencode resolves
- Write a card and assign OpenCode
- Move the card to To Do, then open the result
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 and press play
PortBay detects the stack from the folder, fills in the start command and port, issues the mkcert certificate and attaches a database. The project is now something an agent can actually exercise.
portbay add ~/code/myappCheck opencode resolves
PortBay looks for opencode on your PATH. Set the path by hand if yours is installed somewhere unusual. Keys stay where OpenCode already reads them — PortBay stores none and proxies nothing.
which opencodeWrite a card and assign OpenCode
Brief the task and say how you will know it worked — a URL that should load, a test that should pass. Assign OpenCode on the card, or set it as the board default.
.portbay/tasks/add-search-endpoint.mdMove the card to To Do, then open the result
The run starts in its own worktree and comments what it changed. Open the project URL and use it. Need flags PortBay's default invocation does not pass? Switch the card to the Custom agent and supply the exact command template.
https://myapp.testThree OpenCode runs, one working tree
OpenCode is easy to start twice. Starting it twice in the same checkout is the problem.
A card per run means a worktree per run: same repo, separate files, merge when the card reaches Done.
cd ~/code/myappopencode run "add the search endpoint" # tab 1opencode run "fix the flaky cart test" # tab 2 # both are editing the same files on the same branch# whichever writes last wins, and neither knows
The pieces underneath
Asked before downloading
How does PortBay launch OpenCode?
As a headless subprocess: `opencode run "<the card>"`, with the working directory set to the project folder. It uses the opencode install already on your Mac and whatever credentials that install already reads.
What if I need flags PortBay does not pass?
Use the Custom agent. PortBay's built-in invocations are deliberately the common run-this-prompt form rather than an exhaustive flag surface, and the Custom option runs any CLI from a command template you write — same board, same worktree, same card lifecycle.
Can I pick the model for an OpenCode card?
Not from PortBay. OpenCode is one of six agents with no wired model flag, so no model selector is shown and nothing is appended to the command. Configure the model where OpenCode already reads it.
Can OpenCode claim cards itself over MCP?
No. MCP is wired both ways for Claude Code, Codex, Cursor and Gemini only. OpenCode is dispatched to: cards move because you move them, or because auto-dispatch does it when one lands in To Do.
Give your projects and your agents a real local home.
Download for macOSFree & open source · macOS 11+ on Apple Silicon · Pro from $10/mo