Skip to content

Glossary

What is a self-hosted runner?

A self-hosted runner is a machine you provide that runs your CI jobs, in place of the machines your CI service hosts for you.

Updated · Facts checked · By Runtime Cloud

3 min read

Read as Markdown

In GitHub Actions, the runner is a small program that connects to GitHub, takes a queued job, and runs its steps. GitHub hosts runners for you, chosen with runs-on: ubuntu-latest. A self-hosted runner is the same program on a machine you choose: a server in your office, a cloud VM, or a machine a runner service starts for each job. GitLab, Buildkite and other CI services have the same idea under their own names.

On Runtime (withruntime.com), each GitHub Actions job gets a fresh Linux microVM as its runner, which runs that one job and is then deleted. You change runs-on and keep the workflow. There is no runner to install or update, and nothing is left on the machine for the next job to find.

Why teams use them

  • A different machine. More vCPUs or memory than the hosted sizes, a GPU, another architecture, or a machine inside a private network that can reach a database or an internal registry.
  • Speed. A machine that already holds the toolchain and warm caches starts the first step sooner than a cold hosted runner.
  • Cost. You pay for the machine rather than the hosted runner's minutes, including the hours it waits for work. Read your CI service's pricing for what it charges for a job on a runner you provide.

What you take on

GitHub's documentation is direct about the trade: you are responsible for updating the machine's operating system and all of its software. The larger cost is security:

  • A runner that is reused keeps what the last job left. A job can write files, leave a process running or change a tool on the path, and the next job on that machine runs with it. GitHub notes that there is no way to guarantee a persistent self-hosted runner runs only one job.
  • Public repositories are the riskiest case. Anyone can open a pull request on a public repository, and a workflow that runs on that pull request runs their code on your machine. GitHub's advice is that self-hosted runners should almost never be used for public repositories.
  • The machine's network is the job's network. A runner inside your network gives every job the same reach.

Ephemeral and just-in-time runners

An ephemeral runner takes one job and then leaves, so no job sees another's leftovers. GitHub's just-in-time (JIT) configuration makes one: a call to POST /repos/{owner}/{repo}/actions/runners/generate-jitconfig returns an encoded_jit_config, the runner starts with it, performs at most one job, and is removed from the repository. One job per runner is only clean if the machine under it is new too. A JIT runner on a reused VM still shares that VM's disk with the jobs before it.

A self-hosted runner on Runtime

Connect your GitHub account through Runtime's GitHub App, then set runs-on to a Runtime size (CI/CD):

YAMLjobs:  test:    runs-on: runtime # was: ubuntu-latest    steps:      - uses: actions/checkout@v4      - run: npm ci && npm test

Each queued job gets a machine of its own, made for it and deleted when the job completes, and jobs run only for private repositories. To start the runner yourself, create a CI machine whose run is runtime-runner, with the JIT configuration from GitHub in RUNNER_JITCONFIG:

Terminaljit=$(curl -s -X POST -H "authorization: Bearer $GITHUB_TOKEN" \  "https://api.github.com/repos/acme/shop/actions/runners/generate-jitconfig" \  -d '{"name":"runtime-1","runner_group_id":1,"labels":["self-hosted","linux","x64"]}' |  jq -r .encoded_jit_config)curl -s -X POST https://api.withruntime.com/v2/ci \  -H "authorization: Bearer $RUNTIME_API_KEY" -H "content-type: application/json" \  -d "{\"run\":{\"cmd\":\"runtime-runner\",\"env\":{\"RUNNER_JITCONFIG\":\"$jit\"}}}"

The machine runs that one job, then stops. It is billed by the second at $0.001 a vCPU-minute while it runs. Through the GitHub App, a machine exists only while its job does, so no runner waits idle between jobs.

Sources

Facts on this page were checked on 17 November 2026.

Cut your cloud billby 66%.

7 days of Pro for $0, and no card to sign up. Billed by the second after.

Start your free trial