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: its code is in yokka-ai/runner, and it’s published on npm as yokka-runner. 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. See Plans.

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. On a Yokka server other than yokka.ai, the command adds --server with your deployment’s address; the dialog shows it filled in.
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.

Commands

Command	What it does
yokka-runner	Connects and takes runs. Leave it running.
yokka-runner login	Signs this machine in (--server, --name).
yokka-runner map [folder]	Links a folder to a project (--project, --mode in-place or worktree, --allow-dirty).
yokka-runner unmap [project]	Forgets a project’s folder.
yokka-runner status	Shows the config, the projects, and whether each agent is ready.
yokka-runner config [key value]	Shows or changes a setting, like maxConcurrent or an agent’s permission mode.
yokka-runner logout	Forgets the token.
yokka-runner verify	Prints the version and how to check where this build came from.

Run each with npx in front, or install it with npm install -g yokka-runner. The runner’s README lists every setting. If the runner says it’s too old for your workspace, npx may be running a copy it saved earlier: run npx yokka-runner@latest instead.

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. 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. With no runner connected yet, the menu offers Set up a runner.

Start cards automatically

An auto-start rule starts a run whenever a card enters a lane, however it got there: dragged, moved by another rule or filed there. In Project settings → Flow, add a rule with the event Card enters a lane, then pick the lane and which agent to start on which of your runners. Auto-start is on Pro and up (see Plans).

An auto-start rule leaves alone a card an agent holds, a card with a run going, and a blocked card (it starts it once its last blocker is done). If a run ends without finishing the card, the rule waits 10 minutes before starting it again unless someone moves it. Imported cards never start on their own.

The agent reads the card’s title and brief and acts on them on your machine, so a rule only starts cards whose title and brief you last wrote: in the app, or through your own agents and tokens. When a teammate or their agent filed or rewrote the card, it doesn’t start on its own. The card’s activity says so, and you start it with Start once you’ve read it. Editing the brief yourself counts as writing it.

Because the rule runs agents on your machine, only you or a workspace admin can switch it on or off, change it or delete it. Teammates can still move it in the list.

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, ~/.yokka/runner.json.

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.