How to Run on a Self-Hosted Runner in CircleCI

A self-hosted runner registers under a namespace resource class that your jobs then target directly.

Install the runner agent against a resource class, then point a job at that class. Jobs route to any runner registered under it.

Target a runner resource class

Set the job resource_class to your namespace/class so it runs on your registered runner.

version: 2.1
jobs:
  build:
    machine: true
    resource_class: my-org/linux-runner
    steps:
      - checkout
      - run: ./build.sh
workflows:
  main:
    jobs:
      - build

Notes

• The resource class name is namespace/class and must match how you registered the agent.
• Self-hosted runners use the machine executor, not the docker executor.
• If you adopt self-hosted runners mainly to control hardware, GitHub Actions plus managed runners on Latchkey gives the same control without operating the agents yourself.

Related guides