# Choose a runner

The best runner is the one that can reliably reach your application, run Playwright, and match your team's operating system or security needs.

Most teams should start with `ubuntu-latest`. Change runners when the default environment cannot reach your site or does not match your project requirements.

## Quick Decision Guide

| Situation                                                      | Recommended runner                                                   |
| -------------------------------------------------------------- | -------------------------------------------------------------------- |
| Your target site is public or a normal staging URL             | GitHub-hosted Linux runner, usually `ubuntu-latest`.                 |
| Your target site is behind a VPN, firewall, or private network | Self-hosted runner with access to that network.                      |
| Your tests require Windows-specific behavior                   | GitHub-hosted or self-hosted Windows runner.                         |
| Your tests require macOS-specific behavior                     | GitHub-hosted or self-hosted macOS runner.                           |
| Your organization already has approved runner pools            | The organization runner label your team uses for browser automation. |
| Workflows stay queued because no runner matches                | Choose labels that match an online runner.                           |

## What To Check Before Choosing

Before changing runner settings, confirm:

| Check                                      | Why it matters                                                  |
| ------------------------------------------ | --------------------------------------------------------------- |
| Can the runner reach the site URL?         | Playwright must open the application from the runner machine.   |
| Is the runner online?                      | Offline self-hosted runners cannot pick up work.                |
| Do the labels match?                       | GitHub only sends work to runners with matching labels.         |
| Does the runner have enough capacity?      | Busy runner pools can keep workflows queued.                    |
| Does the runner support your dependencies? | Custom tools, browsers, fonts, and certificates may need setup. |

## Hosted Runner Or Self-Hosted Runner?

Use a GitHub-hosted runner when:

| Good fit                                 | Details                                                              |
| ---------------------------------------- | -------------------------------------------------------------------- |
| You want simple setup                    | GitHub provides and maintains the machine.                           |
| Your site is reachable from the internet | The runner can access the target URL without special network access. |
| Standard browsers are enough             | Playwright dependencies are straightforward to install.              |

Use a self-hosted runner when:

| Good fit                                  | Details                                                                        |
| ----------------------------------------- | ------------------------------------------------------------------------------ |
| Your site is private                      | The runner can sit inside the same network as the app.                         |
| You need custom setup                     | Your team controls installed tools, certificates, browsers, and network rules. |
| You need predictable environment behavior | The same machine or pool can be used for repeated runs.                        |

For more detail from GitHub, compare [GitHub-hosted runners](https://docs.github.com/en/actions/concepts/runners/github-hosted-runners) with [Self-hosted runners](https://docs.github.com/en/actions/concepts/runners/self-hosted-runners).

## Practical Recommendation

Start simple:

1. Use `ubuntu-latest`.
2. Run one small test against your target site.
3. If the runner cannot reach the site or needs custom setup, switch to a self-hosted runner.
4. If the issue is operating-system-specific, choose a Windows or macOS runner.

## Next Step

After choosing the runner you want, see [Set the default runner](/runners/set-default-runner.md).

If you are also editing workflow files directly, GitHub's [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) page explains the `runs-on` values that TestVibe runner labels ultimately map to.


---

# 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/choose-a-runner.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.