server_maintenance

Check whether the server can restart or update itself, and start either action remotely. An admin panel uses it to offer “Restart” and “Update” buttons without shell access to the host.

Request

{
  "cmd": "server_maintenance",
  "action": "restart",
  "confirm": true,
  "listener": "maintenance-1"
}

Field	Type	Required	Description
`action`	string	No	`status`, `restart`, or `update`. Defaults to `status`.
`confirm`	boolean	For `restart` and `update`	Must be `true`. Guards against starting an action by accident.

status reports the current state and changes nothing.
restart stops the process so the launcher starts it again.
update runs the launcher’s updater script, then restarts. Clients can’t choose what gets installed: there is no field for a command, repository, branch, or path.

Response

{
  "cmd": "server_maintenance",
  "state": "restarting",
  "message": "Maintenance requested",
  "restart_supported": true,
  "update_supported": true,
  "version": "1.0.0",
  "started_at": 1758700000000,
  "listener": "maintenance-1"
}

Every action returns the same status object. Nobody else receives a broadcast.

Field	Description
`state`	`idle`, `updating`, `restarting`, or `failed`.
`message`	Human-readable text for the current state.
`restart_supported`	`true` when the server runs under the managed launcher.
`update_supported`	`true` when the launcher also provides an updater script that exists on disk.
`version`	The `service.version` setting. It’s a label, not a source revision.
`started_at`	When this process started, in Unix milliseconds.
`reason`	Present only when the launcher isn’t in use: `Start the server with scripts/run.sh to enable remote restarts and updates.`
`details`	Up to 16,000 characters of updater output after a failed update. Sent to the owner only.

What happens after you start an action

The response comes back before any work starts. Treat it as “accepted”, not “done”.

About two seconds later the server begins. For update, state stays updating while the updater downloads and builds. The server keeps running and still answers status.
If the updater fails, state becomes failed and the old process keeps running. The owner can read the output in details.
Otherwise state becomes restarting, and about two seconds later the process exits so the launcher can start it again.
Your connection drops. Reconnect and authenticate again. The new process reports state: "idle" and a new started_at.

The start, the restart, and any failure are recorded in the audit log under server_management.

Permissions

status requires manage_server. restart and update also require the owner role. All actions are blocked while you are timed out.

Errors

`val`	When
`Action must be a string`	`action` is present but isn’t a string.
`Action must be status, restart or update`	`action` is some other string.
`Only the server owner can restart or update the server`	A non-owner sent `restart` or `update`.
`Confirm maintenance with confirm: true`	`confirm` is missing or not `true`.
`This action requires the managed launcher`	`restart_supported` or `update_supported` is `false` for the chosen action.
`A maintenance operation is already running`	Another restart or update is in progress.