The Runner

The Runner is the process that runs your sessions on your machine. It finds the harness and your checkouts, runs the agent, and reports the log and the result to the dashboard. Each member has one Runner.

Start it

The runner page of the settings shows the exact command, with the address of your dashboard. It looks like this.

npx -y --@tillerly:registry=https://gitlab.com/api/v4/projects/88180444/packages/npm/ \
  @tillerly/runner --url <your dashboard>

Keep the registry flag, the package is published there.

To keep it running in the background, install it once and make it a service. It must be paired first.

tillerly-runner service install
tillerly-runner service status
tillerly-runner service uninstall

Pair it

The Runner prints a code and a link, and opens your browser on the link. The page names the Runner and its machine, and you choose Pair this Runner. Pair only a Runner you started yourself. The code works while the Runner keeps asking, and for one minute after.

Pairing another machine revokes the old one. Revoke stops what the Runner runs, and the Runner deletes its credentials and asks to be paired again.

When it is offline

Queued sessions wait, and the dashboard says that your Runner is offline. If the connection drops, a running session goes on for up to two minutes, then ends as interrupted, and you can resume it. What the Runner has to report waits on your machine until the dashboard answers.

Where it keeps things

Its data is in ~/.tillerly, or wherever TILLERLY_DATA_DIR points. Its credentials file is readable only by you. A run's folder is removed when the run ends. The repositories Tillerly clones for you are in ~/.tillerly-clones.

Worktrees

Each ticket a resolver works on gets its own worktree, beside its repository, in <repository>.tickets/slot-<n>/<ticket>. The Worktrees list of the runner page shows each one with its git state, and its owner can delete it, unless a session is queued or running on it. The Runner never deletes a clone or a worktree on its own. A resolver removes its ticket's worktree once the pull request is merged or declined.

A session reaches its worktree only through four tools the Runner serves it on your machine, open_worktree, sync_worktree, push_branch and remove_worktree. It never pushes by force. The Runner opens no port to the outside.