Agent runner groups
Every agent session is a process in your cloud. Staff does not run the LLM loop on Orkestia's CPU. The pool that hosts that process is a runner group whose purpose is agent.
This is a different object from GitHub Actions / generic CI groups used by Runners. Pointing an agent config at a CI pool used to queue a task, exit cleanly, and hang until heartbeat timeout. The platform now fails fast.
The gate
On config create/update, org-default upsert, and session-launch:
resolve runner_group_uuid
→ group exists and is in this org?
→ purpose == agent? ← the only eligibility signal
→ otherwise ValueError (session-launch → FAILED)
config.supports_agents / "enable for agents" is enablement (this group is allowed to be selected). It does not convert a generic group into an agent group. Create the group as an agent pool from the start.
What to create
In Staff: Admin → Runner groups. In the main app, the same groups appear under Runners.
Production-shaped backends for agent pools today: fargate, azure_container_apps_job, kubernetes. GCP cloud_run, DigitalOcean, and Magalu exist in provider libraries with partial coverage — treat those as beta and confirm in reference.orkestia.dev. The full kind catalog is Runner groups; purpose/integration pairings are Purposes.
The group must reach active before session-launch. Then select it on the actor's config (hire wizard or Configs).
Cloudless / laptop coding
Coding assignments on a developer machine use a cloudless devkit runner group plus ltinteg-devkit runner serve. That path is Coding agents — still purpose=agent, but the broker is local. Do not mix it up with Fargate CI groups.
If sessions stall
| Symptom | Likely cause |
|---|---|
| Launch FAILED mentioning not agent-eligible | Group purpose is not agent |
| Launch queued, never heartbeats | Image/runtime is a CI runner, not the agent runtime; or group not active |
| "No runner group" on hire | Create one first; refresh the hire form |
| Works in one unit, not another | Config points at a different group; check the actor's config |
Full CI runner lifecycle (provision, warm pools, drift): Runner management. This page is only the agent eligibility rule customers hit when running Staff.