<!-- source: https://docs.dreamlake.ai/lakeshore/hosts/power @ 0.1.192 b2f973b1 -->
# 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:

```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](https://github.com/dreamlake-ai/dreamlake-workspace/pull/1110),
[backend PR 1113](https://github.com/dreamlake-ai/dreamlake-workspace/pull/1113),
and [CLI PR 249](https://github.com/dreamlake-ai/dreamlake-cli/pull/249).
Those open dependencies do not become released or implemented by this power API.
