Run the self-hosted runner

By default, kanman runs each story in an isolated machine in Frankfurt, Germany. If your code must not leave your network, run the coding work on your own infrastructure with the self-hosted runner.

How it works

The runner is the same executor host kanman uses in its cloud, packaged as the Docker image kanman/executor-host:

• It pulls work. It opens an outbound HTTPS connection to kanman, registers, asks for the next queued run of your workspace and reports back. No inbound ports, no VPN, no firewall exceptions for kanman.
• It authenticates with a workspace API token (km_...). It never receives database credentials. Each run it picks up gets its own run token, which stops working when the run ends.
• For each run it clones the repository, creates the run branch, starts the coding agent with the run’s brief and the kanman MCP, and reports progress, the diff summary, the commits and a transcript of the agent’s work.
• The repository checkout stays on your machine.

What the model provider receives is described in What model providers see. The coding agent calls the provider from the runner, with the key you give the runner or, for teams that use their own key, with that key.

Requirements

• A Linux host or VM with Docker. The runner needs CPU and memory like a CI job for your repository.
• Outbound HTTPS to kanman, to your git host, and to your model provider.
• A model provider key for the executors the runner offers: ANTHROPIC_API_KEY for Claude Code, OPENAI_API_KEY for Codex. Not needed for teams that use their own key in kanman; their key comes with the run.

Step 1: Create a token

1. Open Settings > API and click Create token.
2. Name it after the runner, for example runner-fra-1.
3. Choose an expiry (30 days, 90 days or 1 year) that matches your rotation policy. The runner needs no particular permission; any active token of the workspace works.
4. Copy the token. It is shown once.

Step 2: Start the runner

Settings > Runners shows the command to copy. With a name and both executors it looks like this:

docker run -d --name kanman-runner \
  --restart unless-stopped \
  -e KANMAN_API_KEY=km_your_runner_token \
  -e ANTHROPIC_API_KEY=your_anthropic_key \
  -e RUNNER_NAME=runner-fra-1 \
  -e RUNNER_EXECUTORS=claude-code,codex \
  -e OPENAI_API_KEY=your_openai_key \
  kanman/executor-host

Pin the image to a version tag in production and update deliberately.

Step 3: Check the status

Open Settings > Runners. The runner appears with its name, executors, version, the time it was last seen and its status. The list refreshes every 30 seconds:

Step 4: Send work to your runners

The choice applies to the whole workspace. Open Settings > AI providers, expand Advanced and turn off Kanman Cloud. From then on, queued runs of all teams go to your runners and are picked up in order. Settings > Runners confirms where runs execute. Concurrency still follows each team’s policy and its plan.

Scale and update

• More capacity: start more runners with different names, or raise RUNNER_CONCURRENCY on a larger host.
• Update: stop the container with enough time to finish its runs, for example docker stop --time 1800 kanman-runner. On stop the runner shows Finishing work, completes its runs and goes offline. Then start the new version.
• Rotate the token: create a new token, restart the runner with it, then revoke the old one. A revoked or expired token takes the runner offline.

Troubleshooting