Starting Runners

Learn how to start and configure runners for your repositories.

Prerequisites

Before starting a runner, ensure you have:

Starting a Runner

  1. Navigate to Repositories
  2. Click the active repository card to open the runners view
  3. Click Start runner
  4. In the Start runner modal, configure your options
  5. Click Start

Note: On the Repositories page, clicking the repository name opens the repository on your git provider. Click the card to open the runners view in Forkline.

Screenshot of the Start runner modal showing size and model selection options.

Configuration Options

Name

Give your runner a meaningful name:

  • Default: runner-{short-id}
  • Maximum: 30 characters
  • Allowed: Letters, numbers, hyphens, underscores

Size Selection

SizeCPURAMRateWhen to Use
Basic24GB1×Quick edits, documentation
Advanced48GB2×Most development tasks
Pro816GB4×Large codebases, heavy builds

Model Selection

Override the default AI model for this runner:

  1. In the Model dropdown, select a model from your configured providers
  2. Optionally, choose “Inherit from repository defaults” to use the repository’s default model

Branch Selection

Choose which branch to clone:

  • Default: Repository’s default branch
  • Alternative: Any existing branch
  • New branch: Enter a name to create one

Startup Process

When you start a runner, Forkline:

  1. Validates your account
  2. Creates an isolated environment
  3. Clones your repository
  4. Runs setup scripts (if present)
  5. Initializes the AI agent

Info: Startup takes 30-60 seconds.

Customizing the Environment

Setup Scripts

Prepare your runner environment with a setup script that installs mandatory dependencies and adds safeguards for the AI agent:

.forkline/
└── setup.sh    # Bash setup script

The setup script runs after the repository is cloned and before the AI agent initializes. Use it to ensure the runner has all tools and configurations needed to complete tasks effectively.

Example: Installing dependencies

#!/bin/bash
# .forkline/setup.sh

npm install
npm run db:migrate

This ensures the AI agent can run tests, build commands, and other project operations immediately.

Example: Multi-language projects

#!/bin/bash
# Install Node.js dependencies
npm install

# Install Python dependencies
pip install -r requirements.txt

# Setup database
python scripts/setup_db.py

Example: Using secrets

#!/bin/bash
# Secrets are available as environment variables with their original names
npm run migrate --db-url $DATABASE_URL

Repository secrets configured in settings are injected as environment variables with the exact names you defined.

Example: Adding safeguards with pre-commit

#!/bin/bash
# Install pre-commit framework
pip install pre-commit

# Install hooks defined in .pre-commit-config.yaml
pre-commit install

# Install pre-push hooks for additional validation
pre-commit install -t pre-push

This ensures the AI agent follows project conventions and linting rules when making commits.

See Setup Scripts for details.

Repository Secrets

Inject sensitive credentials:

  1. Go to repository settings
  2. Add secrets like DATABASE_URL, API_KEY
  3. Secrets are available in setup scripts

Startup Failures

Insufficient Balance

Error: “You need at least 5 minutes of balance to start a runner”

Solution: Add time to your account

Clone Failed

Error: “Failed to clone repository”

Solution: Verify connector has repository access

Setup Script Issues

If setup scripts fail, check:

  • Script syntax
  • Required dependencies
  • Environment variables

Note: Setup script failures are logged but don’t prevent the runner from starting.

Next Steps