DreamLake

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 suffixProvider actionProvider permission
/power/startEC2 StartInstanceslakeshore-provider:update
/power/stopEC2 StopInstanceslakeshore-provider:update
/power/restartEC2 RebootInstanceslakeshore-provider:update
/power/terminateEC2 TerminateInstanceslakeshore-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:

json
{"requestId":"restart-worker-20261016-1","enrollmentId":"0123456789abcdef01234567","allowActiveWork":false}

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:

json
{"requestId":"terminate-worker-20261016-1","enrollmentId":"0123456789abcdef01234567","allowActiveWork":false,"volumes":"delete-on-termination"}

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.