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 create a runner token in Spedy (Settings → Runners)
2. You download and set up the Spedy Supervisor on your machine or server
3. The supervisor connects, polls for work, and executes jobs
4. You see progress and results directly in Spedy

Step 1: Create a Runner Token

1. Open Settings → Runners
2. Switch to the Tokens tab
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).

Step 2: 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
• An Anthropic API key (sk-ant-...)
• A GitHub personal access token (github_pat_...) with the required permissions (see below)

GitHub Token Permissions

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

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

To create one: GitHub → Settings → Developer settings → Personal access tokens → Fine-grained tokens → Generate new token.

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:

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.

Step 3: Configure Automatic Job Creation

By default, Spedy can automatically create jobs when a ticket moves to a specific status.

1. Open Settings → Runners
2. Set the trigger status (e.g., "AI Processing")
3. Enable Auto-create jobs

Now when you drag a ticket into the "AI Processing" column, Spedy creates a job that your runner picks up.

You can also create jobs manually from the Jobs tab by clicking Create Job.

Watching Jobs Run

Batch Jobs

Batch jobs run in the background. You can see their progress in the Jobs tab:

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.

What Happens When a Job Fails?

When a runner job fails, the ticket is automatically moved back to the Todo column with an AI Failed badge. This makes it easy to spot tickets that need attention. When you drag the ticket back into "AI Processing", the badge is cleared and a new job is created automatically.

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.

Managing Runners

In Settings → Runners you have four tabs:

Tokens Tab

• Create new runner tokens
• See which tokens are active and when they were last used
• Revoke tokens that are no longer needed

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
• 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

Settings Tab

• Configure the trigger status for automatic job creation
• Set the completion status (where tickets move after a successful job)
• Enable or disable auto-create jobs

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.
• 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.