Host machine power
These endpoints require the Host power backend release; the CLI interface requires DreamLake CLI 0.72.0+. Request validation, authorization, binding, replay, and adapter routing have automated coverage. Live EC2 power mutations are not part of release acceptance on active user machines.
Machine power is separate from the Nymph connection, work admission, enrollment
access and catalog visibility. Starting, stopping, restarting or terminating a
machine does not revoke its enrollment or credentials, archive its catalog record,
or delete that record. A workstation enrolled with --local or --ssh has no
power adapter merely because it is enrolled.
The host must belong to the caller and namespace. Its provider binding comes
from the launch's persisted MachineBootstrap record, matching the exact
namespace, user, enrollment and recorded instance. Names, tags and online status
cannot establish that binding. Multiple different provider/instance bindings are
ambiguous and rejected. A revoked bootstrap binding is rejected.
Inspect before changing power
GET /namespaces/:slug/hosts/:id/power requires namespace read access and host
ownership. It returns management (unmanaged, provider, or ambiguous),
bindings, enrollments, per-action power support, instance, observation,
and activeWork. Reading the provider's instance state additionally requires
lakeshore-provider:read; denied or failed observations include an error rather
than pretending the instance is absent or stopped. checkedAt records observation
time. EC2 volume mappings include deviceName, volumeId, and nullable
deleteOnTermination.
Per-action available reports a supported binding, not a guarantee of permission,
current provider state, successful dispatch or completed power transition.
activeWork.trackedRuns counts nonterminal tracked runs for the host;
activeWork.complete is always false. Interactive shells and work launched
outside DreamLake are not fully observable.
Request one action
| Endpoint suffix | Provider action | Provider permission |
|---|---|---|
/power/start | EC2 StartInstances | lakeshore-provider:update |
/power/stop | EC2 StopInstances | lakeshore-provider:update |
/power/restart | EC2 RebootInstances | lakeshore-provider:update |
/power/terminate | EC2 TerminateInstances | lakeshore-provider:delete |
Use POST /namespaces/:slug/hosts/:id followed by the suffix. Every mutation
requires namespace lakeshore:use, host ownership and the listed provider
permission. Only an EC2 provider with a valid user-configured launch server is
supported. The adapter verifies the configured execution role; the hosted service
does not fall back to ambient provider credentials for mutations.
For example, the request body for restart is:
The exact provider-bound enrollment ID is mandatory. Unknown fields are rejected.
requestId is 1–128 characters: an initial ASCII letter or digit followed by
letters, digits, _, ., :, or -. allowActiveWork is optional and defaults
to false; it must be a boolean when supplied.
Stop, restart and terminate reject observed nonterminal tracked runs with
active_work_present, unless allowActiveWork is explicitly true. This is an
observation before dispatch, not a fence against concurrent work admission;
zero observed runs does not prove the host is idle. Starting does not use this
guard. A revoked enrollment can be used only for termination, which destroys
the instance without restoring enrollment access.
Termination additionally requires this explicit volume policy:
delete-on-termination is the only supported policy: AWS deletes EBS volumes
currently marked delete-on-termination and retains the others. It does not mean
all attached volumes are deleted. This endpoint does not change those flags and
does not offer an implicit backup or retain-all operation.
Replay and recovery
Keep the same request ID and exact original request after a lost response. The
provider operation fingerprint binds provider, instance, action, host, enrollment,
active-work override and volume policy. Changing any of these under the same ID
returns request_id_conflict; do not issue a new ID merely because a response was
lost. A committed receipt is replayed without another cloud mutation. A pending
reservation rechecks revoked-enrollment and active-work guards before continuing.
Current ownership, binding and provider authorization are still required.
Responses explicitly report enrollment: "unchanged" and catalog: "unchanged".
The receipt records provider acceptance; fetch a fresh observation to inspect
subsequent machine state. An EC2 reboot has no synchronous state transition in
its response and normally retains the instance's running state.
Archive/restore and enrollment retirement are separate changes tracked by backend PR 1110, backend PR 1113, and CLI PR 249. Those open dependencies do not become released or implemented by this power API.