opschain admin runner-group set

Included from Basic tier

opschain admin runner-group set <name> [--description <text>] [--exclusive]
                                [--attribute k=v]... [--binding <path>]...

Creates or updates a runner group (the v2 RunnerService.UpsertRunnerGroup RPC) — the durable row registration tokens reference and enrolment inherits, carrying the group's placement contract: its key=value attributes, its node-path bindings and the exclusive flag.

Set replaces the whole definition, it does not merge. The request always carries all four fields, so an update that omits --attribute clears the group's attributes, omitting --binding clears its bindings, and omitting --exclusive resets it to false. Re-state everything the group should keep on every call.

What the contract means for dispatch (opschain docs fleet-queue has the full ladder):

• Attributes are what a run's placement selectors match against. Keys must be registered first (opschain admin runner-attributes set), and a key with enumerated allowed values only accepts one of them — validation happens here, at write time.
• Bindings are absolute node paths: work targeting a bound subtree is offered only to bound groups' runners, so bound work stays in its zone.
• Exclusive means the group's runners take only work targeted at the group — by name, by binding or by matching selectors — never unconstrained overflow.

Creating a new group name may be refused by the licence's runner-group entitlement; updating an existing group is always within entitlement.

Flags

Flag	Meaning
--description <text>	Group description (shown in the machine listing).
--exclusive	Group runners take only work targeted at the group.
--attribute k=v	Placement attribute (repeatable). Keys must be registered attribute keys.
--binding <path>	Node-path binding the group serves (repeatable; absolute paths starting /).
--server <url>	Server base URL. Default: the active context / OPSCHAIN_SERVER.
--auth-token <token>	Admin bearer token override. Default: your opschain login session, then $OPSCHAIN_ADMIN_TOKEN, then the token stored by opschain admin login.

Output

The stored group, as JSON (-o yaml for YAML) — the authoritative post-write state, including created_at/updated_at.

Examples

opschain admin runner-attributes set location
opschain admin runner-group set secure --exclusive \
  --attribute location=dc1 --binding /prod

Exit codes

0 stored; 1 the request failed or the server refused the definition; 2 usage.

Named errors

• --attribute takes key=value, got "<pair>" (exit 2)
• a server is required — pass --server <url>, set OPSCHAIN_SERVER, or 'opschain context use <name>' (exit 2)
• this command needs a login or an admin token — run 'opschain login', pass --auth-token, set OPSCHAIN_ADMIN_TOKEN, or store one with 'opschain admin login' (exit 2)
• the server rejected the credential — run 'opschain login' again, or check the admin token (exit 1)
• Server refusals pass through with the HTTP status (exit 1):
  • invalid runner group name "<name>": use letters, digits, '.', '_' or '-'
  • binding "<path>" must be an absolute node path
  • attribute key "<key>" is not registered: register it first (admin runner-attributes)
  • attribute "<key>" value "<value>" is not registered: allowed values are <values>

See also

• opschain docs cli/admin-runner-attributes-set — register the keys the attributes use.
• opschain docs cli/admin-runner-group-list — the contracts in force.
• opschain docs cli/admin-runner-group-delete — remove a group nothing references.
• opschain docs fleet-queue — how the contract shapes the placement verdicts.