Runners

A runner is whatever executes a job. neosource models three scopes — hosted, self-hosted, and local — but only hosted runners are available to use today. This page is explicit about which is which, because the gap matters.

Hosted runners

Hosted runners are neosource’s own pool, and they are what runs your jobs. You do not configure or provision anything: push a workflow and jobs are scheduled onto the pool.

Every job runs in the same canonical environment, with tools added by packages:. See The job environment — that page is the one that determines what your job can actually do.

What runs-on selects

This is the most common misunderstanding coming from GitHub Actions.

runs-on is a scheduling label. It does not choose an environment. There is no runs-on value that gives your job a different base image or a different operating system.

jobs:
  a:
    runs-on: ubuntu-latest # a label
    packages: [nodejs_20] # this is what determines the environment

  b:
    runs-on: nix # requests the strict Nix form
    packages: [nodejs_20] # same tools either way

runs-on: nix is the one value with extra meaning at parse time: it requires exactly one of flake: or packages:, and it is the hermetic form. Any other label is scheduling metadata.

A job that declares no packages: and no flake: runs in the canonical container image. A job that declares either runs under Nix. That decision comes entirely from the job’s own keys, never from its runs-on label.

Not yet available

The following are modelled in the platform and partly built, but you cannot use them today. They are listed so you can plan, not so you can rely on them.

Self-hosted runners

The runner API exists — registration, job claim by long-poll, lease heartbeat, and completion are all live endpoints. What is missing is the agent you would run on your own hardware: ns-runner is not distributed. There is no released binary, install script, or package, so there is no supported way to attach your own machine to the pool.

Local-first CI

The design goal is to run your own push’s CI on your own machine while the server still records the run — real run records, real logs, visible in the UI, just executed locally. The implementation exists and has been reviewed, but it is not deployed, and it would depend on the neo CLI, which is also not distributed.

When both ship, this will be documented here properly. Until then, treat it as not available rather than as a feature to design your workflows around.

Seeing what ran

Runs, jobs, and logs are all readable through the API and the Actions view in the web UI. The endpoint list is in How CI works here.