---
title: "Starting Runners"
description: "Learn how to start and configure runners for your repositories."
section: "runners"
url: "https://forkline.dev/docs/runners/starting"
markdown: "https://forkline.dev/docs/runners/starting.md"
source: "src/content/docs/runners/starting.md"
---

# Starting Runners

Learn how to start and configure runners for your repositories.

## Prerequisites

Before starting a runner, ensure you have:

- A configured [git connector](https://forkline.dev/docs/getting-started/connectors)
- An activated repository

## 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.](https://forkline.dev/docs/screenshots/settings/start-runner-modal.webp)

## Configuration Options

### Name

Give your runner a meaningful name:

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

### Size Selection

| Size | CPU | RAM | Rate | When to Use |
|------|-----|-----|------|-------------|
| Basic | 2 | 4GB | 1× | Quick edits, documentation |
| Advanced | 4 | 8GB | 2× | Most development tasks |
| Pro | 8 | 16GB | 4× | 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**

```bash
#!/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**

```bash
#!/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**

```bash
#!/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**

```bash
#!/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](https://forkline.dev/docs/repositories/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.

## API Access

Runners can be started, monitored, and stopped via the [public API](https://forkline.dev/docs/reference/endpoints#runners). See the [Integration Quickstart](https://forkline.dev/docs/reference/api-quickstart) for a full walkthrough.

## Next Steps

- [Connect to your runner](https://forkline.dev/docs/runners/connecting)
- [Understand runner sizes](https://forkline.dev/docs/runners/sizes)
- [Configure setup scripts](https://forkline.dev/docs/repositories/setup-scripts)