# What are runners?

A runner is the machine that does the work when TestVibe starts a GitHub Actions workflow. TestVibe sends the request, GitHub picks a matching runner, and the runner executes the generation or test run.

You can think of a runner as the execution computer for TestVibe.

## What Runners Do

During a TestVibe workflow, a runner may:

| Step                      | What happens                                                                         |
| ------------------------- | ------------------------------------------------------------------------------------ |
| Check out your repository | The runner downloads the repository files needed for the workflow.                   |
| Prepare dependencies      | The runner installs or restores packages, Playwright browsers, and other tools.      |
| Generate output           | AI generation workflows can create or update feature files and Playwright test code. |
| Run browser tests         | Playwright opens your target site and follows the generated test steps.              |
| Upload evidence           | Screenshots, videos, traces, logs, and status updates are returned for review.       |

## Hosted And Self-Hosted Runners

TestVibe can use two broad runner types:

| Runner type          | Best for                                                                                      |
| -------------------- | --------------------------------------------------------------------------------------------- |
| GitHub-hosted runner | Standard web apps, public or staging URLs, and teams that want the simplest setup.            |
| Self-hosted runner   | Private apps, internal networks, VPN-only environments, custom tools, or controlled machines. |

Some organizations also provide organization-level hosted runners with custom labels. If those runners are available to your repository, TestVibe can show them in the Runners settings page.

For GitHub's definitions, see [GitHub-hosted runners](https://docs.github.com/en/actions/concepts/runners/github-hosted-runners) and [Self-hosted runners](https://docs.github.com/en/actions/concepts/runners/self-hosted-runners) in GitHub Docs.

## Runner Labels

GitHub chooses a runner by matching labels. A label can describe the operating system, environment, or custom runner pool.

Common examples include:

| Label            | Typical meaning                                                        |
| ---------------- | ---------------------------------------------------------------------- |
| `ubuntu-latest`  | Use GitHub's default Ubuntu runner.                                    |
| `windows-latest` | Use GitHub's default Windows runner.                                   |
| `macos-latest`   | Use GitHub's default macOS runner.                                     |
| `self-hosted`    | Use a self-hosted runner registered to the repository or organization. |

For self-hosted runners, exact labels are controlled in GitHub. A runner only receives work when the workflow labels match the runner labels.

GitHub explains label and group matching in [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).

## Where Runners Fit In TestVibe

Runners are used after you start generation or a run:

1. You choose a repository and test action in TestVibe.
2. TestVibe starts a GitHub Actions workflow.
3. GitHub finds a runner that matches the configured labels.
4. The runner performs the generation or Playwright execution.
5. TestVibe shows progress, status, and evidence as the workflow reports back.

## Next Step

To decide which runner your project should use, see [Choose a runner](/runners/choose-a-runner.md).


---

# 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/what-are-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.