Runner groups

Groups organize self-hosted runners and define which part of the organization may use them. Workloads target a group by name (for example Default) plus optional labels.

Open Administration → Runners at /admin/runners, select the Setup tab, then Step 1 — Create a runner group. Step 2 registers agents into the selected group. Think of a group like a GitHub Actions runner group: runners join the group; stacks and workflows target the group and labels.

i

Legacy routes such as /administration/execution/runner-registration redirect to /admin/runners. Provider-hosted fleet groups are managed separately on the Hosted fleet tab (platform provider orgs).

Default group

Every organization gets a system Default group automatically the first time groups are listed (GET /organizations/:orgId/runner-groups).

i
  • It cannot be deleted.
  • You cannot create another group named Default (case-insensitive).
  • If you delete a custom group, its runners, registration tokens, and pools are moved to Default.
  • The default group is marked with a default chip in the table and shown as (default) in the Step 2 picker.

Permissions

Action Permission
Open Runners admin (nav) runner:manage, runner:customer:manage, or runner:customer:register
List / view groups runner:read (or broader runner permissions via the UI)
Create, edit, delete groups (API) runner:manage
Register runners (Step 2) runner:customer:register, runner:customer:manage, or runner:manage

The Setup UI shows create/edit/delete controls when the user has runner:manage or runner:customer:manage, but group mutations on the API require runner:manage. Read-only users see the group table without action buttons.

Scope

When you create or edit a group, choose a scope:

UI scope Who can use runners in this group
Organization Entire organization
Project One selected project
Workspace One workspace within a project (project must already have workspaces)
Environment One environment within a workspace (project → workspace → environment)

Workspace scope is stored as scopeType: PROJECT plus a system tag axio:workspace:<workspaceId>. Environment scope uses scopeType: ENVIRONMENT with both projectId and environmentId. Registration in Step 2 must match the group scope; mismatches are rejected.

✓

Narrower scopes keep a GPU or production fleet from being used by every stack in the org.

Group table

The Step 1 table includes search (case-insensitive name filter) and these columns:

Column Meaning
Name Group name; default group shows a default chip
Scope Organization, Project, Workspace, or Environment
Status Enabled or Disabled
Runners Count of registered runners in the group
Actions Edit (pencil) and delete (non-default groups only)

Fields

Field Notes
Name Required. Default is reserved. Names must be unique within the organization.
Description Optional
Scope Organization / project / workspace / environment, with cascading project → workspace → environment pickers
Enabled Shown in the table. Disabled groups cannot receive new registrations (Step 2 blocks token generation). Only enabled groups appear in stack/workflow runner-group pickers. Toggle via API (enabled on create/update); not exposed in the Setup group form today.
Max runners (API) Returned on group objects (maxRunners, default 50) for capacity alignment with internal pools. Not editable in the Setup UI. Org-wide registration still respects plan limits such as maxCustomerRunners and maxGroups.
i

The control plane creates an internal default pool per group for isolation and fleet settings. You do not name or manage that pool in the Setup UI. Additional internal pools may be created automatically when you register runners with a specific isolation mode (see below).

Create

  1. Open Runners → Setup (/admin/runners?tab=setup).
  2. In Step 1, click Create group.
  3. Set name, optional description, and scope (plus project / workspace / environment when required).
  4. Save. The new group appears in the table and becomes selectable in Step 2.
i

Requires runner:manage on the API (POST /organizations/:orgId/runner-groups). Subject to organization group quota (maxGroups) when configured.

Edit

Use the pencil icon on a group row. In the Setup UI you can change the name (except creating a second Default), description, and scope. Saving calls PATCH /organizations/:orgId/runner-groups/:groupId.

Changing scope may trigger the control plane to ensure the group’s internal default pool matches the new scope.

Delete

  1. Open delete on a non-default group.
  2. Type DELETE or the exact group name to confirm.
!
Rules:
  • The default group cannot be deleted.
  • Registered runners in the deleted group are moved to Default along with their pools and tokens.
  • Empty groups have their internal pools removed; the group record is then deleted.

Using a group

  • Registration (Step 2): Select a runner group before generating an install command. The registration token is bound to that group, its scope, and the chosen platform/isolation. Disabled groups cannot be used.
  • Workloads: Stacks and axio.yaml can set runner.strategy: runner-group and runner.runnerGroup: <name> (match the group name, not the internal id). Combine with runnerLabels to narrow to labeled runners within the group.
  • Inventory: The Overview tab shows the group name on each runner row.
  • Reassign runners: Use runner edit actions or API assign/remove endpoints to move runners between groups (scope must remain compatible).

Isolation and internal pools

Isolation (process / container / Kubernetes pod) is chosen in Step 2 when you register a runner (platform-dependent — for example Linux/Windows support process or container; Docker requires container; Kubernetes requires pod isolation).

The control plane selects or creates an internal pool for that isolation mode on the group. Pool isolation cannot be changed after creation; register against a different isolation choice (which may create another internal pool) if you need a separate execution mode.

See repository docs docs/RUNNER.md and docs/RUNNER_FLEET.md for fleet and execution details.