Groups¶

A group is a bag of agents you target with a rollout. Groups come in two flavours; this page covers static groups. For label-selector groups see Dynamic groups.

The single-group invariant¶

Every agent belongs to exactly one group at a time. This is a hard invariant in the schema, not just a UI convention. The reasoning:

• Auto-apply must be unambiguous — there is exactly one configuration the agent should be running. Multiple groups → multiple candidate configs → ambiguity.
• "Move" replaces "remove from A, add to B" with one atomic operation, audited as a single event.
• It removes a class of bugs around overlapping group memberships.

If you need an agent in "two cohorts", model the cohorts as labels and use a dynamic group instead.

Creating a static group¶

Groups → New group:

• Name — unique per tenant.
• Description — free text.
• Mode — Static.
• Default configuration (optional) — agents joining the group are auto-assigned this config (subject to policy).

Save. The group is empty until you add members.

Adding members¶

• Group detail → Members → Add: pick agents from the agent picker.
• Bulk from the Fleet page: multi-select, then Bulk → Move to group.
• From an Agent detail page: Move action.

Adding an agent to a group removes it from its previous group.

Default configuration and auto-apply¶

If the group has a default configuration:

• Agents joining the group are queued for an auto-apply of that config.
• Auto-apply respects the same policies and capability gating as a manual rollout.
• A separate audit event is emitted (Group.AutoApplied) so you can distinguish auto-apply from explicit rollouts.

Soft delete¶

Delete sets DeletedAtUtc rather than hard-deleting. The group:

• disappears from the regular Groups list,
• remains visible on rollouts that referenced it (so the audit trail stays consistent),
• moves to the Deleted tab where you can restore it,
• frees its name for a partial-unique-index reuse — you can immediately create a new group with the same name.

Force rebuild¶

For dynamic groups specifically, Force rebuild kicks the reconciler synchronously and shows a "before/after" agent count. For a static group it is a no-op.

Bulk delete¶

Multi-select on the Groups list, then Delete. The confirmation modal shows the per-group member count and any rollouts that reference the group.