# Runners

Runners are the machines that execute TestVibe work in GitHub Actions. When TestVibe generates Playwright code or runs tests, GitHub selects a runner, prepares the environment, and executes the workflow.

For many teams, the default GitHub-hosted runner is enough. If your application is private, behind a VPN, or needs a controlled network, you may need a self-hosted runner that can reach your app.

## What You Can Do

<table data-view="cards"><thead><tr><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><strong>Understand runners</strong></td><td>Learn what a runner is and why it matters for generation and test runs.</td><td><a href="/pages/MFN5uxc0naidpR0m7lOv">/pages/MFN5uxc0naidpR0m7lOv</a></td></tr><tr><td><strong>Pick the right runner</strong></td><td>Choose between hosted runners, self-hosted runners, and custom labels.</td><td><a href="/pages/nsuldvgQk3I0DUNc9MNw">/pages/nsuldvgQk3I0DUNc9MNw</a></td></tr><tr><td><strong>Set a default</strong></td><td>Use the Runners settings page to choose the default runner for a repository.</td><td><a href="/pages/njhHuzrg7J1AK5HMXUOY">/pages/njhHuzrg7J1AK5HMXUOY</a></td></tr><tr><td><strong>Fix runner issues</strong></td><td>Resolve queued workflows, offline runners, missing labels, and unreachable sites.</td><td><a href="/pages/U3R2iXfZUFCAHpMySmxw">/pages/U3R2iXfZUFCAHpMySmxw</a></td></tr></tbody></table>

## When Runners Matter

Runner choice affects:

| Area             | Why it matters                                                             |
| ---------------- | -------------------------------------------------------------------------- |
| Site access      | The runner must be able to open the target site URL.                       |
| Operating system | Some apps or test dependencies work best on Linux, Windows, or macOS.      |
| Browser support  | Playwright needs browsers and system dependencies available on the runner. |
| Queue time       | Busy or unavailable runners can delay generation and test runs.            |
| Security         | Private applications may require a runner inside your network.             |

## Recommended Starting Point

Start with a GitHub-hosted Linux runner such as `ubuntu-latest` unless your team has a reason to use a different environment. Move to a self-hosted runner when your target site or dependencies are not reachable from GitHub-hosted infrastructure.

## Official GitHub Docs

Use GitHub's own runner documentation when you need GitHub-specific setup, limits, labels, or admin instructions:

| GitHub doc                                                                                                                                         | Use it for                                                      |
| -------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------- |
| [GitHub-hosted runners](https://docs.github.com/en/actions/concepts/runners/github-hosted-runners)                                                 | Confirm hosted runner behavior, images, and platform options.   |
| [Self-hosted runners](https://docs.github.com/en/actions/concepts/runners/self-hosted-runners)                                                     | Understand what your team manages when hosting its own runners. |
| [Choosing the runner for a job](https://docs.github.com/en/actions/how-tos/write-workflows/choose-where-workflows-run/choose-the-runner-for-a-job) | Learn how GitHub matches `runs-on` labels and runner groups.    |

## Related Pages

<table data-view="cards"><thead><tr><th></th><th></th></tr></thead><tbody><tr><td><strong>Run tests</strong></td><td><a href="/pages/jRDweXS74GF5RysL7hCO">Learn how to start and monitor test runs.</a></td></tr><tr><td><strong>Configure your workspace</strong></td><td><a href="/pages/OmsBY1OXulgZoZnkBH4o">Review repository and target site settings.</a></td></tr><tr><td><strong>Troubleshooting</strong></td><td><a href="/pages/3gs6UgqcBcbXFexQsKTo">Understand workflows that stay queued or stuck.</a></td></tr></tbody></table>


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.testvibe.com/runners.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.