Runners¶
Review workflows run in the arnold-runner image (ghcr.io/phonepe/arnold-runner). The backend setting
runner.mode (ARNOLD_RUNNER_MODE) decides how jobs reach a runner. Every mode uses the same image and the same job
contract: a flat set of variables such as WORKFLOW, ARNOLD_RUN_ID, MR_LINK and EXECUTION_ID.
| Mode | How a job reaches a runner | Runner credentials live in | Good for |
|---|---|---|---|
LOCAL (default) |
Jobs are queued in Arnold; worker processes long-poll and claim them |
Worker environment | Docker Compose, Kubernetes, VMs |
GITLAB |
Arnold triggers a pipeline in a runner project with the job as pipeline variables | Runner project CI/CD variables | Reusing GitLab CI capacity |
GITHUB |
Arnold queues the job and dispatches a workflow with only the job number; the workflow claims it | Runner repository secrets | Reusing GitHub Actions capacity |
In every mode the runner posts review comments to the forge directly and reports results to Arnold. It needs outbound access to the backend, the forge and the LLM endpoint, and no inbound access.
Runner API key¶
Runners authenticate to the backend with a shared API key sent as a bearer token. The backend entry needs these roles:
serviceCoreConfiguration:
auth:
apiKeys:
- name: runner
key: ${ARNOLD_RUNNER_API_KEY}
roles: [runner_execute, analysis_callback_write, smart_diff_callback_write, review_feedback_write]
Set the same ARNOLD_RUNNER_API_KEY for the backend and every runner. Generate a strong value
(openssl rand -hex 32); the example local-runner-key-change-me is for local use only.
Forge credentials for jobs¶
| Forge | Credential |
|---|---|
| GitHub | With the GitHub App configured, each job carries a short-lived installation token for the PR's repository (SCM_GITHUB_TOKEN). Nothing to configure on runners |
| GitLab | The runner's own GITLAB_ACCESS_TOKEN (api scope) |
LOCAL¶
Workers poll POST /runner/v1/jobs/claim, send heartbeats while working, and post completion. A job whose worker stops
heartbeating for runner.local.leaseSeconds (300) is requeued, up to runner.local.maxAttempts (2), then marked failed.
docker run --rm \
-e ARNOLD_URL=https://arnold-api.example.com \
-e ARNOLD_RUNNER_API_KEY=... \
-e GITLAB_ACCESS_TOKEN=glpat-... \
-e CLIO_HARNESS=opencode \
-e CLIO_LLM_BASE_URL=https://api.openai.com/v1 \
-e CLIO_LLM_API_KEY=sk-... \
ghcr.io/phonepe/arnold-runner:latest worker --concurrency 2
| Option | Env | Default | Purpose |
|---|---|---|---|
--concurrency N |
ARNOLD_RUNNER_CONCURRENCY |
1 | Jobs processed in parallel by this worker |
--name |
ARNOLD_RUNNER_NAME |
hostname | Worker name prefix used in job leases |
--once |
Handle one claim per slot, then exit | ||
ARNOLD_RUNNER_JOB_TIMEOUT |
9900 s | Hard limit per job, in seconds |
Scale by running more workers. Each job clones repositories into a temporary directory and runs an agent, so allow roughly 1 CPU and 2 GB memory per concurrent job, plus disk for checkouts.
Without Docker: cd arnold-runner && pip install -r requirements.txt && npm i -g opencode-ai && python main.py worker.
GitLab CI¶
-
Create a project for the runner, e.g.
acme/arnold-runner, and add this.gitlab-ci.yml:.gitlab-ci.yml# Arnold runner pipeline for runner.mode: GITLAB. # # Put this file (or an `include:` of it) in the runner project's .gitlab-ci.yml. Arnold starts pipelines through the # pipeline trigger API and passes the job as pipeline variables (WORKFLOW, ARNOLD_RUN_ID, MR_LINK, ...). # # Configure these as masked + protected CI/CD variables in the runner project: # ARNOLD_URL, ARNOLD_RUNNER_API_KEY callback endpoint and runner API key (backend auth.apiKeys) # GITLAB_ACCESS_TOKEN token used to read MRs and post review comments # CLIO_LLM_BASE_URL, CLIO_LLM_API_KEY OpenAI-compatible LLM endpoint (OpenCode and simple LLM calls) # GITHUB_TOKEN only for the opt-in Copilot harness without Arnold execution keys # # The image is fixed here rather than read from a variable: anyone able to trigger the pipeline could otherwise point # it at an image of their choosing and receive the masked variables above. To use a mirror or a pinned version, edit # this line in your copy. arnold-runner: image: ghcr.io/phonepe/arnold-runner:latest rules: - if: '$CI_PIPELINE_SOURCE == "trigger" && $WORKFLOW' script: - python /app/main.py job timeout: 2h 45m -
Add masked, protected CI/CD variables:
ARNOLD_URL,ARNOLD_RUNNER_API_KEY,GITLAB_ACCESS_TOKEN,CLIO_HARNESS,CLIO_LLM_BASE_URL,CLIO_LLM_API_KEY. - Create a pipeline trigger token: Settings โ CI/CD โ Pipeline trigger tokens.
-
Configure the backend:
.envARNOLD_RUNNER_MODE=GITLAB RUNNER_GITLAB_PROJECT_ID=123 RUNNER_GITLAB_PROJECT_PATH=acme/arnold-runner RUNNER_GITLAB_REF=main RUNNER_GITLAB_TRIGGER_TOKEN=glptt-...The triggering GitLab is
GITLAB_URL. In Docker Compose, also removeARNOLD_RUNNER_MODE: LOCALfrom theserverservice, or it overrides.env, and stop the localrunnerservice.
Warning
Keep CI debug tracing off. Job variables can include short-lived execution keys for the Copilot harness.
GitHub Actions¶
-
Create a private repository for the runner, e.g.
acme/arnold-runner, and add this workflow as.github/workflows/arnold-runner.yml:.github/workflows/arnold-runner.yml# Arnold runner workflow for runner.mode: GITHUB. # # Copy to .github/workflows/arnold-runner.yml in the runner repository (keep that repository private). Arnold queues # the job and dispatches this workflow with only the job number; the workflow claims the job from Arnold with the # runner API key, so job details never appear in workflow inputs. # # Repository secrets: # ARNOLD_URL, ARNOLD_RUNNER_API_KEY callback endpoint and runner API key (backend auth.apiKeys) # SCM_GITLAB_TOKEN token for GitLab-hosted merge requests (optional) # SCM_GITHUB_TOKEN token for GitHub-hosted pull requests (optional) # CLIO_LLM_BASE_URL, CLIO_LLM_API_KEY OpenAI-compatible LLM endpoint name: arnold-runner on: workflow_dispatch: inputs: job: description: Arnold runner job number required: true permissions: contents: read concurrency: group: arnold-runner-${{ inputs.job }} cancel-in-progress: false jobs: run: runs-on: ubuntu-latest timeout-minutes: 165 container: image: ghcr.io/phonepe/arnold-runner:latest steps: - name: Run Arnold job env: ARNOLD_URL: ${{ secrets.ARNOLD_URL }} ARNOLD_RUNNER_API_KEY: ${{ secrets.ARNOLD_RUNNER_API_KEY }} GITLAB_ACCESS_TOKEN: ${{ secrets.SCM_GITLAB_TOKEN }} GITHUB_TOKEN: ${{ secrets.SCM_GITHUB_TOKEN }} CLIO_LLM_BASE_URL: ${{ secrets.CLIO_LLM_BASE_URL }} CLIO_LLM_API_KEY: ${{ secrets.CLIO_LLM_API_KEY }} JOB: ${{ inputs.job }} run: | case "$JOB" in ''|*[!0-9]*) echo "invalid job number" >&2; exit 2 ;; esac python /app/main.py job --claim "$JOB" -
Add repository secrets:
ARNOLD_URL,ARNOLD_RUNNER_API_KEY,CLIO_LLM_BASE_URL,CLIO_LLM_API_KEY, andSCM_GITLAB_TOKENif you also review GitLab MRs. - Create a token that can dispatch workflows in that repository: a fine-grained PAT with Actions: Read and write on it only.
-
Configure the backend:
The workflow input carries only the job number. The workflow claims the job from Arnold, so review details and tokens never appear in workflow inputs or logs.
Choosing a mode¶
- Start with
LOCAL. It has the lowest latency (no pipeline start-up) and the fewest moving parts. - Use
GITLABorGITHUBwhen reviews must run inside an existing CI trust boundary or you want CI to absorb the compute. Expect 20โ60 seconds of extra start-up per run. GITLABandGITHUBmodes need the backend reachable from CI runners (ARNOLD_URL).