Self-Hosted Runners

Use the runs-on frontmatter field to target a self-hosted runner instead of the default ubuntu-latest.

For these reasons, a non-sudo mode is not supported, including ARC configurations with allowPrivilegeEscalation: false.

runs-on formats

String — single runner label:

---
on: issues
runs-on: self-hosted
---

Array — runner must have all listed labels (logical AND):

---
on: issues
runs-on: [self-hosted, linux, x64]
---

Object — named runner group, optionally filtered by labels:

---
on: issues
runs-on:
  group: my-runner-group
  labels: [linux, x64]
---

runs-on must be set in each workflow — it is not merged from imports. Other settings like network and tools can be shared:

---
network:
  allowed:
    - defaults
    - private-registry.example.com
tools:
  bash: {}
---

---
on: issues
imports:
  - shared/runner-config.md
runs-on: [self-hosted, linux, x64]
---

Triage this issue.

Configuring the detection job runner

When threat detection is enabled, the detection job runs on the agent job’s runner by default. Override it with safe-outputs.threat-detection.runs-on:

---
on: issues
runs-on: [self-hosted, linux, x64]
safe-outputs:
  create-issue: {}
  threat-detection:
    runs-on: ubuntu-latest
---

This is useful when your self-hosted runner lacks outbound internet access for AI detection, or when you want to run the detection job on a cheaper runner.

Configuring the framework job runner

Framework jobs — activation, pre-activation, safe-outputs, unlock, APM, update_cache_memory, and push_repo_memory — default to ubuntu-slim. Use runs-on-slim: to override all of them at once:

---
on: issues
runs-on: [self-hosted, linux, x64]
runs-on-slim: self-hosted
safe-outputs:
  create-issue: {}
---

Configuring the maintenance workflow runner

The generated agentics-maintenance.yml workflow defaults to ubuntu-slim for all its jobs. To use a self-hosted runner for maintenance jobs, set runs_on in .github/workflows/aw.json:

Single label:

{
  "maintenance": {
    "runs_on": "self-hosted"
  }
}

Multiple labels (runner must match all):

{
  "maintenance": {
    "runs_on": ["self-hosted", "linux", "x64"]
  }
}

This setting applies to every job in agentics-maintenance.yml (close-expired-entities, cleanup-cache-memory, run_operation, apply_safe_outputs, create_labels, validate_workflows, and activity_report). Re-run gh aw compile after changing aw.json to regenerate the workflow.

Frontmatter — runs-on and runs-on-slim syntax reference
Imports — importable fields and merge semantics
Threat Detection — detection job configuration
Network Access — configuring outbound network permissions
Sandbox — container and Docker requirements
Ephemerals — full aw.json maintenance configuration reference