Local runners

Install, register, run, and troubleshoot a Labor0 local runner for workspace-owned task execution.

Use hosted Labor0-managed runners for normal work. Use a local runner when work needs private network access, local caches, a specific operating system, special tools, or a machine you control.

A local runner executes commands with the privileges of the user or service account that starts it. Run it only on machines you trust for the workspace repositories and setup commands it will execute.

Choose hosted or local execution

Hosted runners are the default when the repository can build in the standard hosted environment.

Choose a local runner when work needs:

private network access or local services
a machine-local package manager, license, device, or cache
a specific operating system or architecture
direct control over checkout and generated-file locations

When an active local runner is registered for a workspace, eligible work can use that runner. Leave the daemon running when you expect Labor0 to use the machine.

Download and verify

Start from the authenticated app:

Open the Labor0 app.
Choose the workspace that should own the runner.
Go to Settings > Runners.
Start the local runner setup flow.
Download the matching release archive and SHA256SUMS file when the app points you to them.

Release artifacts use this naming pattern:

Operating system	Architecture	Artifact
Linux	amd64 / x64	`labor0-runner_<tag>_linux_amd64.tar.gz`
Linux	arm64	`labor0-runner_<tag>_linux_arm64.tar.gz`
macOS	amd64 / Intel	`labor0-runner_<tag>_darwin_amd64.tar.gz`
macOS	arm64 / Apple Silicon	`labor0-runner_<tag>_darwin_arm64.tar.gz`
Windows	amd64 / x64	`labor0-runner_<tag>_windows_amd64.zip`
Windows	arm64	`labor0-runner_<tag>_windows_arm64.zip`

Replace <tag> with the release tag.

Verify the archive before installing it. On Linux:

grep " labor0-runner_<tag>_linux_amd64.tar.gz$" SHA256SUMS | sha256sum -c -

On macOS:

grep " labor0-runner_<tag>_darwin_arm64.tar.gz$" SHA256SUMS | shasum -a 256 -c -

On Windows PowerShell, compare the displayed hash to the matching line in SHA256SUMS:

Get-FileHash .\labor0-runner_<tag>_windows_amd64.zip -Algorithm SHA256

Extract the archive and put the binary on your PATH:

tar -xzf "labor0-runner_<tag>_<os>_<arch>.tar.gz"
./labor0-runner --help

For Windows:

Expand-Archive .\labor0-runner_<tag>_windows_amd64.zip -DestinationPath .\labor0-runner
.\labor0-runner\labor0-runner.exe --help

Register from the app

The normal first-run path is:

Open the workspace in the app.
Go to Settings > Runners.
Register a local runner with a display name that identifies the machine.
Copy the one-time l0r_ runner token or daemon command before leaving the result screen.
Start labor0-runner daemon on the local machine with that token.

Runner tokens are secret and one-time visible. Do not commit them, log them, paste them into issues, share them in chat, or store them in repository .env files.

Register from the CLI

You can also register from the CLI when you have a Labor0 user API token and the tenant/workspace scope:

export LABOR0_GRAPH_AGENT_URL="https://graph-agent.api.labor0.com"
export LABOR0_TOKEN="<Labor0 token>"

labor0-runner register \
  --tenant-id "<tenant_uuid>" \
  --workspace-id "<workspace_uuid>" \
  --display-name "$(hostname)"

Useful register inputs:

Input	Purpose
`--server` or `LABOR0_GRAPH_AGENT_URL`	Labor0 runner service URL. Use `https://graph-agent.api.labor0.com` for production.
`--auth-token` or `LABOR0_TOKEN`	Labor0 user API token used only for registration.
`--tenant-id` / `LABOR0_TENANT_ID`	Tenant id for the runner scope.
`--workspace-id` / `LABOR0_WORKSPACE_ID`	Workspace id for the runner scope.
`--display-name`	Human-readable runner name shown in the workspace.
`--config` / `LABOR0_RUNNER_CONFIG`	Config file path for storing server URL, runner token, and work directory.
`--no-color` or `NO_COLOR`	Disables ANSI color in runner logs.

The register command exchanges the user API token for a workspace runner token and writes that runner token to the local config file.

Run the daemon

After CLI registration, start the daemon from the saved config:

labor0-runner daemon

After app registration, pass the one-time token:

export LABOR0_RUNNER_TOKEN="<l0r_runner_token>"

labor0-runner daemon \
  --server "https://graph-agent.api.labor0.com"

For a smoke test that attempts one lease and exits:

labor0-runner daemon --once

Useful daemon inputs:

Input	Purpose
`--server` or `LABOR0_GRAPH_AGENT_URL`	Labor0 runner service URL. Defaults to saved config, then local development.
`--runner-token` or `LABOR0_RUNNER_TOKEN`	`l0r_` runner token. Defaults to saved config when present.
`--config` or `LABOR0_RUNNER_CONFIG`	Local config path.
`--work-dir` or `LABOR0_RUNNER_WORK_DIR`	Workspace root for checkouts and runtime files.
`--once`	Acquire at most one lease, then exit.
`--poll-interval`	No-work and cancellation polling interval.
`--lease-duration`	Requested lease duration for acquisition and renewal.
`--no-color` or `NO_COLOR`	Disables ANSI color in runner logs.

Run the daemon under your normal service manager for long-lived operation. Keep the token in the service manager's secret storage or a user-only runner config file.

Config and work directories

Defaults use the operating system's user config and cache directories:

Platform	Config default	Work directory default
Linux	`${XDG_CONFIG_HOME:-$HOME/.config}/labor0/runner.json`	`${XDG_CACHE_HOME:-$HOME/.cache}/labor0/runner-workspaces`
macOS	`$HOME/Library/Application Support/labor0/runner.json`	`$HOME/Library/Caches/labor0/runner-workspaces`
Windows	`%AppData%\labor0\runner.json`	`%LocalAppData%\labor0\runner-workspaces`

Each acquired phase gets an isolated workspace under the work directory:

<work-dir>/
  <agent_task_session_id>/
    <runner_phase_id>/
      repositories/
        <repository_id>/

Treat the work directory as sensitive because it contains repository source and generated files.

Setup commands and tools

Project runner setup commands are configured in project settings. Each non-empty line runs after checkout or checkpoint restore and before the selected agent runtime starts.

Project-level Runner MCP servers are also configured in project settings under Project Settings > Runners. Those saved MCP servers are attached to future runner sessions automatically, but only when the configured endpoint is reachable from the machine that runs the session.

Local runners rely on tools installed on your machine. Common tools include:

Git
GitHub CLI gh
selected agent runtime CLI: codex, claude, or opencode
project build tools such as Go, Rust, Python, Node.js, pnpm, compilers, and system libraries

Do not put secrets in runner setup commands. Manage runtime credentials from workspace runtime credential settings.

Local runners and Runner MCP

Use Project Runner MCP settings for remote MCP servers that have a public HTTPS endpoint and should be shared by future sessions for one project.

Use machine-local MCP configuration instead when the server:

runs through stdio on the local machine
listens on localhost
depends on a private subnet, VPN, loopback, or machine-local socket
should exist only on one developer machine instead of every future project session

Hosted runners cannot reach those local or private targets. A local runner can, but only if the MCP server is configured on that machine and the process is already available there.

Troubleshooting

Common symptoms:

Symptom	What to check
`register requires --auth-token or LABOR0_TOKEN`	Create a Labor0 user API token, then pass it through `LABOR0_TOKEN` or `--auth-token`.
`register requires --tenant-id and --workspace-id`	Use the tenant and workspace values shown by the app setup flow.
`daemon requires --runner-token`	Register the runner, set `LABOR0_RUNNER_TOKEN`, pass `--runner-token`, or use the saved config.
`no runner work acquired` with `--once`	The daemon reached Labor0, but no eligible pending work was available.
Repeated lease acquisition failures	Check network access, token rotation or disablement, workspace scope, and configured server URL.
Setup command failure	Re-run the command manually in the checkout, then adjust project setup or local dependencies.
Project Runner MCP works on hosted runners but not this local runner	Verify the MCP endpoint is reachable from the local runner machine, or move that server into the machine-local agent config if it depends on local/private access.
Project Runner MCP does not appear in a session after editing settings	Start a new session. Project Runner MCP changes apply to future sessions only.
Runner MCP preview says reconnect required	Return to `Project Settings` > `Runners` and reconnect the shared Hub authorization connection for that project server.
`gh is not available`	Install GitHub CLI and make sure it is on `PATH` for the daemon service account.
Task canceled	The app canceled the active work. The daemon observes cancellation and stops child processes.

Cancel work from the Labor0 app when possible. Ctrl+C or service shutdown stops the daemon; if a lease is active, the runner attempts to release recoverable work before it exits.

Read Getting started before registering a runner.
Read Pricing and credits for usage visibility.