DreamLake

Environments

The CLI can target multiple DreamLake deployments. It ships with two built-in environments — staging and prod — so you never type their URLs. Each environment keeps its own token; switching never logs you out of the other.

Log into a built-in environment

terminalbash
dl login --env staging
dl login --env prod

dl login prints the complete authorization link with the code in its query parameters. Open that link to authorize without copying the code manually, including when using --no-browser on a remote machine. The code is also shown as a fallback if prompted.

No --url / --bss needed — the URLs are baked in. dl login with no --env re-authenticates the active environment, and falls back to prod when nothing is logged in yet.

Switch environments

terminalbash
dl auth env list           # show logged-in envs (* = active)
dl auth env use prod       # switch — no URLs, no re-login
dl auth env remove staging # forget a saved env
Renamed from `dl env`

These lived at dl env ... before v0.6; the top-level env command is a compatibility alias for dl scene (see Scenes). For login switching, update scripts to dl auth env ....

Every command then targets the active environment — and so does the Python SDK: switching writes the token and server to ~/.dreamlake, the same files dreamlake-py resolves its connection from. One switch moves both tools. dl profile shows which environment is in effect ([env: prod]).

The * in auth env list marks the environment your commands will actually hit, not just the last one you selected — if a DREAMLAKE_* env var is overriding the connection, or the files were edited by hand, the star disappears and a memo explains why.

Select the default CLI namespace

CLI 0.102.0+: su selects the default resource namespace for subsequent CLI invocations under the current saved login:

bash
dl su fortyfive
dl hosts list
dl hosts list --namespace geyang
dl su geyang

Use the actual namespace name; personal is not a special alias. Selection requires your personal namespace or an organization you belong to, checked with the current authenticated account. It changes local CLI scope and does not change login identity, grant permissions, move resources, or switch the GUI. An explicit --namespace or namespace-qualified target wins for that invocation and leaves the stored default unchanged. Otherwise commands using the shared namespace resolver use the selected scope, then the signed-in personal namespace when no selection exists. Existing commands that require an explicit namespace still require it.

The selection is stored separately from cached personal identity in ~/.dreamlake/config.json, bound to the remote and a credential fingerprint. A different remote/token cannot inherit it. login, auth env use, and logout clear the selection; select it again for the intended environment. Access is still enforced by every resource route, so revoked membership causes an access error rather than a silent switch to another namespace.

The public TypeScript API requires explicit namespaces (for example, client.hosts('fortyfive')) and never reads CLI configuration. The Python host API likewise takes an explicit namespace. Python's implicit personal-namespace resolver remains tied to the authenticated identity; this CLI setting does not change that SDK default. Built-in agent /su <namespace> is a separate, conversation-scoped selection.

Custom / self-hosted environments

Define a custom environment once with its URLs, then switch by name forever:

terminalbash
dl login --env dev --url https://dev-api.example.com
dl auth env use dev
Auth server must match the target

The device-flow auth server must be the one your target API trusts. The built-ins set this automatically (staging uses staging-auth.vuer.ai, prod uses auth.vuer.ai). For a custom env on a non-default auth server, pass --auth <url>. A mismatch fails token exchange with No matching key found in JWKS.

Overrides and storage

Resolution order (high → low): flag → env var → ~/.dreamlake → prod. For one-off commands you can override the active env:

SettingEnv var
Server URLDREAMLAKE_REMOTE
TokenDREAMLAKE_API_KEY
Web app URL (receipt open: links)DREAMLAKE_WEB_URL

The effective connection lives in two files shared with the Python SDK (all chmod 600):

FileContents
~/.dreamlake/tokens.jsonthe active token (dreamlake-token slot)
~/.dreamlake/config.jsonremote_url, cached personal namespace, optional CLI default_namespace, device_secret

login and auth env use always rewrite the token and server together, so the pair can never point at different environments.

~/.dreamlake/auth.yml additionally caches a token per environment — it exists only so auth env use can switch without a new device-flow login, and is never consulted to answer "what am I connected to":

auth.ymlyaml
current: prod
envs:
  staging: { server, bss, auth, namespace, token }
  prod:    { server, bss, auth, namespace, token }

Receipt web links

Successful scene, artifact, workflow and share commands print an open: URL into the web app. The CLI derives it from the active server URL. For the known deployments:

DeploymentAPI serverWeb app
prodapi.dreamlake.aidreamlake.ai
stagingstaging-api.dreamlake.aistaging.dreamlake.ai

Any other server maps conservatively: a leading api. label is stripped (api.example.com → example.com); everything else — localhost, a custom deployment — is printed unchanged rather than guessed. Set DREAMLAKE_WEB_URL to print a different web origin (a trailing slash is trimmed); it beats every derivation above.

Staging mapping requires CLI 0.37.1

The automatic staging-api.dreamlake.ai → staging.dreamlake.ai mapping is introduced in CLI 0.37.1. On 0.37.0 and earlier, staging receipts print the API host instead — set DREAMLAKE_WEB_URL=https://staging.dreamlake.ai there; the override works in every released CLI.

Shared login contract (v1)

Every DreamLake client that reuses this login (the DreamLake CLI, ml-dash with --backend native or its managed mode, and the Python SDK as a reader) follows the same rules on ~/.dreamlake. Clients other than the SDK may override the directory for tests only.

FileRole
auth.ymlsaved environments: { current, envs: { <name>: { server, auth?, namespace, token } } } (YAML, chmod 600)
tokens.json + config.jsonthe projection: the one connection every reader uses (dreamlake-token; remote_url, namespace)
  • Login saves the environment under its name in auth.yml, makes it current, and projects it, writing the token and server together.
  • Logout of an environment (default: current) removes it from auth.yml. If the projection still holds that environment's server and token, the client projects the new current environment, or clears the projection when none is left. Clearing deletes the token slot, remote_url, namespace and default_namespace, and keeps other keys such as device_secret. Other saved environments are unchanged.
  • Orphan projection: a logout with no saved environment clears a projection that another client wrote without saving it, so a logout always stays logged out.
  • Nothing is revoked on the server; a token copied elsewhere stays valid until it expires.
bash
dl logout --env staging
Upgrading from ≤ 0.4.x

State previously lived at ~/.config/dreamlake. The first run of a newer CLI moves it into ~/.dreamlake automatically — logins survive, nothing to redo.

Optional Nymph setup after login

The login consent and local overview require CLI 0.86.0 or newer and the companion Nymph 0.1.32 or newer. These are source requirements; do not treat an older installed release as supporting this flow.

After successful interactive device login, the CLI offers an optional background service with a default No response:

Enable Nymph background service?
Supports uploads, command execution and other tools; access permissions are managed separately. [y/N]

Enter, No and cancellation leave service and access settings unchanged. Token login, noninteractive stdin/stdout and CI do not prompt. Use login --no-nymph to skip the offer. Existing local instances are shown for review; login does not register a second daemon or automatically migrate a legacy installation. Setup failure does not undo successful authentication.

bash
dl nymph
dl nymph --json

The overview keeps three things separate:

AreaAuthority
ConfigurationThe local nymph.toml: pacing and runtime settings
AccessA separate private access.json, bound to the control plane, namespace and machine
RuntimeRead-only local instance observations; missing observations remain unknown

Since 0.88.1, managed Nymph commands accept trusted home-directory aliases, such as /home/geyang pointing to /export/work/geyang. The CLI resolves the home directory before locating the existing enrollment; it does not re-enroll the machine or change its permissions. The home target must belong to the current user, with trusted owners and no group/other-writable directories in either path (root-owned sticky ancestors such as /tmp are allowed). Symlinks beneath the resolved home, including linked settings files, remain rejected. Private file ownership and permission checks still apply.

Fresh managed setup defaults both automatic upload and command execution access to denied. Enabling the service does not grant either permission. Enrollment still requires an authorized Lakeshore connection; this command does not create a control plane or copy your personal login token into Nymph. A Nymph binary without the separate-policy interface is refused before enrollment grants are requested. Configure or upgrade Nymph first when that prerequisite is missing.

bash
dl nymph setup --name alice/computers/laptop --lakeshore-id CONNECTION_ID

Configuration is managed independently of access:

bash
dl nymph config --name alice/computers/laptop
bash
dl nymph config set --name alice/computers/laptop --poll-seconds 30 --max-invocations 4

Use CLI 0.86.1+ when selecting a named enrollment. It honors --name on parent or final commands and rejects conflicting selections before any mutation. CLI 0.86.0 could silently use the default profile for subcommand operations even when a name was provided; upgrade before managing multiple enrollments.

Configuration edits validate with the installed Nymph parser before committing. They do not change access.json. Select a managed enrollment by its full name when the automatic namespace/computers/hostname name does not apply.

bash
dl nymph access show --name alice/computers/laptop
bash
dl nymph access grant upload --name alice/computers/laptop
dl nymph access grant command-execution --name alice/computers/laptop

Each grant has its own default-No confirmation. For automation, --yes explicitly approves only that one permission. Revoke independently:

bash
dl nymph access revoke upload --name alice/computers/laptop
dl nymph access revoke command-execution --name alice/computers/laptop

Changes are saved locally and take effect after restarting that enrollment; configuration inspection is not evidence of a running process applying them.

bash
dl nymph restart --name alice/computers/laptop

The daemon fails closed on missing, malformed, foreign-scope or non-private managed policies. Upload access controls Nymph's automatic session metadata, compute metrics and experiment reporting; it does not enable a transcript archive by itself. Command access covers remote jobs, exec, setup scripts, SSH and remote updates, including their requested outputs. Server-side authorization is additionally required: local consent cannot grant access to another account or bypass an API ACL. Already-running commands finish under the prior startup snapshot until the restart/drain completes.

Independent transcript archive services retain their own configuration and credentials. The overview labels that boundary; changing Nymph consent does not silently alter an existing archive collector. Legacy installations with no managed access file retain their current behavior and are displayed as unmanaged / unknown, not as newly consented or denied.