Maintenance Mode

Maintenance mode temporarily marks an agent as off-limits so it is held back from new commands and deployments while you patch, reboot, or otherwise service the machine. Each agent in maintenance carries a reason, who enabled it, when, and an optional end time. You can toggle maintenance on a single agent or a whole group, from the console, the REST API, or PowerShell.

What maintenance mode does — and doesn't

Maintenance mode is a server-side flag on the agent record. It does not stop the agent process, uninstall anything, or block heartbeats — the agent keeps checking in and stays visible. What it changes is targeting: when you build a command or deployment, agents in maintenance are excluded from the selection so a routine rollout can't land on a machine you're actively servicing.

What a maintenance record holds#

When an agent is in maintenance, its record exposes these fields (visible in the console, and returned on the agent object by the API and PowerShell):

Field	Type	Description
`isInMaintenance`	bool	Whether the agent is currently in maintenance mode.
`maintenanceReason`	string	The reason supplied when maintenance was enabled.
`maintenanceEnabledBy`	string	The user who enabled maintenance mode.
`maintenanceEnabledAt`	datetime	When maintenance mode was enabled.
`maintenanceEndTime`	datetime	Optional scheduled end time. When it passes, maintenance clears automatically.

Automatic end time

If you set an end time when enabling maintenance, the agent leaves maintenance on its own once that moment passes — the flag is cleared the next time the server reads the agent's record, so no manual step is required to end a scheduled window. Leave the end time empty to keep the agent in maintenance until you disable it explicitly.

Toggle maintenance in the console#

Open Agents in the web console. Agents currently in maintenance show an In Maintenance status badge, and the fleet counters include a Maintenance tile you can click to filter the list down to just those agents.

Each agent row has a maintenance action button:

Enable maintenance opens a dialog asking for a reason (at least 3 characters, required) and an optional end time. Confirm to place the agent in maintenance.
Disable maintenance takes the agent back out of maintenance immediately.

Toggling maintenance requires the Operator or Admin role. Changes broadcast live, so other open consoles and the deployment/command builders update without a refresh.

Maintenance in the targeting picker

When you pick agents for a command or a deployment, agents in maintenance appear with a 🚧 badge and are not selectable — "select all" and collection expansion skip them too. If an agent enters maintenance while you're mid-selection, it is automatically de-selected so it can't be included by accident.

How maintenance affects commands#

Beyond the picker, the server also honors maintenance at execution time. If a command is executed against an agent that is in maintenance, that agent is not dispatched to — instead it receives a per-agent Skipped result. The skipped result carries the maintenance details (reason, who enabled it, when, and the end time) so it's clear why the agent was passed over, and you can re-run against it once maintenance is lifted.

Toggle maintenance via the REST API#

All maintenance endpoints require an Operator or Admin token. Enable maintenance on a single agent with a reason and optional end time:

POST /api/agents/550e8400-e29b-41d4-a716-446655440000/maintenance/enable
{
  "reason": "Scheduled maintenance window",
  "endTime": "2026-07-20T18:00:00"
}

The reason is required (3–500 characters); endTime is optional. Take an agent back out of maintenance:

POST /api/agents/550e8400-e29b-41d4-a716-446655440000/maintenance/disable

To act on many agents in one call, use the bulk endpoints. Bulk enable requires a reason; both return a summary with the requested, succeeded, and failed counts:

POST /api/agents/maintenance/bulk-enable
{
  "agentIds": ["550e8400-e29b-41d4-a716-446655440000", "550e8400-e29b-41d4-a716-446655440001"],
  "reason": "Scheduled maintenance window",
  "endTime": "2026-07-20T18:00:00"
}

List every agent currently in maintenance:

GET /api/agents/maintenance

You can also filter the main agent list to the maintenance status:

GET /api/agents?status=Maintenance

Method & path	Role	Purpose
`POST /api/agents/{id}/maintenance/enable`	Operator / Admin	Enable maintenance on one agent (body: `reason`, optional `endTime`).
`POST /api/agents/{id}/maintenance/disable`	Operator / Admin	Disable maintenance on one agent.
`POST /api/agents/maintenance/bulk-enable`	Operator / Admin	Enable maintenance on many agents (body: `agentIds`, `reason`, optional `endTime`).
`POST /api/agents/maintenance/bulk-disable`	Operator / Admin	Disable maintenance on many agents (body: `agentIds`).
`GET /api/agents/maintenance`	Operator / Admin	List all agents currently in maintenance.

Toggle maintenance via PowerShell#

The Athena PowerShell module wraps these endpoints in Enable-AthenaAgentMaintenance and Disable-AthenaAgentMaintenance. Both accept a single -Id, a list via -AgentIds, or agents from the pipeline, and automatically use the bulk endpoint when more than one agent is supplied (Operator or Admin role required):

# Enable maintenance on one agent
Enable-AthenaAgentMaintenance -Id "550e8400-e29b-41d4-a716-446655440000" -Reason "Scheduled maintenance"

# Enable with an automatic end time four hours out
Enable-AthenaAgentMaintenance -Id "550e8400-e29b-41d4-a716-446655440000" -Reason "Patching" -EndTime (Get-Date).AddHours(4)

# Enable maintenance on a whole group by tag (routes to the bulk endpoint)
Get-AthenaAgent -Tag "production" | Enable-AthenaAgentMaintenance -Reason "Production maintenance window"

# Take agents back out of maintenance
Disable-AthenaAgentMaintenance -Id "550e8400-e29b-41d4-a716-446655440000"
Get-AthenaAgent -Tag "production" | Disable-AthenaAgentMaintenance

Parameter	Cmdlet	Description
`-Id`	Enable / Disable	A single agent's ID (accepts pipeline input by property name).
`-AgentIds`	Enable / Disable	An array of agent IDs for a bulk operation.
`-Reason`	Enable	Required reason for the maintenance window.
`-EndTime`	Enable	Optional automatic end time for the window.

Auditing#

Every maintenance change is written to the audit log, recording who made the change, the affected agent, the reason, and the action. This gives you a clear trail of when machines were pulled out of, and returned to, normal service.