title: "Server groups" description: "Logical labels you can attach to servers — group by environment, role, or region." last_updated: "2026-05-24"

Server groups

A server group is a logical label like production, staging, or eu-west. Groups let you filter the dashboard, apply maintenance windows in bulk, and (eventually) route alerts to different channels. A server can belong to one group at a time.

Groups have no effect on metric collection or pricing. They are purely organizational.

Creating a group

From the dashboard, go to Servers and open the group manager (the chip with a +, or Manage groups in the toolbar). Pick a name and save. Group names are scoped to your account — they don't need to be globally unique.

You can also create a group over the API:

curl -X POST https://api.boxwatch.app/server-groups \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"production"}'

{
  "group": {
    "id": 12,
    "name": "production",
    "server_count": 0,
    "created_at": "2026-05-24T18:42:00Z"
  }
}

Assigning servers

In the dashboard, open a server and pick a group from the dropdown in the server-detail header. Or update it over the API:

curl -X PUT https://api.boxwatch.app/servers/42 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"group_id":12}'

A server can be moved between groups freely. To unassign, set group_id to null.

Filtering the dashboard

The dashboard's server list has a group filter at the top. Click a group chip to show only servers in that group; click it again to clear. The selection persists across page reloads (stored in localStorage), so you can leave production selected by default if that's what you usually look at.

The same filter applies to the alerts page and the metrics overview.

Bulk maintenance windows

A maintenance window can target either a single server or a whole group. Targeting a group is the practical reason groups exist: scheduling a Sunday-2am OS upgrade across production is a one-step operation. See Maintenance windows for details.

Alert routing per group

Per-group notification channel routing is on the roadmap — the idea is to send production alerts to a different Slack channel than staging. The data model already carries the group ID; the routing layer is in progress. (See the Alerts docs once they're published.)

API endpoints

Lists your groups with a server count for each.

Creates a group. Body: { "name": "..." }.

Renames a group. Body: { "name": "..." }.

Deletes a group. Servers in the group become ungrouped (group_id is set to NULL). No servers are deleted.

Notes

• There's no hard cap on the number of groups. It's an organizational tool, not a billable resource.
• Groups are flat — there's no nesting in v1. Use prefixes (prod-web, prod-db) if you want a pseudo-hierarchy.
• Deleting a group is safe. The servers in it survive; they just stop being grouped.