DreamLake

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. 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 suffixRequestResult
POST /name, optional descriptionserviceAccount
GET /optional page, pageSizeserviceAccounts, page, pageSize, total
GET /:id—account, project grants, host grants, enrollment binding
POST /:id/enrollmentenrollmentIdaccount and binding
PUT /:id/project-grants/:projectIdrolegrant
DELETE /:id/project-grants/:projectId—revoked: true
PUT /:id/host-grants/:hostIdread, use booleansgrant
DELETE /:id/host-grants/:hostId—revoked: true
POST /:id/revokeempty objectaccount 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:

RouteAuthorization
GET /machine/selfactive, bound machine identity
GET /machine/projects/:idexplicit project grant allowing project:read
GET /machine/hosts/:idexplicit 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:

["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.