Runners

A runner connects a computer that has your code to your workspace. Press Start on a card, from the board or your phone, and the runner starts Claude Code or Codex on that computer to work the card. The agent then works it like any other: it claims the card, reports progress and completes it over MCP.

The runner is a small open-source program. It drives the claude and codex you already have installed and signed in, connects outward only (no open ports or tunnels), and keeps your folder paths on that machine.

Runners come with Pro (up to 5), Team (5 per seat) and Enterprise.

Connect a machine

Go to Workspace settings → Agents → Runners and choose Connect a runner. On the machine, with Node 22 or newer and Claude Code or Codex installed and signed in:

1. Sign it in. Run npx yokka-runner login. It opens Yokka to confirm a code: check that the machine and code match your terminal, pick the workspace and choose Connect. You need to be a member or admin of that workspace, not a viewer.
2. Map a project. In a project’s folder, run npx yokka-runner map to link the folder to its Yokka project.
3. Start it. Run npx yokka-runner and leave it running.

The runner’s row in settings shows whether it’s online, the agents it found with their versions (or why one can’t run, like not being signed in), and each project it has a folder for.

In place or a worktree

When you map a folder you choose how runs work there:

• In place: the agent works in the folder itself, on whatever branch is checked out, one run at a time.
• Worktree per run: each run gets its own git worktree and branch, so several cards can run at once without treading on each other.

For a project that runs in place, the Start menu offers Use a worktree for this run.

Start a card

A card’s Start button offers every way to hand it to an agent:

• Run on a machine: each of your runners with each agent it has, like laptop · Claude Code. An offline runner picks the run up when it’s back.
• Open in the app on this computer: opens the agent’s desktop app with a short start prompt (not on phones).
• Copy prompt: copies the prompt to paste into any agent.

The main button repeats what you used last on that device. A card can have one runner run going at a time, and a card another agent holds has to be released first.

Follow and steer a run

The card shows the live run and what you can do about it:

• Answer or open it in the agent’s app. Anything the agent needs a person for, like a question or a permission prompt, is answered in its own app. A Claude Code run is a Remote Control session, so Open in Claude (or Answer in Claude) opens it in the Claude app, on your phone too. A Codex thread is locked in the Codex app while the runner holds it: Continue in Codex hands it over, and you carry on there.
• Pause stops the agent without losing its conversation; Resume wakes the same session.
• Stop ends the run, or takes it off the queue if it hasn’t started.

When a run ends, the card keeps it with its branch, how many commits it made, any uncommitted files, and its summary. With push notifications turned on (Account → Notifications), you hear when a run needs you and when it finishes.

Who can use a runner

A runner only ever starts runs for its owner, the person who connected it. Nobody else in the workspace, admins included, can start a run on someone else’s machine, and other people’s runners don’t appear in their Start menu.

• The owner, the person who started a run and admins can pause, resume and stop it.
• The owner and admins can disconnect a runner. Its runs stop, and the machine has to sign in again to start any more.
• A runner stops working when its owner leaves the workspace, is removed or becomes a viewer.

What stays on your machine

The board can only ask a runner to start, pause, resume or stop a run for a card. It never sends a command or a folder path. Which folder belongs to which project lives only in the runner’s local config.

The server keeps the runner’s name, hostname and operating system, the versions of the agents it found, which projects it has a folder for and in which mode, and each run’s status and git summary. Each run gets its own agent token, which stops working when the run ends. See Data, privacy and security.