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
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
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:
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:
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:
| Setting | Env var |
|---|---|
| Server URL | DREAMLAKE_REMOTE |
| Token | DREAMLAKE_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):
| File | Contents |
|---|---|
~/.dreamlake/tokens.json | the active token (dreamlake-token slot) |
~/.dreamlake/config.json | remote_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":
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:
| Deployment | API server | Web app |
|---|---|---|
| prod | api.dreamlake.ai | dreamlake.ai |
| staging | staging-api.dreamlake.ai | staging.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.
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.
| File | Role |
|---|---|
auth.yml | saved environments: { current, envs: { <name>: { server, auth?, namespace, token } } } (YAML, chmod 600) |
tokens.json + config.json | the projection: the one connection every reader uses (dreamlake-token; remote_url, namespace) |
- Login saves the environment under its name in
auth.yml, makes itcurrent, and projects it, writing the token and server together. - Logout of an environment (default:
current) removes it fromauth.yml. If the projection still holds that environment's server and token, the client projects the newcurrentenvironment, or clears the projection when none is left. Clearing deletes the token slot,remote_url,namespaceanddefault_namespace, and keeps other keys such asdevice_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.
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:
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.
The overview keeps three things separate:
| Area | Authority |
|---|---|
| Configuration | The local nymph.toml: pacing and runtime settings |
| Access | A separate private access.json, bound to the control plane, namespace and machine |
| Runtime | Read-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.
Configuration is managed independently of access:
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.
Each grant has its own default-No confirmation. For automation, --yes explicitly
approves only that one permission. Revoke independently:
Changes are saved locally and take effect after restarting that enrollment; configuration inspection is not evidence of a running process applying them.
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.