Runners

Runners are AI agents that connect to Spedy and do work for you. When a ticket reaches a certain status, Spedy creates a job. A runner picks it up, writes the code, and delivers a pull request -- fully automatic.

Quick Overview

1. You store your Anthropic API key in Spedy (Settings → Runners → Secrets)
2. You connect GitHub / Bitbucket (Settings → Integrations) — the runner reuses the token automatically
3. You create a runner token in Spedy (Settings → Runners)
4. You download and set up the Spedy Supervisor on your machine or server
5. The supervisor authenticates with the token, fetches its secrets from the platform, and starts picking up jobs

The runner never stores Anthropic keys or git tokens on disk — they are delivered in memory at startup via GET /runners/bootstrap.

Step 1: Store the Anthropic API Key on the Platform

The runner fetches its Claude credentials from Spedy at startup — you don't put the key into local config files anymore.

1. Open Settings → Runners
2. Switch to the Secrets tab
3. Click Add secret, pick Anthropic (Claude) as the preset, paste your sk-ant-… key
4. Save

The value is encrypted at rest with AES-256-GCM and only ever decrypted inside the /runners/bootstrap response for authenticated runners. Even admins cannot read the full value back — to rotate, paste a new value.

Skip this step if you plan to use the Local Claude (Max/Pro) flow instead. In that case the supervisor will use your local Claude credentials and no Anthropic key is needed.

Step 2: Connect Git (GitHub / Bitbucket)

The runner reuses your existing git integrations automatically. If you already have GitHub or Bitbucket connected under Settings → Integrations, there is nothing to do for the runner. If not, add the integration there — the runner will pick up the token on its next bootstrap.

GitHub Integration Permissions

The GitHub token stored on the Integration needs the following scopes so the runner can clone repositories, create branches, and open pull requests:

Recommended: Use a fine-grained personal access token or the Spedy GitHub App, scoped to only the repositories the runner should access. This follows the principle of least privilege.

Step 3: Create a Runner Token

1. Open Settings → Runners
2. In the Runners tab, find the token management section
3. Click Create Token and give it a name (e.g., "My Dev Runner")
4. Copy the token immediately -- it is only shown once

The token looks like this: rnt_a3f8c1d9e4b7... (64 hex characters after the prefix). After creation Spedy shows you the exact .env snippet you need locally plus a readiness checklist (Anthropic key present? Git integration active?). Use the Copy button to grab the snippet in one go.

Step 4: Install the Spedy Supervisor

The Spedy Supervisor is a lightweight program that runs on your machine or server. It manages one or more runner instances and connects them to Spedy.

Prerequisites

• Docker and Docker Compose installed
• The runner token from Step 3. Optionally a Claude Max subscription if you want OAuth mode instead of the platform-managed Anthropic key.

Download and Setup

1. Download the latest release:

wget https://spedy.ai/download/supervisor -O spedy-supervisor.zip

To download a specific version, append ?version=v0.0.6 (or whichever tag you need).

2. Unzip the archive:

unzip spedy-supervisor.zip
cd spedy-supervisor

3. Run the setup script:

./setup.sh

The setup wizard will ask you for the following:

The wizard no longer asks for an Anthropic API key or a GitHub/Bitbucket token — those come from the platform at startup. On the final Review step the wizard runs a readiness check and refuses to complete if ANTHROPIC_API_KEY isn't stored in the vault yet, so the runner never goes online just to fail on its first job.

OAuth Mode (Claude Max)

If you have a Claude Max subscription, you can skip the Anthropic API key entirely. The supervisor supports OAuth mode, where runners authenticate using your local Claude credentials instead of an API key.

To use OAuth mode:

1. Run claude once on your machine to create the ~/.claude credentials directory
2. During setup, leave the Anthropic API Key field empty
3. The setup script automatically detects ~/.claude and configures the volume mount

In OAuth mode, no API key is injected and no proxy is started — the Claude CLI inside the runner container uses its own credentials. The supervisor automatically mounts ~/.claude into each runner container.

Start the Supervisor

After setup, start the supervisor:

docker compose up -d

Other useful commands:

# View logs
docker compose logs -f

# Stop the supervisor
docker compose down

# Update to latest version
docker compose pull && docker compose up -d

Verify the Connection

Go to Settings → Runners → Runners tab. Your runner should appear with a green "Online" badge.

Managing Runner Secrets

Under Settings → Runners → Secrets you manage the credentials the runner fetches at startup:

• Anthropic (Claude) API key — the only officially supported LLM provider today.
• Custom env vars — anything else your jobs need (project-specific flags, build-time tokens, …). Pick the Custom scope and define the env-var name yourself.

GitHub and Bitbucket tokens do not belong here — they come from Settings → Integrations and are merged into the runner bootstrap automatically. MCP server credentials live on their own configurations under Settings → MCP Servers.

How values travel to the runner

1. You save a secret. The value is encrypted with AES-256-GCM before it hits the database.
2. The runner authenticates with its rnt_… token against GET /runners/bootstrap.
3. Spedy merges your vault entries with the tokens of your active git integrations, decrypts the values, and returns the bundle over TLS.
4. The runner holds the values in memory only and injects them into job containers as environment variables. Values are scrubbed when the job exits.

The runner re-fetches this bundle every 15 minutes, so rotating a secret propagates without a supervisor restart.

Rotate or remove a value

• Rotate: click the secret row → Edit → paste the new value. The rotation timestamp is recorded.
• Remove: click Delete. Runners lose access on their next bootstrap.
• Local override: if you have ANTHROPIC_API_KEY in your local .env, that value wins over the platform value. Remove the local line to let the platform manage the key.

Your keys, your responsibility

The Secrets tab shows a persistent reminder:

• Every job runs against your Anthropic key. Spedy does not cap, proxy, or subsidise token usage — costs bill directly to your Anthropic account.
• Set budgets and rate limits in the Anthropic dashboard and per-job token budgets under Runner Teams. Agent loops can spiral into six-figure cache-read counts if left uncapped.
• Never commit credentials, .env files, or private keys into repositories the runner touches. The agent reads the full working tree as context and may echo committed secrets back into logs, commits, or PR descriptions.

Migration for Existing Runners

If you already had runners connected before this update, Spedy shows a migration banner on Settings → Runners with exactly two steps:

1. Store your Anthropic API key under Settings → Runners → Secrets (follow Step 1 above).
2. Restart the supervisor once so it picks up the new bootstrap flow:

docker compose pull
docker compose up -d --force-recreate spedy-supervisor

The banner auto-hides as soon as the vault contains an ANTHROPIC_API_KEY. You can keep the old ANTHROPIC_API_KEY / GITHUB_TOKEN / BITBUCKET_* lines in your local .env during the transition — local values override the platform, so nothing breaks. Remove them once everything is green.

Step 5: Configure Runner Teams

Runner Teams are the central way to configure how runners process tickets. Each team defines its own status mappings, pipeline stages, and trigger behavior.

Creating a Runner Team

1. Open Settings → Runners
2. Switch to the Runner Teams tab
3. Click Create Team
4. Choose a pipeline preset as a starting point:
   • Code Runner -- starts with Planning + Coding + Review stages, creates PRs when there are code changes
   • Board Agent -- a single custom stage with read-only tools, suitable for research and project interactions
   • Review Team -- two AI reviewers (Security + Quality) work in parallel, a Review Lead synthesizes and verifies
   • Full-Stack Team -- backend and frontend agents work in parallel, an Integration Validator checks the collaboration
5. Configure the team name, description, and status mappings
6. Customize the pipeline stages as needed

Team Status Mappings

Each runner team has its own status configuration:

• Working Status -- the status tickets are moved to while the team is processing them (e.g., "AI Processing")
• Completion Status -- where tickets move after a successful job (e.g., "In Review")
• Failure Status -- where tickets move when a job fails (configurable per team, not a fixed status)

@Mention Triggers

Each team can have a mention handle (e.g., @helper or @codebot). When a user @mentions a team handle in a ticket comment, Spedy automatically creates a job for that team -- this is the BOARD_INTERACTION job type.

Per-Team Capabilities and Labels

Teams can specify capabilities (e.g., claude_code) and required labels (e.g., backend, frontend) to control which runners pick up their jobs. Only runners that match the team's capabilities and labels will receive jobs from that team.

Pipeline Stages

Each runner team has a pipeline of stages that define how a job is executed. Stages run in order, and each stage can have its own configuration.

Stage Types

Stage Configuration

Each pipeline stage can be configured with:

• System Prompt -- the instructions the AI follows during this stage
• Allowed Tools -- which tools the AI can use (e.g., Read, Edit, Write, Bash, Grep, Glob, WebSearch, WebFetch)
• Model Selection -- choose the AI model for this stage:
  • Haiku 4.5 -- fast and cost-effective
  • Sonnet 4.6 -- balanced performance
  • Opus 4.7 -- strongest reasoning (default for planning stages)
  • Opus 4.6 -- previous generation, still selectable for teams that rely on its specific behavior
• Role -- Planner (read-only) or Executor (read/write)
• Require Approval -- toggle to pause the pipeline and wait for human approval before this stage runs
• Validation Commands -- shell commands that run after a coding stage completes (e.g., npm run lint, npm test). If a command fails, the agent retries the stage and fixes the issue automatically. Maximum retries are configurable (0-10). Dangerous shell patterns (semicolons, pipes, backticks, redirects) are blocked server-side.
• Skills -- attach reusable skill instruction sets to augment the stage's behavior
• MCP Server Configs -- connect external tool servers via the Model Context Protocol

You can reorder stages by dragging them, enable or disable individual stages, and reset the pipeline back to the preset defaults.

Default Pipeline

The default Code Runner pipeline has three stages:

1. Planner (Opus 4.7) -- analyzes the ticket and creates a plan
2. Implement (Sonnet 4.6) -- writes the code based on the plan
3. Review (Sonnet 4.6) -- reviews the implementation for correctness, security, and quality, fixing issues directly

Skills

Skills are reusable instruction sets that you can attach to pipeline stages. They provide additional context, guidelines, or specialized knowledge for the AI.

Manage skills from Settings → Skills. Each skill has:

• A name (slug format, e.g., code-review-guidelines)
• A description used for trigger-matching
• A content body (the actual instructions in Markdown)

Skills can be scoped to the organization level or to a specific board. Attach skills to any pipeline stage to augment what the AI knows and how it behaves during that stage.

MCP Server Configs

MCP (Model Context Protocol) server configurations allow you to connect external tool servers that runners can use during pipeline execution. This extends the runner's capabilities beyond built-in tools.

Manage MCP servers from Settings → MCP Servers. Each configuration includes:

• A server URL (for SSE/HTTP transport) or a command (for STDIO transport)
• Optional authentication credentials
• An optional allowed tools filter

MCP server configs can be scoped to the organization or a specific board, and attached to individual pipeline stages.

Watching Jobs Run

Job Types

Job Statuses

Jobs progress through these statuses:

Cache Token Metrics

Every runner job view displays token usage details including cache performance. You can see:

• Cache Read -- number of tokens served from the prompt cache instead of being reprocessed
• Cache Write -- number of tokens written to the cache during this job
• Cache Hit Rate -- percentage of input tokens served from cache, calculated as cache read tokens divided by total input tokens

These metrics appear in the ticket runs panel, the runner job list, the active runners overview, and the streaming job view. A high cache hit rate means your runner is reusing prompt context efficiently, which reduces both latency and cost.

Streaming Jobs

Streaming jobs give you a live view of what the AI is doing. Click on a streaming job to see:

• Real-time text output from the AI
• Tool calls (file edits, commands) as they happen
• The ability to send input when the AI asks a question
• A stop button to pause the work
• A continue button to resume after a pause

The live event feed updates automatically -- you see everything as it happens.

When the orchestrator detects a blocker during planning (e.g., missing information or open questions), the streaming view shows an amber "Answers required" panel instead of the normal plan approval panel. The approve button is hidden until the blocker is resolved — use the input field to answer the agent's questions directly.

Cache Token Metrics

All job views display cache token metrics: cache read tokens, cache write tokens, and the cache hit rate as a percentage. This helps you understand how efficiently the runner uses the context cache and estimate costs. Cache metrics appear in the Ticket Runs Panel, Runner Job List, Active Runners widget, and Streaming Job View.

What Happens When a Job Fails?

When a runner job fails, the ticket is automatically moved to the team's configured failure status and receives an AI Failed badge. This makes it easy to spot tickets that need attention. When you drag the ticket back into the team's working status, the badge is cleared and a new job is created automatically.

Epic Orchestrator

The Epic Orchestrator lets you assign a runner team to an entire Epic. Instead of creating individual jobs for each ticket, the orchestrator resolves all child tickets, builds a dependency graph, and processes them automatically in the correct order.

Starting an Epic Run

1. Open an Epic that has subtickets or stories
2. Assign a runner team to the Epic
3. The orchestrator starts automatically and shows progress in the Epic Run Panel

How It Works

• Dependency resolution: The orchestrator builds a directed graph from BLOCKS ticket links and parent-child relationships. Parent tickets always wait for their children to complete first.
• Wave-based execution: Tickets with no pending dependencies are dispatched in parallel. Once a wave finishes, the next group of unblocked tickets is released.
• Shared branch: All sub-runs commit to a single epic/<display-id> branch — no merge conflicts from separate PRs.
• Automatic PR: When all tickets complete, the orchestrator opens a pull request from the epic branch against the repository's default branch.
• Epic ticket moves: On completion, the Epic ticket is automatically moved to the runner team's completion status (e.g., "Review").

Pause, Resume, and Restart

• Pause: If a sub-run fails, the entire epic run pauses automatically. You can retry the failed ticket or skip it (downstream tickets that depend on it are also skipped).
• Continue: Resume a paused or cancelled run — only unfinished tickets are dispatched. Newly added subtickets are picked up automatically.
• Restart: Reset and re-run the entire Epic from scratch. Completed nodes are cleared and all tickets start fresh.

Limits

Each epic run is capped at 100 child tickets to prevent runaway costs. If your Epic has more than 100 subtickets or stories, split it into smaller Epics.

Epic Run Panel

The panel on the Epic ticket shows:

• Current run status (Running, Paused, Completed, Failed, Cancelled)
• Per-ticket status within the run
• A link to the epic branch on the git provider
• Direct links to the final PR(s) once the run completes
• Continue / Restart buttons for terminal runs

Per-Project Runner Setup (Build & Validate)

Each project can have its own runner configuration. In the project settings, the Build & Validate section lets you configure which runner team handles tickets for that project and set project-specific trigger behavior. The setup displays the working directory (/workspace/{repoName}) for each connected repository.

Per-Repository Base Branch

Every repository linked to a project stores its own base branch. When you add a repository, Spedy automatically picks up the provider's default branch (GitHub, GitLab, Bitbucket). You can override it any time from the Build & Validate section in project settings.

The base branch controls:

• The branch the runner cuts new feature branches from
• The target branch for the pull requests it opens

This means multi-repo projects can use a different base branch per repository -- for example, main on one repo and develop on another. The repository list shows a badge with the current base branch for each entry, so you can see at a glance where the runner will branch from and push against.

Automatic Retrigger on PR Review

When a reviewer requests changes on a pull request, Spedy can automatically retrigger the runner to address the feedback — without any manual intervention.

How It Works

1. A runner completes a job and opens a pull request
2. A reviewer leaves a "Changes Requested" review on the PR (GitHub or Bitbucket)
3. Spedy receives the webhook and creates a new runner job
4. The runner picks up the job, reads the review comments, and pushes a revised commit

The new job includes the full review context: the reviewer's summary comment and all inline comments with their file location and line number.

Requirements

• Git integration must be active for the repository (Settings → Integrations)
• Runner retrigger on review must be enabled in Settings → Runners → Settings
• The pull request must be linked to a ticket in Spedy (this happens automatically when the runner creates the PR)

Guards and Safeguards

Spedy applies several checks before triggering a new job to avoid unnecessary or duplicate work:

What the Runner Receives

The runner job prompt includes:

• The original ticket description
• A summary of the reviewer's feedback
• All inline review comments with file path, line number, and comment text
• The PR URL and branch name

This gives the runner everything it needs to address the feedback precisely.

PR Review Learning

When a runner processes PR review feedback, each review comment is stored as a knowledge entry with file path, diff context, and reviewer comment. These entries are available organization-wide -- if a reviewer corrects a convention on Project A, agents on Project B benefit next time. Evergreen entries with confidence >= 0.7 are shared automatically across all projects.

Smart Follow-ups

When a follow-up job targets a PR that has already been merged or closed, Spedy detects this automatically. Instead of updating the old branch, the runner creates a fresh branch from main and opens a new PR. Follow-up jobs are grouped under the same root run in the UI.

Managing Runners

In Settings → Runners you have five tabs:

Runners Tab

• See all connected runners with their status (Online / Offline)
• View capabilities and labels for each runner
• See how many jobs each runner is currently handling
• Create and manage runner tokens
• Delete runners you no longer need

Jobs Tab

• Browse all jobs with status filters
• View job details, results, and PR links
• Watch streaming jobs in real time
• Manually create new jobs

Runner Teams Tab

• Create and manage runner teams
• Configure per-team status mappings (working, completion, failure)
• Set @mention handles for board interaction triggers
• Configure pipeline stages for each team
• Choose pipeline presets (Code Runner, Board Agent)

Analytics Tab

• View agent performance metrics: total jobs, success rate, cost, tokens, average duration
• Stage performance breakdown: duration, tokens, and quality gate pass rates per stage
• Model usage analytics: token consumption by model
• Daily trend charts with configurable period (7d / 30d / 90d)

Settings Tab

• Enable or disable auto-create jobs
• Enable or disable runner retrigger on review
• Configure global runner behavior

Secrets Tab

• Manage the Anthropic API key and any custom env vars the runner needs
• See a masked preview + last-rotation timestamp for each secret
• Add, rotate, or delete values — changes propagate to runners within 15 minutes
• Requires the runners:manage-secrets permission (granted to Administrators by default)

Cost Tracking & Budgets

Every runner job tracks costs and token usage in real time, broken down by pipeline stage.

What You See Per Job

• Total cost in USD
• Token consumption split by input tokens, output tokens, and cache tokens
• Cost per pipeline stage (e.g., planner, implementation, review)
• Turns -- the number of interaction rounds the agent needed

In the streaming job view, cost updates appear live as the agent works. The job header shows a cost/limit indicator when a budget is configured.

Team Budgets

Each runner team can have a default budget. Configure it under Settings → Runners → Runner Teams in the team settings:

When a job is created, it inherits the team's budget as its default. Individual jobs can override the team budget.

The job view shows budget status as a progress bar:

• Green -- within budget
• Yellow -- warning threshold reached
• Red -- budget exceeded

Organization Cost Summary

Admins can view an aggregated cost summary across all runner jobs in the organization under Settings → Runners. This helps you understand total spending and decide where model selection or budget adjustments make sense.

Runner Intelligence

The runner includes several built-in mechanisms that improve agent effectiveness without requiring configuration.

Knowledge Pre-Selection

Before an agent starts working on a ticket, the runner automatically fetches relevant knowledge entries from the knowledge base. It uses the ticket context and a keyword search to pre-load entries that the agent would otherwise need to fetch via knowledge_recall tool calls. This reduces wasted turns and gives the agent better starting context.

Diminishing Returns Detection

The runner tracks output token volume per turn. When an agent produces fewer than 500 output tokens for three or more consecutive turns, it flags this as a potential sign that the agent is stuck or making minimal progress. This detection is reported as a progress event and can be used for monitoring agent health.

Progress Summarizer

Every 30 seconds during job execution, the runner generates a human-readable status summary from agent events (tool calls, text output, errors). These summaries appear in the streaming job view alongside raw agent output, making it easier to understand what the agent is currently doing without reading every tool call.

Ticket Context Cache

The runner caches ticket context data for 5 minutes. When multiple pipeline stages request the same ticket information, only the first stage triggers an API call -- subsequent stages reuse the cached response. The cache is invalidated automatically on mutations (e.g., adding a comment or updating the description).

Runner Capabilities and Labels

When a runner registers, it declares what it can do:

• Capabilities: The AI backends it supports (e.g., claude_code). A runner only receives jobs that match its capabilities.
• Labels: Tags like backend, frontend, python, typescript. Jobs can require specific labels, so only matching runners pick them up.

This lets you run specialized runners -- for example, one for backend work and another for frontend work.

What Happens When a Runner Goes Offline?

Spedy monitors runners via heartbeats. If a runner stops sending heartbeats for more than 90 seconds (configurable):

1. The runner is marked as Offline
2. All its active jobs are automatically marked as Failed
3. You see the status change in real time in the UI

When the runner comes back online and sends a heartbeat, it's marked as Online again and can pick up new jobs.

Token Security

• Tokens are hashed before storage -- Spedy never stores the plain value
• Each token has a visible prefix (e.g., rnt_a3f8) so you can identify it
• Tokens can have an expiration date
• Revoked tokens are rejected immediately
• You can scope a token to a specific runner for extra security

Troubleshooting

Docker pull fails on Apple Silicon Macs (ARM64)

If you see an error like:

no matching manifest for linux/arm64/v8 in the manifest list entries

The supervisor image is currently only built for linux/amd64. On Apple Silicon Macs, add the platform field to your docker-compose.yml:

services:
  supervisor:
    platform: linux/amd64
    image: ghcr.io/coding9gmbh/spedy-supervisor:latest
    # ...

Docker Desktop will use Rosetta to emulate the x86 architecture automatically.

Tips

• Start simple: Begin with one runner and the default settings. You can scale later.
• Use labels: If you have multiple projects, use labels to route jobs to the right runner.
• Use Runner Teams: Create separate teams for different workflows (e.g., code changes vs. research tasks).
• Watch the heartbeat: If a runner shows as "Offline", check that it's running and can reach the Spedy API.
• Check the Jobs tab: If jobs stay in "Ready" for a long time, make sure you have a runner online with matching capabilities.
• Pool size: Increase the runner pool size if you want multiple tickets processed in parallel.