Run Cursor agents from a local task board
Move a card to To Do and PortBay opens Cursor on the project folder, with the card as the brief. The work happens on your Mac, in a project that is already running at a real URL.
How do I run Cursor agents on a queue of tasks?
An editor-based agent needs two things a checkout alone does not give it: a written brief, and a running app to check the work against. Cursor shipped parallel-agent orchestration in April 2026, which handles the checkouts; PortBay adds the other two. Each card is a Markdown file in .portbay/tasks/, so tasks version with your code. Move one to To Do and PortBay dispatches Cursor — unlike the headless CLI agents it opens as a desktop app on the project folder, pointed at the card — while the project underneath is already serving on a real .test domain with trusted HTTPS, a per-project database and captured mail. The run reads .portbay/HANDOFF.md first and the card comes back with comments; a strike system stops a failing card after 3 runs by default. Settings → Integrations writes Cursor's MCP config, so the editor can drive PortBay too.
Verified against the product, 2026-07-10.
One card, opened in Cursor
Assign Cursor, move the card to To Do, and PortBay opens the editor on the project folder. The card tracks the run and comes back with comments.
Your first card opened in Cursor
Six steps from a clean Mac to a Cursor run you can review at a real URL. Every command runs as written.
- Install PortBay
- Add your project
- Connect Cursor over MCP (optional)
- Write a card and assign Cursor
- 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 Cursor over MCP (optional)
Settings → Integrations detects the agents on your Mac and writes the MCP config for each client. For Cursor the entry lands in mcp.json, global or per-project, pointing at the bundled portbay-mcp binary. A connected editor can read the board and move cards.
~/.cursor/mcp.jsonWrite a card and assign Cursor
Describe the task the way you would brief a teammate. Assign Cursor 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/redesign-empty-states.mdMove the card to To Do
Auto-dispatch opens Cursor as a desktop app on the project folder the moment the card lands. Manual mode queues the card and asks you to confirm each run. Other cards can dispatch to headless CLI agents at the same time.
Review the work at a real URL
The work lands in your repo, the card collects comments, and a hand-off entry goes to .portbay/HANDOFF.md. Open the project URL and review against the running app. Turn on Require review to hold agent-reported work for your approval.
https://myapp.testThe same afternoon, without a board
Running Cursor by hand makes you the dispatcher: you open the editor, paste the task, and check back. Nothing records what ran, what changed, or what comes next.
The board replaces the pasting and the checking back: cards carry the brief, comments carry the result, and the hand-off note carries the context.
# the manual loop: you are the dispatcheropen -a Cursor ~/code/myapp# paste the task into the agent pane, wait, check back# repeat for the next task: no queue, no record, no hand-off # task state: a notes file and your memory# "what did that session change again?"
The pieces underneath
Asked before downloading
How does PortBay launch Cursor?
As a desktop app, opened on the project folder with the card as the brief. Most agents on the board launch as headless CLI subprocesses; Cursor is one of the few that opens as an app. PortBay auto-detects the agents installed on your Mac.
Can Cursor cards run next to CLI agents on the same board?
Yes. Assignment is per card, with an optional board default. One card can open Cursor while others dispatch Claude Code or Codex headless, and a concurrency cap decides how many runs go at once.
What does Cursor get besides the card?
A running project: a real .test domain with trusted HTTPS, a per-project database, and captured mail. Each run also reads the rolling hand-off note in .portbay/HANDOFF.md first, so it starts where the last run stopped instead of from a cold start.
Do I need PortBay Pro to dispatch Cursor from the task board?
No. The board and agent dispatch ship in the free Community tier, and the app is open source (AGPL-3.0). Pro raises ceilings around it, such as larger task attachments and unlimited projects.
Give your projects and your agents a real local home.
Download for macOSFree & open source · macOS 11+ on Apple Silicon · Pro from $10/mo