---
title: "Runners Overview"
description: "Understand what runners are and how they execute AI-powered tasks."
section: "runners"
url: "https://forkline.dev/docs/runners"
markdown: "https://forkline.dev/docs/runners.md"
source: "src/content/docs/runners.mdx"
---

# Runners

Runners are isolated cloud environments where AI agents work on your code.

_Interactive figure (RunnerLifecycleDiagram) — see the HTML version of this page._

## What a Runner Does

A runner gives Forkline a short-lived workspace where it can:

- Clone your repository
- Understand your project structure and configuration
- Execute the task you requested
- Run tests, linters, builds, and scripts
- Push commits or open pull requests when the job is done

> **Info**: Runners are ephemeral. They are created when you start one and destroyed when you stop it. Persistent state lives in your repository, not inside the runner.

![Runners list page](https://forkline.dev/docs/screenshots/runners/runners-list-page.webp)

## Understanding Runner States

The most important transition is from **Starting** to **Running**. While a runner is starting, Forkline is preparing the repository, applying setup logic, and making the environment ready to connect. Once it is running, you can open it in the browser, desktop app, or terminal.

If a runner stops unexpectedly, check whether it ended in **Stopped** because you or a policy ended it, or **Failed** because startup or execution hit an error.

## Size at a Glance

_Interactive figure (RunnerSizesBoard) — see the HTML version of this page._

For most repositories, **Advanced** is the best default. Move down to **Basic** for documentation or quick edits. Move up to **Pro** when a larger codebase, build pipeline, or memory-heavy tooling would slow smaller runners down.

See [Runner Sizes](https://forkline.dev/docs/runners/sizes) for detailed guidance.

## What Runners Can Do

Runners can handle the full engineering loop: understand the codebase, plan the work, make changes, interact with your git provider, and run the commands needed to verify results.

### Analysis and Planning

- Explore and understand your codebase
- Analyze issues, pull requests, and existing changes
- Break work into steps and plan implementation
- Investigate failures and propose fixes

### Code Changes

- Edit existing code or add new files
- Implement features, fix bugs, and refactor safely
- Follow your project's structure, conventions, and tooling
- Update tests and documentation when needed

### Repository Workflows

- Create branches, commits, and pull requests
- Comment on issues and pull requests
- Label issues, triage work, and assign tasks to Forkline
- Open, close, reopen, review, and merge pull requests
- Check CI status, inspect logs, and analyze failures
- Trigger workflows and coordinate work across GitHub, GitLab, and Forgejo

### Running Commands

- Execute tests, linters, formatters, and builds
- Run project-specific scripts and CLI tools
- Debug issues from logs, traces, and command output
- Perform infrastructure, automation, and browser-based workflows when needed

## Security

Runners are isolated for security:

- **Per-user isolation**: Your runners only access your repositories
- **Secure credentials**: Secrets are injected via environment variables
- **Ephemeral storage**: No data persists after the runner stops

## Resource Limits

Control how many runners can run simultaneously:

1. Go to **Settings** -> **General**
2. Set **Maximum active runners**

## Next Steps

- [Start a runner](https://forkline.dev/docs/runners/starting)
- [Connect to your runner](https://forkline.dev/docs/runners/connecting)
- [Configure OpenCode](https://forkline.dev/docs/opencode/rules)