Runner types

Relay supports managed cloud runners and self-hosted agents. Pick a target with runs-on in relay.yaml.

Cloud runners

Managed runners require no setup. Relay provisions ephemeral VMs for each job.

jobs:
  test:
    runs-on: relay-linux-medium
    steps:
      - run: npm test

jobs:
  ios-build:
    runs-on: relay-macos-medium
    steps:
      - run: xcodebuild -scheme App test

jobs:
  windows-test:
    runs-on: relay-windows-medium
    steps:
      - run: dotnet test

jobs:
  arm-build:
    runs-on: relay-linux-arm64-medium
    steps:
      - run: cargo build --release

Self-hosted runners

Register agents in your network, VPC, or on bare metal for compliance or specialized hardware.

curl -fsSL https://get.relay.dev/agent | bash
relay-agent register --org northline --labels gpu,docker

jobs:
  integration:
    runs-on: [self-hosted, linux, docker]
    steps:
      - run: docker compose up -d
      - run: npm run test:integration

Runner configuration

OIDC and secrets on runners

Self-hosted and cloud runners receive short-lived OIDC tokens for cloud deploys. Mount organization secrets without exposing them in logs:

jobs:
  deploy:
    runs-on: self-hosted-linux
    permissions:
      id-token: write
    steps:
      - uses: relay/aws-oidc@v1
        with:
          role-to-assume: arn:aws:iam::123456789012:role/RelayDeploy
      - run: ./scripts/deploy.sh
        env:
          API_KEY: ${{ secrets.STAGING_API_KEY }}

Best Practices

Important: Pin self-hosted agents to a version channel and rotate registration tokens regularly.

• Use cloud runners for bursty PR builds; reserve self-hosted for GPU or air-gapped workloads
• Apply labels for OS, architecture, and capability (e.g. docker, k8s)
• Set timeout on long-running integration jobs
• Scale self-hosted pools with auto-scaling groups or Relay's agent orchestration