<!-- source: https://docs.dreamlake.ai/lakeshore/service-accounts @ 0.1.192 b2f973b1 -->
# Service accounts

Each Nymph daemon has one service account in DreamLake. Human users and service
accounts have separate records and share resource permission policies. Creating
an account does not give the machine its creator's access. A namespace owner
assigns the resources it may use.

These APIs require the matching DreamLake server, control-plane and CLI releases.
Installing a newer CLI alone does not enable an older server. Machine HTTP access
requires the control plane's immutable enrollment-anchor field and fails closed
when that field or the configured control plane is unavailable.

## Create and bind an existing machine

A personal namespace's owner, or an organization member with role `OWNER`, manages
its service accounts. Ordinary organization members and machines cannot manage
them.

```bash
dl service-accounts create my-team --name dreamfs-worker --description "DreamFS development daemon"
dl service-accounts list my-team
dl service-accounts show my-team/0123456789abcdef01234567
dl service-accounts bind my-team/0123456789abcdef01234567 --enrollment 444444444444444444444444
```

Names start with a lowercase letter and contain at most 63 lowercase letters,
digits, underscores or hyphens. Retrying creation with the same name and
description returns the same account. Changing the description or reusing a
revoked name returns a conflict.

Binding an enrolled Nymph does not restart or rekey it. Both records must belong
to the same namespace. The binding is one-to-one and permanent: neither side can
be reassigned to a different identity. Repeating the same binding is safe. The
machine receives `read` and `use` grants for its own host; project access remains
empty until explicitly granted. Its private key stays on the machine.

## Grant resource access

```bash
dl service-accounts project-grants set my-team/0123456789abcdef01234567 --project 111111111111111111111111 --role READ
dl service-accounts host-grants set my-team/0123456789abcdef01234567 --host 222222222222222222222222 --read
dl service-accounts project-grants remove my-team/0123456789abcdef01234567 --project 111111111111111111111111
```

Projects and hosts must belong to the service account's namespace. Project roles
use the existing `READ`, `WRITE` and `ADMIN` policy. Host `read` and `use` are
independent; setting a grant replaces both flags. Removing a grant denies that
resource on subsequent authorized requests.

The initial machine HTTP surface exposes identity and bounded project/host
metadata reads. `WRITE`, `ADMIN` and host `use` grants do not turn machine
credentials into human login tokens or enable arbitrary user APIs. Workload data
writes and additional resource endpoints require explicit machine-principal
integration in those endpoints.

A service-account host grant is not a person's connection grant. It opens no
terminal or SSH session, and a service account cannot receive one. To let a
teammate or a team connect to your machine, see
[Share a machine with a teammate](/lakeshore/hosts/browser-terminal.md#share-a-machine-with-a-teammate).
These are DreamLake permissions, not cloud IAM roles.

## Automatic EC2 installation

Launch one EC2 machine with a host name to request automatic registration:

```bash
dl providers instances launch my-team/333333333333333333333333 --host-name my-team/dreamfs/worker --unix-user dreamlake-agent --request-id dreamfs-worker-1 --json
```

DreamLake creates a dedicated service account for that launch. To use an unused
account you have already configured, add `--service-account ACCOUNT_ID`.
Automatic registration currently requires `--count 1`; use a separate account,
host name and request ID for each additional Nymph.

The instance must use a trusted Ubuntu/Debian image with cloud-init, systemd and
outbound network access to DreamLake, the selected control plane, package mirrors
and pinned release artifacts. Supported architectures are those whose Nymph and
uv checksums the server administrator has configured. Other images are not
validated by checking architecture alone.

The protected bootstrap implementation requires Nymph 0.1.11 and CLI 0.50.0 or
newer. It is delivered in companion implementation PRs; verify deployment before
using it. User data contains installer code and non-secret configuration only.
After the launch receipt is committed, the machine fetches a KMS-encrypted
registration envelope. KMS binds decryption to AWS's `ec2:SourceInstanceARN`, the
recorded instance ARN and this deployment's API audience. Another instance using
the same role cannot decrypt the target's envelope. This requires the dedicated
instance profile and key policy described below; a shared administrator role is
not an acceptable substitute.

Nymph generates its Ed25519 key locally. A root-only runtime file preserves the
capability across a partial install and is removed after starting the user service.
The capability expires after 20 minutes and binds one public key to one launch.
Its encrypted server-side retry material is erased on claim, revocation or expiry.
No human login or Vault credential is included in user data, setup command strings,
host-key metadata or logs. Protect IMDS and the machine's local private files.

The default execution Unix account is `dreamlake-agent`, separate from the human
operator account. Keep personal DreamLake logins in a different Unix home;
process environment selection alone is not a security boundary between processes
that can read one another's files. An explicit `--unix-user` override must preserve
this separation.

The daemon's required setup hook verifies signed machine identity and its own
host read. Optional harnesses, their DreamLake skills, and Codex daemon startup
come from the user's resolved `agentSetup` launch layer below. Setup failure
keeps the daemon in setup rather than advertising readiness. Vendor inference
login remains independent of DreamLake machine identity.

When `agentSetup.startCodexDaemon` is `true`, provisioning enables
`dreamlake-codex-start.service` for the machine user. The oneshot unit invokes
`codex app-server daemon start`, preserves an existing daemon, and starts again
with the lingering user manager. It does not create chats, enable remote control,
or install vendor credentials. Inspect it with
`systemctl --user status dreamlake-codex-start.service`. Disable automatic startup
with `systemctl --user disable dreamlake-codex-start.service`; this preserves an
already running daemon. Removing the unit and reloading the user manager rolls
back the startup configuration. Omission or `false` creates no Codex startup unit.

Repeat a launch with the same request ID and inputs after an interrupted reply.
DreamLake pins the rendered installer and resolved launch configuration and uses
the cloud's idempotency token. It records the provider receipt before allowing
redemption, so retrying can repair a missing registration attachment without
launching another instance. A conflicting request or provider configuration
change is rejected.

A launch receipt is not proof that Nymph is online or that a workload succeeded.
Inspect the named host and run a representative job. If bootstrap expires or
installation fails, inspect the retained instance and registration state before
requesting another paid machine. This path does not automatically destroy a
failed development machine.

## Management API

All management routes below are under `/namespaces/:slug/service-accounts` and
require an authenticated human namespace owner.

| Method and suffix | Request | Result |
| --- | --- | --- |
| `POST /` | `name`, optional `description` | `serviceAccount` |
| `GET /` | optional `page`, `pageSize` | `serviceAccounts`, `page`, `pageSize`, `total` |
| `GET /:id` | — | account, project grants, host grants, enrollment binding |
| `POST /:id/enrollment` | `enrollmentId` | account and binding |
| `PUT /:id/project-grants/:projectId` | `role` | grant |
| `DELETE /:id/project-grants/:projectId` | — | `revoked: true` |
| `PUT /:id/host-grants/:hostId` | `read`, `use` booleans | grant |
| `DELETE /:id/host-grants/:hostId` | — | `revoked: true` |
| `POST /:id/revoke` | empty object | account and revocation delivery status |

List page size defaults to 50 and is limited to 100. Account and enrollment IDs
are opaque 24-character hexadecimal identifiers. Responses do not contain machine
private keys, enrollment tokens or human credentials.

## Signed machine reads

The machine surface authenticates an Ed25519 signature independently of human
JWT authentication:

| Route | Authorization |
| --- | --- |
| `GET /machine/self` | active, bound machine identity |
| `GET /machine/projects/:id` | explicit project grant allowing `project:read` |
| `GET /machine/hosts/:id` | explicit host `read` grant |

Send these headers on each request:

- `x-dreamlake-enrollment`: the bound enrollment ID.
- `x-dreamlake-timestamp`: current Unix time in milliseconds, as 13 decimal digits.
- `x-dreamlake-nonce`: a fresh random unpadded base64url value, 32–64 characters.
- `x-dreamlake-signature`: the 64-byte Ed25519 signature in unpadded base64url.
- Optional `x-dreamlake-key-id`: the control plane's current 16-character key ID.

Sign the UTF-8 bytes of this compact JSON array, with no added whitespace:

```text
["dreamlake-machine-v1",audience,method,url,bodySha256,enrollmentId,timestamp,nonce]
```

`method` is uppercase. `url` is the exact request path, including its query
string. `bodySha256` is the lowercase hexadecimal SHA-256 of the raw body; these
GET routes use an empty body. `timestamp` and `nonce` are strings matching the
headers. `audience` is the deployment's configured `MACHINE_AUTH_AUDIENCE`, not a
caller-selected Host header.

The server checks the exact namespace, host, enrollment, machine ID, Unix user
and original enrollment key against the selected control plane. The original
key anchors the identity; signatures use a currently valid control-plane key.
Active keys and retiring keys within their recorded overlap deadline work.
Expired, revoked and mismatched keys fail. Requests fail closed if the control
plane cannot confirm the identity. Without a key-ID header, at most eight valid
candidate keys are considered.

The timestamp window is 60 seconds. The server records used nonces durably and
rejects replays, including concurrent copies. Account, enrollment, namespace and
resource grants are checked on each request. There is no service-account JWT
that can be substituted into the human API.

## Revocation

```bash
dl service-accounts revoke my-team/0123456789abcdef01234567
```

Revocation is permanent. DreamLake first disables local account/enrollment
authority and outstanding bootstrap capabilities, then delivers the daemon
revocation to its control plane. The response includes `revocationState` and an
entry per enrollment with state `revoked` or `pending`.

If delivery is pending, repeat the revoke command to retry. A pending response
is not confirmation that the remote daemon has been disabled. Successful
control-plane revocation covers rotated credentials and subsequent reconnects.
It prevents subsequent authenticated work; it does not promise to kill a process
that was already executing.

## Server configuration

Automatic installation requires `DREAMLAKE_BOOTSTRAP_API_URL`, a pinned
`NYMPH_BOOTSTRAP_VERSION`, a pinned `UV_BOOTSTRAP_VERSION`, and matching
`NYMPH_BOOTSTRAP_SHA256_X86_64` / `UV_BOOTSTRAP_SHA256_X86_64` or
`NYMPH_BOOTSTRAP_SHA256_AARCH64` / `UV_BOOTSTRAP_SHA256_AARCH64` artifact hashes.
The API URL must be an HTTPS origin. Existing server encryption and a configured
execution-capable Lakeshore connection are also required.

Set a stable `MACHINE_AUTH_AUDIENCE` for signed machine HTTP requests. Deploy the
control-plane enrollment-anchor and revocation support before enabling the
matching DreamLake server. The release process must create and verify the
service-account binding, bootstrap reservation and nonce uniqueness indexes and
the nonce expiry index before serving traffic.

## Protected-delivery deployment and rollback

Review `dreamlake-server/infra/machine-bootstrap.yaml` and deploy it as a new,
isolated CloudFormation stack in the provider's account and region. Supply the
DreamLake backend's existing IAM principal as `EncryptPrincipalArn` and the exact
API origin as `ApiOrigin`. The stack creates a dedicated EC2 role/profile and a
rotating KMS key; it does not attach permissions to existing roles. Its policy
explicitly denies decryption by other principals, without EC2 source identity,
for another instance's context, or for another audience. The backend receives
Encrypt permission only. Protect KMS policy administration as credential authority.

Set `DREAMLAKE_BOOTSTRAP_KMS_KEY_ARN` and
`DREAMLAKE_BOOTSTRAP_INSTANCE_PROFILE` from the stack outputs. The provider's
configured account and region must match the KMS key. The resolved launch layer's
`iamInstanceProfile` must exactly match the dedicated profile ARN. Missing or
mismatched configuration fails before launching EC2.

Also configure `DREAMLAKE_CLI_BOOTSTRAP_VERSION` (0.50.0 or newer) and per-architecture
`DREAMLAKE_CLI_BOOTSTRAP_SHA256_X86_64` / `_AARCH64`, alongside the Nymph and uv
pins above. Publish CLI artifacts through its existing GitHub Actions release
workflow and Nymph through its release workflow. Do not use mutable latest URLs
or substitute local source-test results for downloaded artifact verification.

Before enabling paid launches, verify server schema/indexes, exact pinned artifact
bytes, the control plane's enrollment anchor/rotation/revocation support, and the
KMS policy. Rate-limit the ciphertext-envelope endpoint at the edge; ciphertext
is intentionally retrievable without human authentication, while KMS controls
plaintext release. Envelope retrieval is unavailable after claim/expiry/revocation.

On one disposable host, verify enrollment, required setup completion, both skill
readbacks, a permitted resource read and a real agent development task. Check
cross-instance KMS decryption denial and machine revocation before proceeding to
staging, then production. Check CloudTrail KMS attribution without logging
plaintext or request headers. A successful cloud launch receipt is not acceptance.

For rollback, disable new managed launches first. Retain failed hosts and the
stack/key for investigation; deleting the stack retains the key to avoid
accidentally losing recovery data. Expire/revoke pending registrations, restore
matching known-good artifacts and server code, and repeat a disposable-host test.
Never roll a required-setup host back to Nymph 0.1.10 or restore a revoked account.
Do not schedule deletion of the KMS key until all dependent tickets have expired
and every dependent machine has been retired or migrated.

The current implementation has fixture coverage for delivery context, expiry,
claim/retry, account isolation, revocation and signatures. Live AWS KMS/IAM
negative checks, cold boot, reboot and remote Codex acceptance remain deployment
gates, not claims made by unit tests.

### User-selected agent software

The shared managed bootstrap supplies enrollment, the pinned DreamLake CLI and
Nymph, protected machine credentials, native SSH, and machine readiness. It
installs no Node package or agent harness and starts no agent daemon unless the
user selects them. Existing running machines and persisted launch retries retain
their original setup; a new request uses the new contract.

Use the existing provider/named/request launch layers to select software:

```json
{
  "agentSetup": {
    "nodeVersion": "22.22.2",
    "codexVersion": "latest",
    "claudeVersion": "2.1.296",
    "startCodexDaemon": false
  }
}
```

Save this preset as `agent.layer.json`. `nodeVersion` is required; Node and
Claude use exact versions. Set `codexVersion` to `latest`. Older Codex pins in
saved presets also resolve to `latest`. Omit a harness to leave it uninstalled.
`startCodexDaemon: true` requires Codex. Preflight shows the resolved settings
and their source layers.

```bash
dl providers preflight my-team/333333333333333333333333 --file agent.layer.json --json
dl providers instances launch my-team/333333333333333333333333 --file agent.layer.json --host-name my-team/dev/agent --unix-user dreamlake-agent --request-id agent-dev-1 --json
```

`agentSetup` requires managed enrollment (`--host-name`); raw VM launches reject
it rather than silently skipping setup. The layer also needs the provider's
required image, machine, network and protected instance-profile configuration.
Node and Claude use npm; Codex uses its native installer. Downloads are verified.
Readiness checks the selected tools, their DreamLake skills and machine identity.

**Codex launch and updates:** New managed EC2 launches install
latest stable Codex in the machine user's `~/.codex/packages/app-server-daemon`.
The terminal CLI and daemon share its `current` package and native update channel.
Run `codex update` to update both; it may restart the daemon and interrupt work.
Bootstrap retries preserve updates. Codex manages retained rollback releases.

For an existing machine, inspect the selected user's PATH, package ownership,
daemon `current` selection and running process identities before changing the
launcher. If the existing daemon package is a verified stable release, a guarded
user-owned launcher can point new CLI invocations at that same package. Keep an
exact launcher backup and verify the new login-shell resolution. This cutover
does not require running `codex update`, restarting the daemon or deleting older
packages. Active processes may still reference those older releases.

Preserve custom daemon builds, user configuration, credentials and session
history. A machine with no installation needs a separate verified user-space
install; an offline or unauthorized machine remains incomplete. Do not run the
new-machine bootstrap over an existing installation or remove packages solely
because another version is now selected.

If launch reports `codex_install_conflict`, remove competing Codex installations
from the image and launch with a new request ID. Bootstrap does not delete them.
Existing machines and Kubernetes images are unchanged.

Project dependencies, repository setup and startup tasks remain user choices.
Use the existing tracked-run setup/repository mechanism for those tasks; this
field does not accept arbitrary root shell commands or vendor credentials.
Verify one disposable launch, reboot, skill discovery and a real development task
before calling a particular preset ready. For rollback, stop new launches,
restore matching server code and preserve the immutable retry receipt; never
reuse a request ID with different software choices.
