systemslab host drain

Description	Drain a host so the scheduler assigns it no new work.
Usage	systemslab host drain [OPTIONS] <UUID>

Description

The systemslab host drain command cordons a host out of the scheduler so no new jobs are placed on it. Use it to reclaim a machine that is both a developer box and a registered agent (for example a Mac Studio) so you can work on it locally without contaminating experiment measurements.

The transition depends on the host's current state:

Current state	Result
idle	Transitions immediately to drained (safe for local work).
busy / assigned	Transitions to draining; reaches drained once its job finishes.
draining/drained	No-op (idempotent).
locked	Rejected — the agent is already shutting down.

The host stays cordoned until you run systemslab host reactivate; there is no automatic timeout. To see which hosts have finished draining and are safe for local work, run systemslab host list --state drained.

Examples

Cordon an idle host and return immediately:

systemslab host drain 0194d39d-00d8-7fd1-5a72-1c3b7565ab66

Drain a busy host and block until it is safe for local work:

systemslab host drain 0194d39d-00d8-7fd1-5a72-1c3b7565ab66 --wait

Options

Option	Default	Description
<UUID>		The ID of the host to drain. Use systemslab host list to find host IDs.
--wait		Wait until the host reaches the drained state before returning. Polls the host's state roughly once a second (safe for local work once it prints drained) and times out after about two minutes; on timeout the command exits with an error, but the drain keeps running in the background — re-check with systemslab host list --state drained. Without this flag the command returns as soon as the drain is requested, which for a busy host means it may still be draining.

Common Options

Option	Default	Description
--systemslab-url		The URL at which to access the systemslab server.
--color	auto	Controls when color is used in the output. Possible values are auto, always, and never.
--output-format	long	Output format to use when outputting messages. long will result output designed to be human-readable while short is short output meant to be used within scripts.

Environment Variables

Variable	Description
SYSTEMSLAB_URL	Specify the URL used to contact the SystemsLab server. Equivalent to --systemslab-url.