Host enrollment

dreamlake hosts enroll bootstraps a user-owned nymph over your existing SSH connection, then waits for the backend to confirm that exact enrollment online. Provider registration is not required. It requires the new authenticated Hosts API and a control plane supporting identity-bound grants and signed reconnect; these changes must be deployed together. --dry-run only validates inputs and does not contact the server or target.

The target needs Python 3, OpenSSL, an accessible systemd user manager, and user linger enabled for service persistence after logout. Enrollment never uses sudo. It reuses an installed nymph, or downloads the official installer into the user-local binary directory. --nymph-version selects an installer version when the binary is absent. The target generates and retains its nymph private key; only its public key and Unix username go to the enrollment API. Short-lived grants travel to the target over SSH stdin, not process arguments or logs.

Check the target account before enrollment:

ssh bos14-ctrl 'systemctl --user show-environment >/dev/null && loginctl show-user "$(id -un)" -p Linger --value'

If this prints no, enable lingering for that account:

ssh bos14-ctrl 'loginctl enable-linger "$(id -un)"'

If local policy denies this operation, ask the host administrator to enable it. Enrollment checks these prerequisites before creating an identity or requesting a grant.

Use --lakeshore-id when your namespace has multiple control-plane connections. The command prints a request ID before enrollment. After an interrupted request, repeat the same inputs with --request-id <id>. If the API returns retryAt, wait until that time before starting a new request. JSON errors retain the request ID and available operation/retry fields. --wait-seconds bounds readiness polling (default 60). A timeout reports pending and exits nonzero; it does not claim enrollment succeeded. Repeat execution preserves the target identity and reuses the user service. Runner/job readiness is a separate check from a connected nymph.

Direct enrollment on the target host is planned but has no implemented command syntax yet. For the broader workflow, see the upcoming host enrollment guide in the main DreamLake docs (not yet deployed). This page is the CLI input reference.

dreamlake hosts enroll -p fortyfive/bos14 -n bos14-ctrl --ssh bos14-ctrl
dreamlake hosts status fortyfive/bos14/bos14-ctrl --json
dreamlake hosts status 'fortyfive/bos14/*' --json

For configuration-only validation:

dreamlake hosts enroll -p fortyfive/bos14 -n bos14-ctrl \
  --ssh bos14-ctrl --dry-run

# Equivalent full name, with structured output:
dreamlake hosts enroll -n fortyfive/bos14/bos14-ctrl \
  --ssh '-i "/Users/ge/My Keys/key" \
    -J ge@bastion.example.com \
    -p 2222 geyang@bos14-ctrl.internal' --dry-run --json

Names have exactly three components: namespace/group/host. A matching explicit prefix and embedded prefix are accepted; conflicting prefixes and wildcards are rejected. Each component is 1–64 letters, digits, underscores or hyphens and starts with a letter or digit. A namespace in a name does not grant access to it. The control-plane namespace comes from the selected connection and can differ from the DreamLake namespace.

JSON input

dreamlake hosts enroll --config ./bos14-host.json --dry-run --json

{
  "name": "fortyfive/bos14/bos14-ctrl",
  "ssh": {
    "host": "bos14-ctrl.internal",
    "user": "geyang",
    "port": 2222,
    "identityFile": "/Users/ge/.ssh/bos14_ed25519",
    "jumpHost": "ge@bastion.example.com",
    "options": { "ServerAliveInterval": "30" }
  }
}

The file may also contain prefix. Explicit CLI name/prefix fields override those file fields, then prefix conflicts are checked. --ssh replaces the entire file SSH object. Unknown fields are rejected. Identity files are local paths, never embedded key contents. Use either ssh.user or user@host, not both. --json controls output only.

SSH argument text is tokenized without shell expansion or evaluation; multiline whitespace, line continuations, and quoted paths are supported. Do not include ssh itself or a remote command. The initial supported flags are -i, -J, -p, -o, -l, and -F, each followed by a separate value. Supported -o settings are BatchMode, ServerAliveInterval, ServerAliveCountMax, ConnectTimeout, IdentitiesOnly, StrictHostKeyChecking, and UserKnownHostsFile. Use an existing SSH config alias for more advanced transport settings. Preview validates syntax, not whether an identity file exists, an SSH alias resolves, or SSH authentication works. Passwords are not accepted in arguments or JSON. Future interactive enrollment should let OpenSSH prompt for target/jump-host passwords locally; the preview does not attempt authentication and does not require agent forwarding.

Group status accepts --page (1–100000) and --page-size (1–100). Exact host lookup starts at the first page and follows matching pages automatically.

Host status is read from the backend; enrollment succeeds only when the returned enrollment ID reports online. Infrastructure provisioning and workload execution remain separate from this operation.

Optional cross-device SSH credential storage (preview only)

Enrollment initiated from your laptop uses your local SSH access. Normal operation through nymph does not require saved SSH credentials. To request future per-host vault access from your other devices, including mobile, opt in:

dreamlake hosts enroll -n fortyfive/bos14/bos14-ctrl \
  --ssh '-i /Users/ge/.ssh/bos14_ed25519 bos14-ctrl' \
  --save-credentials --dry-run --json

Saving credentials does not authorize DreamLake backend services to initiate SSH connections. Any backend SSH delegation is a separate permission to design; this flag does not grant it. The vault access, encryption, recovery, and revocation mechanisms remain to be implemented.

This flag currently records intent only: output includes credentialSaveRequested: true, credentialsSaved: false, and a warnings array. Without the flag, credential saving is not requested. Human-readable warnings go to stderr. The preview does not read identity files, save, or upload credentials. Real enrollment with --save-credentials remains unsupported and exits nonzero before contacting the target; omit the flag for normal enrollment. Do not put private keys or passwords into configuration JSON. The flag is a CLI-only opt-in; it is not accepted as a configuration JSON field.

Cross-component integration check

The repository includes a repeatable check against an isolated local Hosts API, control plane, persistent databases, and a compiled nymph binary:

pnpm build
node scripts/test-hosts-integration.mjs \
  /path/to/protected-test-environment.json /path/to/nymph

The protected JSON supplies remote, namespace, token, outsiderToken, and lakeshoreId; use test-only credentials and a loopback server. The test launches the actual CLI and nymph subprocesses, verifies online status, stable explicit request replay, consumed-token and token-absent reconnect, and forbidden access before target mutation. It uses local SSH/service adapters, so this is not a live-network SSH or actual-systemd test. Real target access and runner execution need their own acceptance checks. Test processes are stopped and temporary identity files removed afterward.