Browser terminal
Compute can open an interactive SSH terminal on a machine you own and have
enrolled, or on one whose owner has shared it with you.
Open Compute, select the machine, choose Terminal
(/:namespace/compute?view=terminal), then Connect. The terminal runs as
the enrolled Unix user. Keys stay on the server, and the browser never sends a
host address or a key.
A machine is listed only when its daemon is online, reports native SSH support, and is bound to an enrollment you own in that namespace or one shared with you. In an organization namespace, membership alone does not list anyone else's machines.
Share a machine with a teammate
In an organization namespace, the owner of a machine can let one named member, or one team of the organization, connect to it with their own DreamLake account:
- Open Compute in the organization namespace and select the machine.
- Under Access, choose the Unix account, enter the member's username, and choose Grant.
A team grant names the team's slug instead of a username; see Manage grants without Compute.
The member then sees the machine in Compute, marked Shared with you, and
can open the terminal there or with dl ssh <namespace>/<group>/<machine>.
Each person signs in as themselves, and their DreamLake sessions and saved
sessions stay their own. DreamLake never passes the owner's DreamLake sign-in
or connection credentials to the member; credentials stored on the machine
itself are a different matter (see below). The grant covers connecting only. Machine settings, metrics,
jobs, the agent list and sharing stay with the owner.
- Only the machine's owner can grant or revoke, and only to a current member of the organization or a team of that organization. Personal namespaces cannot share machines.
- A grant covers one enrollment, that is one Unix account on that machine.
- A team grant follows the team's membership. It reaches each person who, at the time of each connection, is a direct member of that team, is not a team guest, and is a current organization member. Members of parent or child teams are not included. A guest never connects through a team grant, even after joining the organization, until their team role is changed. People the team's owners and admins add later get access too, without the machine owner being asked, so grant a team only when you accept everyone its managers may add. An archived team's grants give no access until it is restored.
- A person's access is the union of their current grants: they can reach the same enrollment directly and through one or more teams.
- Revoke stops new connections through that grant at once and asks the
control plane to close every connection opened through it, browser or
dl ssh; they usually end within a few seconds. A connection whose person still holds another current grant to that enrollment is kept instead. If the control plane cannot confirm a close, Compute says so and keeps the revoked member listed with a Retry close button until those connections close or reach their current deadline. That is at most 30 minutes after a connection opened or, for a keyboard-idledl sshsession, at most 30 minutes 10 seconds after its last keystroke renewal. A renewal rechecks the grant, so none succeeds after revoke. - The grant also stops working while the member is not in the organization,
the owner can no longer use the machine, the enrollment is revoked, or the
machine moves to another namespace. Then new connections are refused and
browser terminals close, but a
dl sshsession that is already open runs until its current deadline (the same bounds; renewals are refused meanwhile). - When a person is removed from a team or leaves it, or is removed from the organization, the connections they opened through that team's grants are closed like a revoke, unless another current grant of theirs covers the enrollment. Deleting a team revokes its machine grants and closes their connections. Other people's connections are never touched. This is best effort: a connection the control plane cannot confirm closed runs until its current deadline (the same bounds as above), while its renewals and any new connection are refused at once. Membership changes do not report how many connections were closed.
- A member's tmux sessions get their own names, so the default
web-sshdoes not attach the owner's session. Their shell can still reach everything the Unix account can.
The shell runs as the enrolled Unix user. If you share your own account, the member (for a team grant, every member of the team) can read its files, attach its tmux sessions, and use any credentials stored in it on that machine, including agent logins and the machine's DreamLake daemon identity. To keep people apart, create a separate Unix account for the member, enroll that account, and share that enrollment instead.
Manage grants without Compute
The same owner-only grant is available through the API and its clients. Each call is made as the signed-in owner; none of them changes who may grant, the organization-member requirement or the one-enrollment scope.
| Surface | List | Grant | Revoke |
|---|---|---|---|
| API | GET /namespaces/:namespace/hosts/:hostId/access-grants | POST the same path with {"enrollmentId": "ENROLLMENT_ID", "grantee": "USERNAME"} (@ optional) | DELETE …/access-grants/:grantId |
| CLI (0.128.0 or later) | dl hosts access list HOST_ID | dl hosts access grant HOST_ID --enrollment ENROLLMENT_ID --user USERNAME | dl hosts access revoke HOST_ID GRANT_ID |
TypeScript, @dreamlake/dreamlake-cli/api (same release) | hosts(ns).accessGrants(hostId) | hosts(ns).grantAccess(hostId, { enrollmentId, grantee }) | hosts(ns).revokeAccess(hostId, grantId) |
| Python (0.54.0 or later) | client.hosts.access_grants(ns, host_id) | client.hosts.grant_access(ns, host_id, enrollment_id=…, grantee=…) | client.hosts.revoke_access(ns, host_id, grant_id) |
| Built-in agent | dreamlake_host_access_grants | dreamlake_host_access_grant | dreamlake_host_access_revoke |
To grant a team, send exactly one of grantee or team, where team is the
slug of a team in the namespace's organization. Revoke a team grant by its ID
like any other grant. The version minimums in the table above cover person
grants only. Team grants need the API released on 2026-11-17, CLI 0.132.0 or
later, Python 0.56.0 or later, and the current Compute.
| Surface | List people and teams | Grant a team | Revoke receipt |
|---|---|---|---|
| Compute | Brief › Access › Terminal access lists Person and Team rows | Choose Organization team, read the warning under Grant and grant | Says how many connections stay open through another grant |
| API | GET …/access-grants?grantees=all | POST with {"enrollmentId": "ENROLLMENT_ID", "team": "TEAM_SLUG"}, returns teamGrant | adds stillAuthorizedConnections |
| CLI (0.132.0 or later) | dl hosts access list HOST_ID | dl hosts access grant HOST_ID --enrollment ENROLLMENT_ID --team TEAM_SLUG | dl hosts access revoke HOST_ID GRANT_ID |
| TypeScript (same release) | hosts(ns).allAccessGrants(hostId) | hosts(ns).grantAccess(hostId, { enrollmentId, team }) | hosts(ns).revokeAccess(hostId, grantId) |
| Python (0.56.0 or later) | client.hosts.access_grants(ns, host_id) | client.hosts.grant_access(ns, host_id, enrollment_id=…, team="TEAM_SLUG") | client.hosts.revoke_access(ns, host_id, grant_id) |
| Built-in agent | dreamlake_host_access_grants (teamGrants) | dreamlake_host_access_grant with team | dreamlake_host_access_revoke |
TypeScript allAccessGrants and Python access_grants() report a server that
predates team grants as unsupported (TypeScript HostTeamGrantsUnsupportedError),
never as an empty team list.
To list team grants, the API call adds ?grantees=all and returns grants
(people), teamGrants and teams, the organization's live teams that can be
granted. Python access_grants() returns the same three lists, and the
built-in agent lists teamGrants alongside grants. Without ?grantees=all
the response lists people only, so once a machine has any team grant that
request is refused with 409 host_access_grant_client_upgrade_required
rather than showing an incomplete list. Update the client if you see it. More
than 100 grants in any listed set fails closed with 503 host_access_grant_limit.
For CLI flags and output, see Share connection access
in the CLI guide. A grant always names an exact enrollment, so choose the Unix account first;
host and enrollment IDs come from dl hosts enrollments HOST_ID or the host
details. Granting the same person or team the same enrollment again while the
grant is active returns it unchanged (201 when created, 200 when already
active). After
a revoke, the same request grants access again, so do not repeat a grant whose
outcome is unknown. List the grants first, and grant again only as a new decision.
Errors keep their
API codes: grantee_not_found, team_not_found, grantee_not_member,
grantee_is_owner, host_access_grant_org_only, enrollment_not_found,
host_not_found, and invalid_host_access_grant (including neither or both of
grantee and team).
Each grant lists id, enrollmentId, unixUser, machineId, grantee
(username, name), grantedAt and state; a team grant lists team
(slug, name) instead of grantee, plus inactive when the team was
deleted. A revoke returns
closedConnections, stillAuthorizedConnections (connections kept because
their person holds another current grant to that enrollment) and
unconfirmedConnections, plus unconfirmedUntil when
some closes were not confirmed. Those connections may stay open until that
time. The grant then stays listed with state: "revoked", pendingConnections
and pendingUntil, and repeating the revoke retries the close.
The built-in agent's mutating grant tools need Full access turned on for
the message, and act only when you name the person or team and the machine.
Before a team grant, the agent says it applies to every current direct member
and to anyone added later. They use
your own sign-in, not a service account, and the agent's generic API tools
cannot reach these routes. Machine service-account host grants
(dl service-accounts host-grants) are a different permission for a machine's
own identity. They neither share a machine with a person nor make a service
account a grantee.
Hosts in Projects
The owner can file a machine in a Project of the same namespace, by default in
its hosts folder. Filing is placement only. No Project role, Project grant or
Project membership gives anyone access to the machine: it opens no terminal or
dl ssh session and exposes no lifecycle controls, metrics or jobs. Connection
access stays the person and team grants above.
- Only the machine's exact owner can file it; anyone else is refused as if it did not exist (404). Filing also needs Project content-create permission. Only an organization owner holds the machine-use permission an owner needs, and organization owners administer every Project in the namespace, so the owner can file and unfile there; other Project writers can also unfile. Filing again returns the same entry.
- A machine is filed only in its own namespace. A cross-namespace mount is
refused with
400 host_placement_same_namespace_only. - Signed-in members of the namespace who can read the Project see the machine's name, its owner and their own relation to it (owner, grant or none). Public and anonymous readers, external Project grantees and service accounts see nothing. No enrollment, Unix account, status or credential is shown. Where a machine is filed is visible to its owner only.
- Changing the Project's grants does not involve filed machines.
- Moving the machine to another namespace unfiles it from every Project in the
same step. The move preview reports this as
projectPlacements(count, policyunfile); filing after the preview makes it stale (move_preview_conflict). - A whole Project cannot be moved while a machine is filed in it. The move is
refused with
PROJECT_RESOURCE_TRANSFER_UNSUPPORTED,UNSUPPORTED_PROJECT_CONTENTorPROJECT_STREAM_RESOURCE_UNSUPPORTED; unfile the machines first. - Unfiling, deleting the Project or moving it never deletes or changes the machine.
Filing needs the same releases as team grants: CLI 0.132.0 or later, Python
0.56.0 or later, and the current Compute. The CLI can also tag the filing with
--bindr NAME_OR_ID.
| Surface | File | Unfile |
|---|---|---|
| Compute | Brief › Access › Projects › File: choose a Project you can write to and, optionally, a Bindr. In the Project, the machine opens as a reference card. | Remove it from the Projects row |
| API | POST /namespaces/:namespace/projects/:project/resources with {"resourceType": "host", "resourceId": "HOST_ID"} | DELETE the same path and body |
| CLI (0.132.0 or later) | dl project attach PROJECT --namespace NAMESPACE --type host --resource HOST_ID | dl project detach PROJECT --namespace NAMESPACE --type host --resource HOST_ID |
| TypeScript (same release) | projects(ns).attach(project, { type: "host", resourceId: hostId }) | projects(ns).detach(project, { type: "host", resourceId: hostId }) |
| Python (0.56.0 or later) | client.projects.attach(namespace, project, "host", host_id) | client.projects.detach(namespace, project, "host", host_id) |
| Built-in agent | dreamlake_resource_project_api_write, which also needs an explicit service-account grant on that Project | the same tool |
Connection command
The terminal button in the session header (Connection command) selects the program a new session starts with:
| Option | What runs | On disconnect |
|---|---|---|
tmux (default, session web-ssh) | tmux new-session -A -s web-ssh: attaches to the session, or creates it | tmux keeps running. Reconnect to return to the same windows and processes. |
| Login shell | Your account's login shell | The shell ends. Reconnecting starts a new one. |
| Custom | One single-line command, run by your account's shell with a terminal | The session ends when the command exits. |
You can change the tmux session name, for example to keep separate train
and debug sessions. Names use 1–64 letters, digits, hyphens or underscores.
tmux is found through your login shell's PATH, so installs that your
login profile adds to PATH (such as Homebrew) work. When tmux is not installed, the session prints
tmux was not found; starting a login shell. and opens your login shell.
Choose All machines to set the default, or This machine to override it for one machine and Unix user. Use default removes a machine's override. Settings are saved in the current browser and apply the next time you connect. They never change an open session.
Compute actions that type a prepared command (such as the Cartpole demo) always use a fresh login shell. Their input never goes into a reattached tmux session.
Custom commands are limited to 4096 bytes on one line. For example,
tmux new-session -A -s web-ssh -c ~/project or htop. The gateway rejects
newlines and control characters.
Machine tabs: Brief, Agents and Jobs
The selected machine's dock keeps three fixed tabs, followed by its open terminal sessions.
- Brief: status, group, Unix user and last heartbeat, then recorded CPU, memory and storage readings, SSH and tunnel counts, and observed capabilities. A capability marked Ready (observed) is advertised by the worker. It is not an SSH handshake or a test run. IDs, exact times and limits are under Technical details.
- Agents: sessions reported by the machine's agent-session collector,
grouped as Needs input, Working, Done, Idle and Unknown, youngest first.
- Done means the newest turn completed; a thread that is merely idle is Idle.
- The age is the session's native creation time. Codex reports it, and a
resume keeps it. Claude sessions and older collectors report none and
show
—.
- Jobs: tracked runs bound to this exact machine enrollment, grouped as
Failed, Working, Done, Cancelled and Other, each with its exact state.
- The title is the uploaded program file when the run started it directly
(
script.pyorpython script.py). Otherwise it is the run's request ID, or a short job ID. - Arguments and environment are never shown.
- The age counts from creation. Jobs are read 100 at a time across the namespace, so other pages may hold more of this machine's jobs.
- The title is the uploaded program file when the run started it directly
(
Saved agent sessions
Session core interfaces
Saved session identity is the DreamLake registry ID plus the provider/native UUID
and exact enrolled host, machine and Unix-user binding. vendorSessionId is the
provider UUID; the historic codexSessionId field is retained for compatibility.
A display title, namespace, online machine or first search result is not a default
SSH target. Resolve the caller-selected host/session explicitly; refuse ambiguity.
| Interface | Core read/search contract | Boundary |
|---|---|---|
| REST | GET /namespaces/:ns/terminal-sessions, /terminal-sessions/available, /:id/metadata, and owner /sessions/attention | q, `searchIn=title |
| GUI | Session registry and /session command results | Search/panel opening does not start a provider; terminal connection is explicit |
| CLI / TypeScript | Existing sessions command and client.sessions API; companion release adds search scope and CLI aliases | Exact registry IDs and existing target resolution; no implicit host |
| Python | Companion SDK DreamLakeClient().sessions: list/search/available/get/attention/targets/target/reference | Read-only; no PTY or provider start |
| Built-in agent | dreamlake_sessions_list and dreamlake_session_get | Search scope, fresh state, durable attention, binding metadata and native memo references; caller authorization retained |
| GraphQL | No session-registry query or mutation is exposed | Use REST; unrelated GraphQL resource queries do not imply session parity |
| External MCP | No standalone session-registry MCP server is exposed by these repositories | Built-in tool plugins are not an MCP publishing endpoint; external MCP projection is deferred |
searchIn=title matches saved titles case-insensitively before pagination;
all/omission preserves broad metadata/body search under existing visibility
rules. Change filters by starting a new cursor sequence. Client releases that
send this option require the matching API deployment; an older server ignoring
an unknown query field is not title-search acceptance.
The descriptor's runState is fresh-only (45 seconds), while lastRunState and
attention preserve the last report. Stale unknown is neither stopped nor
resolved. archiveOnly, canManage, target/enrollment/machine/username and
observation timestamps describe binding and authority; they do not prove an SSH
connection is open. GET /namespaces/:ns/hosts/terminal-targets and saved-session
/:id/target resolve current authorized transport metadata without issuing an
attach ticket. PTY, forwarding and native transcript UI additions are deferred.
Terminal target catalog
GET /namespaces/:ns/hosts/terminal-targets returns the caller's ready SSH
targets: unrevoked enrollments of the caller on hosts the caller owns in the
namespace, after the usual lakeshore:use check. A revoked enrollment is never
listed or connectable. Enrollments that are not online with SSH are skipped.
| Query | Meaning |
|---|---|
limit (1–100), cursor | Page in ascending enrollment order. The response is { targets, nextCursor }; continue with cursor=<nextCursor> until it is null. A page can hold fewer than limit targets, including none, while nextCursor is set: skipped enrollments still advance the cursor, and one request examines at most 1000 records. |
archived=include | Also list enrollments of archived hosts. They are excluded by default. |
hostId, enrollmentId | Exact lookup of one host's or one enrollment's targets. It includes archived hosts and does not depend on the size of the rest of the catalog. |
Archiving a host changes catalog visibility only. It does not revoke an
enrollment or stop a machine: an archived host stays connectable by exact name,
host ID or enrollment ID. dl exec, dl ssh and dl tmux use the exact
hostId lookup.
Without limit or cursor, the response is the original single-page
{ targets } used by older clients. It returns 503 terminal_inventory_limit
when more than 100 eligible enrollments exist, rather than a truncated list;
revoked enrollments and archived hosts do not count toward that limit.
The browser terminal gateway (term.dreamlake.ai) builds its target list by
following the cursor for at most five pages (500 targets) and answers
503 terminal_inventory_limit beyond that. A ticket or saved session resolves its
one target with the exact enrollmentId lookup. Gateway responses keep the
product API's meaning: a 401 or 403 from the API is
403 terminal_access_denied; 429 and 5xx failures keep their status and
error code (for example 503 terminal_inventory_limit), or
terminal_discovery_unavailable when the API gave no code.
Discovery remains per enrolled Unix user. Use separate config, credentials,
state/cache paths and service identities for separate users. The current host
enrollment path refuses a different user/key under an existing host name with
host_identity_conflict; a schema that includes Unix user does not establish a
supported multi-user installer. No privileged cross-user discovery is provided.
/session title search
In the command palette, type /session reconnect to search saved session titles
in the selected command namespace. Results show the provider and enrolled machine.
Enter opens the highlighted saved-session panel; the separate Open session action
connects its terminal.
Shift+Enter opens its page in a new browser tab. The command namespace is distinct
from the active agent conversation's namespace. Searching launches nothing.
The command uses q=reconnect&searchIn=title on the existing session listing API.
searchIn=all or omission retains the existing broad search.
Title filtering happens before pagination and retains the existing read permissions.
It does not search transcript bodies or grant terminal access. Use Python SDK 0.45.0 or later for client.sessions.search(..., search_in="title").
CLI 0.114.0 adds dl sessions search --search-in title and the sess/session aliases.
Opening reuses the existing managed tmux path and explicit foreground fallback when tmux is unavailable. Resuming saved app history is distinct from attaching an arbitrary running process; an existing native writer remains protected. Transport retries attach only. A foreground session is nonpersistent and cannot be shared; disconnecting may end its process.
Nymph 0.1.39 registers valid Codex names/titles and Claude explicit log/index titles, using summaries only where applicable. Blank names cannot hide a usable title, and manual server-side names remain unchanged. Codex startup history is paged without the previous seven-day cutoff; new sessions keep priority. History backfill restarts with the daemon and excludes archived and child sessions. It never generates names from raw prompts or uploads transcripts. Upgrading a client does not upgrade an enrolled daemon; inspect its installed version before expecting this backfill behavior.
Provider discovery requirements: Claude discovery and observed
run states require Nymph 0.1.31+, DreamLake CLI 0.77.0+ for the new CLI
flags, and the matching provider-aware API, gateway and interface. Installing a
client or reading updated documentation does not upgrade those other components.
Compatible machine collectors discover Claude Code sessions across their configured project
roots when session discovery is enabled (see below). The registry contains session UUID, working/config directory, explicit
title, repository, provider and observed runtime metadata; conversation bodies
remain on the machine. Claude resumes with claude --resume SESSION_UUID in its saved
working directory and configuration root. Codex UUIDs and saved links remain
compatible. Both use the existing private-by-default/team-sharing controls.
Claude bookmarks are identified by their enrolled machine, Unix user, conversation
UUID and configuration root. Later working-directory observations do not create
another bookmark or move its saved launch directory. observedCwd records the
newer metadata while the saved ID, launch directory and tmux binding stay fixed.
Saving the same conversation with another launch directory returns
terminal_session_launch_cwd_conflict with its existing saved ID; open that saved
session instead. Existing Codex IDs and launch bindings keep their original rules.
Owner-selected reconciliation of a verified discovery cohort can hide private automatically named duplicates from lists while keeping their old saved IDs usable. It preserves human names, team shares and execution bindings, and copies newer observations to the retained bookmark. Explicit owner renaming or sharing restores a hidden bookmark to the list.
The agent tool (Codex or Claude Code) is separate from the model provider (OpenAI, Anthropic, DeepSeek, MiniMax, and others). Provider logos use reported metadata. An unidentified model provider remains unidentified.
Run state is an observation, not inferred from recent edits. running means a
matching process was observed; working and waiting require explicit runtime
signals. Supported Codex daemons provide these through metadata-only native
status reads, plus idle and error. stopped requires confirmed termination. Observations older than
45 seconds become unknown; opening the catalog does not start a session or
SSH-poll every row. Existing managed terminal controls still report their own
current lifecycle and dependency errors.
For Claude, discovery covers the enrolled user's default ~/.claude, inherited
CLAUDE_CONFIG_DIR and explicitly configured claude_config_dirs. Same-user
project roots and top-level UUID files are indexed; symlinks and subagent trees
are excluded. Explicit titles, summaries, directories and recognized provider
metadata may be retained. First prompts and conversation/tool content are never
used as display titles or uploaded. Saved custom configuration roots are used
again when resuming that session.
Existing Claude history is indexed gradually without an age cutoff. Each two-second tick has a bounded directory and byte budget; unchanged acknowledged metadata is cached across daemon restarts. New/changed files receive priority, and bounded reconciliation recovers missed filesystem notifications. Large histories can take time to populate; refresh never starts an unbounded host scan.
Codex native states come only from an already-running same-user app-server
control socket on a supported stable daemon version (0.162.1 or newer). Older,
custom or unavailable daemons remain unknown unless exact process evidence is
available. Discovery does not start a daemon or read transcripts as a fallback.
Known states heartbeat every 30 seconds; API observations expire after 45
seconds. unknown is an honest absence of current evidence, not a stopped claim.
Use Sessions in the main left sidebar for your saved sessions, including
while browsing an organization. In Memos, the session-library tab at the left of
the chat tab row opens a picker without moving the memo editor. Its available
list includes your sessions and sessions shared with an organization you belong to. The dedicated /:namespace/sessions
page saves a machine, its enrolled Unix user, an absolute working directory and
an agent conversation UUID. Click a saved session to open it immediately in the
browser terminal. A session link selects its saved configuration; visiting or
refreshing the link alone executes no command.
Opening a saved session adds a closable terminal tab. Use + in the terminal tab strip to choose another saved session. Choosing an already-open session focuses its existing tab. Switching tabs keeps their terminal connections open; closing a tab detaches that viewer while the agent keeps running on the host. Refreshing still only selects the saved session in the link; click to reconnect.
With focus on a session row, Up/Down moves through visible entries and scrolls the focused row into view. It does not open or start a terminal. Press Enter to activate the focused entry. Search fields and editors retain their normal caret behavior.
Use the controls beside search to choose a view of the same saved sessions:
- Machine groups sessions by their enrolled machine. Each row keeps its machine and Unix user visible.
- Recent shows one flat list, newest conversation activity first. The time comes from the exact conversation's activity metadata on its machine, from agent hooks, or from the newest message time in an uploaded conversation archive, whichever is latest. Sessions with no known activity come last; their registration or upload time is never substituted.
- Repo groups sessions by the actual Git repository resolved on their machine. A verified, sanitized remote identity can join the same repository across machines. Repositories without a safe remote stay grouped by their machine, Unix user and actual Git root. No Git repository means the directory was checked and is not in a repository; Repository unknown means the repository has not been observed or could not be resolved. The saved working directory alone never becomes a repository group.
Search filters session names, machines, working directories and observed repository information. Use × to clear the query. Choosing machine suggestions adds removable filters; multiple chosen machines match with OR. Project and Bindr suggestions navigate to those items and do not imply a session belongs to them. The Recent control is labeled, and group expansion controls show expand/collapse hints. Switching a view or searching does not connect to a machine.
Refresh reloads saved entries and their observations. Discover sessions explicitly reads the selected enrolled machine's recent Codex metadata and lets you save discovered sessions. Further pages and partial or unavailable results remain visible; an incomplete discovery is not a complete machine inventory. Repository and activity values are timestamped observations, not live process status. Opening a session does not itself refresh those observations from the machine. Compatible nymph daemons with session discovery enabled also register new local sessions automatically, as described below.
When you reopen a session in the same browser tab, its last visible screen can appear while the terminal connects. This read-only preview is marked as previous output and is replaced by live terminal output. It is not a connection status or proof that the remote process is still running. The browser keeps a bounded, temporary plain-text screen cache for the signed-in account and exact saved binding. Signing out, changing authentication or losing access clears the preview. The cache stays in the browser tab; it is not sent to DreamLake or included in saved session metadata.
For example, select the machine that already owns the conversation, enter
/home/ubuntu/workspace-3 and 01a13cbc-d4a7-7893-81cc-39696769c454. Opening runs
codex resume 01a13cbc-d4a7-7893-81cc-39696769c454 -C /home/ubuntu/workspace-3
inside a stable tmux session when tmux is available. Reopening that configuration
attaches to the running process. Closing its browser viewer detaches from it.
The machine needs its selected provider (Codex or Claude Code), the saved conversation and the usual provider login. Authentication and workspace trust prompts remain interactive. With the matching direct-runtime gateway and client, an owner opening a session on a machine without tmux uses a direct foreground terminal. No package installation is required. Direct mode may stop on disconnect; it has no detached process, managed Stop action or shared attachment. Reopening is an explicit new foreground resume, never an automatic reconnect loop. A host reboot or exiting the provider ends its process; opening again resumes the conversation in a new process. Bookmarks persist in DreamLake, while Codex history and running processes stay on the selected machine and Unix account. Changing machines does not transfer either one.
Saved sessions require matching product API and terminal gateway deployments
with Codex launch support, plus the Sessions page. CLI 0.74.1 or later uses
the same saved descriptors through the companion
dl sessions commands.
Updating the CLI does not deploy those server capabilities. Existing terminal
access and connection limits below still apply.
Share a session with a team
Sessions are private by default. The owner can change Private to
Organization and choose one organization they belong to. This shares the
session with every current member of that organization, not with an organization
team. The API keeps the legacy visibility value team for this setting
(visibility: "team" with organizationId); it still means the whole
organization. It does not publish the session to the internet or to the owner's other
organizations. Both the owner and the viewer must remain active members of the
selected organization.
Team access is interactive: teammates can see terminal output and type through the owner's running session. Share only sessions intended for that team. Memo sharing does not grant session access, and session sharing does not grant memo access. Only the owner can change sharing or use the managed start/stop controls. A teammate attaches to an existing runtime; if it is absent, the owner must open it first. Closing any terminal tab disconnects only that viewer.
Changing back to Private, losing organization membership or revoking the machine enrollment removes access. The gateway rechecks active connections and disconnects viewers whose access has been revoked. Saved descriptors are resolved on the server; the shared-session route does not accept arbitrary machines, directories or SSH commands. Interactive terminal access still acts through the owner's session.
Managed runtime
The managed lifecycle is available through the Sessions page and CLI 0.75.0 or later, with the matching deployed terminal gateway. Updating an older CLI alone does not deploy the gateway capability. Opening a saved session explicitly starts its runtime if needed and then attaches. Reconnect attaches only: it never starts a replacement process. Closing a tab still only detaches. Status is refreshed on explicit actions, not by polling every row or hidden tab.
The gateway exposes authenticated, origin-checked POST endpoints at
/namespaces/:namespace/terminal/sessions/:savedId/status, /start and /stop.
Status accepts {}. Start accepts {} (automatic selection) or
{ runtime: 'auto' | 'tmux' | 'direct' }. Automatic selection prefers tmux, including
common user-local and Homebrew installations; otherwise it prepares direct mode
for the owner. An explicit tmux request never silently switches modes. Direct
preparation checks executable, directory and provider config without starting a
process. Stop requires the exact fresh observation's
{ generation, paneId, panePid }; it is an explicit process-ending operation,
not a way to close a viewer. No endpoint accepts a command, host address or key.
Each successful response is { runtime } with:
| Field | Meaning |
|---|---|
sessionId, targetId, enrollmentId, tmuxSession | Exact saved binding; tmuxSession is not an active tmux assertion in direct mode |
observedAt | Timestamp of this machine observation |
kind, capabilities | tmux or direct, with { persistent, canStop, canShare }; all three are false for direct |
status | ready (direct preflight only), absent, running, exited, legacy, dependency_missing or unavailable |
managed, generation | Verified DreamLake ownership and runtime generation; generation is otherwise null |
pane | { id, pid, dead, exitStatus } for an observed pane, otherwise null |
clients | Number of attached tmux viewers, or null when unknown |
dependencies | { tmux, codex }; codex: null means not checked during this action |
reason, created | Optional fixed failure reason and whether start created or resumed this runtime |
New managed sessions retain an exited pane so its exit status can be observed.
Start can resume that same owned runtime with a new generation. Concurrent starts
do not duplicate Codex. Stop rechecks owner, generation, pane PID and the single
window/pane constraint atomically; a changed runtime returns 409 runtime_changed
without retrying or killing the replacement. An already-absent runtime stays absent.
Preexisting unmarked tmux sessions appear as legacy. They remain attachable but
are never adopted, restarted or stopped by managed actions. A manual pane or
window change also prevents managed stop. Missing provider prerequisites are
reported explicitly. Status and Stop never start a direct session or install
packages. Direct mode never reports a fabricated pane, generation or running
process: these fields and clients are null, managed and created are false.
No mode changes global tmux settings or stops unrelated sessions.
An attach-only terminal ticket includes top-level managedSessionId alongside
the existing exact targetId, dimensions and Codex launch. The gateway resolves
that saved descriptor again and rejects mismatched machine, user, enrollment,
directory or conversation bindings. Legacy clients without this field keep their
existing launch behavior. Metadata operations use the same pinned SSH and owner
authorization as terminals, recheck authorization after the handshake, and return
no terminal contents, environment or raw shell errors.
A direct ticket adds top-level runtime: 'direct' and is owner-only. The gateway
rechecks the exact saved binding and owner access before releasing a one-use
stdin gate to start the provider inside its SSH PTY. It allows one direct viewer
per machine/user/directory/provider/native-session/config binding; another returns
direct_session_in_use until the previous SSH channel closes. Active sessions
continue the existing bounded access-renewal checks. Tickets without a runtime
field remain tmux attach-only for compatibility, including CLI sessions reconnect.
Use an explicit open/resume to start direct mode again. Direct mode requires the
matching gateway, browser client, or CLI 0.81.0+; updating a client alone does not
update the gateway. The runtime adapter contract leaves room for additional
persistent clients; screen is not implemented yet.
The existing viewer limits count attached connections, not running tmux sessions. Managed metadata requests are separately bounded to two per account and eight per gateway. A capacity response means retry the explicit action after an active request completes; it is not a limit on saved bookmarks or detached processes.
Discovering machine sessions and registry paging
Since Nymph 0.1.34: session discovery is off unless the daemon configuration
sets [sessions] enabled = true. Configurations that omit the key stop
discovering sessions after upgrading. Nymph does not rewrite configuration
files, and an explicit enabled = true keeps discovery on. See
host testing for the related job output setting.
With nymph 0.1.29 or later, session discovery enabled and the matching product API on an enrolled machine, new local Codex sessions are registered automatically from the local SQLite metadata index. Nymph checks local index/WAL metadata and sends bounded incremental batches. With multiple roots, one root is visited per two-second tick; a complete pass takes at least two seconds per root, plus I/O and retries. Newly discovered session titles update as Codex fills them in. Custom names, older saved names and sharing choices stay unchanged. It never uploads conversation or terminal contents. Missing or locked indexes and upload failures leave existing saved entries intact; retries are bounded. The visible session picker refreshes the saved registry every five seconds without scanning remote machines; refresh stops while hidden. Visibility follows these intervals and network latency, not a guaranteed subsecond event.
Use nymph 0.1.30 or later for discovery diagnostics. Its service logs show
whether discovery started or was disabled. enrollment_binding_unconfirmed
means the daemon could not confirm the enrollment from the signed handshake;
it is not proof that the local session index is empty. Retry diagnostics show
only a reason, optional HTTP status and retry delay, at most once per minute,
plus a corresponding recovery event. They exclude session names, paths,
credentials and conversation contents. Upload backoff can reach five minutes
after repeated API failures; a recovered API does not reset an already-running
daemon's retry timer.
Multiple provider roots and exact resume
Nymph 0.1.40 adds include_default_roots (default true) and codex_homes.
With defaults enabled, discovery unions ~/.codex, inherited CODEX_HOME, the
legacy explicit codex_home, and codex_homes. Claude similarly unions
~/.claude, inherited CLAUDE_CONFIG_DIR and claude_config_dirs. A custom
environment root no longer replaces the default root.
Set include_default_roots = false to collect only explicit roots. The legacy
codex_home remains an explicit root. Empty explicit lists with defaults disabled
collect no roots. Paths are canonicalized, deduplicated and restricted to
directories owned by the enrolled Unix user. Only the first 32 explicit entries
per provider are probed; default roots and the singular legacy Codex root retain
their slots. Missing roots are checked again periodically. Configuration changes
require the normal daemon restart; discovery does not create users, inspect
other users' home directories or change their services.
Each Codex root has its own cursor and retry state, while roots share the existing
per-tick upload/read budgets. Fresh metadata is checked during history backfill.
Replacing an index at the same pathname restarts bounded history discovery.
Removing a Claude root excludes its cached observations. A sustained backlog is
reported through rate-limited service diagnostics; large histories and many roots
can take longer to appear. Native status probes also rotate across roots, so a
stale observation can become unknown before the next successful probe.
The matching API and SSH gateway retain an optional codexHome in the saved
session and Codex launch descriptor. It is an absolute canonical remote path,
limited to 4096 UTF-8 bytes. It is part of registry, runtime and tmux identity:
the same conversation UUID in two roots remains two distinct bindings. Launches
set the exact saved CODEX_HOME, regardless of the interactive shell's default.
CLI and TypeScript SDK 0.115.0 or later preserve that value, as does the
matching browser release. Python SDK 0.45.0 keeps server-provided root fields in
its read-only descriptor responses. Substituting or omitting the root of a bound
session is rejected before launch. Root-aware clients require
the matching API/gateway rollout; upgrading Nymph alone is insufficient.
Existing descriptors with an absent or null top-level root keep their legacy
behavior. They are not silently adopted into a new root binding; legacy and
root-bound entries can coexist. UUID-only registration cannot select a root
implicitly. The metadata update binding must include the exact codexHome for
a bound Codex session. The API checks equality; the remote execution path checks
that the directory still exists, is canonical and belongs to the enrolled user.
Local responsiveness measurements use real collectors, the actual signed drain/poll loop, a separate control-request comparison and an authenticated OpenSSH stream with synthetic same-user data. They are separate from unit budget tests and do not establish production heartbeat, WebSocket relay, battery or fleet-wide latency guarantees. Reproduction steps and workload limits are documented in the Nymph measurement harness.
A session created in a normal local terminal cannot be moved into a browser terminal. Opening its saved entry uses DreamLake's supported terminal runtime; it does not capture or take over the original local TTY.
With the Codex native-writer guard deployed, a positive observation of a writable
handle to the exact conversation's local rollout file blocks creating or
restarting a managed process, or launching a new direct process, with
native_session_active. Continue in the existing Codex chat rather than retrying
automatically or terminating it to clear the error. An already-running managed
tmux session remains attachable without starting another writer.
This check reads file/process metadata, not conversation contents, and does not stop the observed process. It applies to Codex only. Missing tools, unsupported layouts, timeouts and inconclusive observations retain the previous behavior; the absence of an error does not prove there is no other writer. The guard does not provide an exclusive-writer lock or adopt native app sessions. CLI 0.84.1+ preserves the error and recovery guidance; older clients may show only HTTP 409. Client updates alone do not deploy the gateway guard.
Older daemons still require explicit discovery and saving. That discovery reads the enrolled user's
default ~/.codex SQLite index for recent, unarchived root conversations from
the last seven days. It excludes spawned agents and checks that the referenced
rollout is readable and belongs to that user's sessions directory. It never
reads rollout contents or starts Codex. Older conversations can still be saved
explicitly with their UUID and working directory.
POST /namespaces/:namespace/terminal/discovery on the terminal gateway accepts
{ targetId, enrollmentId, cursor? }. It returns { discovery } with the exact
target and enrollment, observedAt, status, candidates, nextCursor,
lookbackDays: 7, scope: "default_codex_home", cached, skippedCount,
metadataOmittedCount and partial. Each candidate has codexSessionId, cwd, name
and lastActivityAt, plus an optional repository/activity metadata observation.
Names prefer the index's saved name, then its title. Only sanitized Git remote
identities leave the machine. skippedCount reports unusable directory/rollout
references on that page. metadataOmittedCount reports candidates whose complete
Git observation could not fit the bounded read; their activity is still returned,
but the client must not pretend a complete observation was saved. partial is
true for non-OK status, another page, skipped candidates or omitted observations.
The gateway reads at most 25 index rows per page, caps output at 64 KiB and
allows at most two concurrent host reads. It uses a 15-second observation cache;
each response still rechecks the current owner and exact target binding. Cursors
are signed, bound to that owner/target and snapshot, and expire after ten minutes.
python_missing, index_missing, unsupported_schema and unavailable mean
discovery could not establish a complete inventory; they do not mean there are
zero sessions. No dependency is installed or repaired automatically.
Clients save selected candidates through the existing product API. Optional
nameIfNew supplies a newly imported bookmark's title while preserving an
existing user-chosen name. Metadata enrichment uses the guarded PATCH below.
Both actions save metadata only. Partial host failures must stay visible rather
than being reported as a successful complete scan.
GET /namespaces/:namespace/terminal-sessions now returns one page with
sessions, hasMore and nextCursor. pageSize defaults to 100 and may be
1–100; pass cursor for the next page. This is a response page size, not a
bookmark count limit. sort=created is the default; sort=recent orders by
lastActivityAt, newest first, and leaves missing activity at the bottom.
lastActivityAt can be known while activityStatus and metadataObservedAt
are null: those two describe a host metadata observation, and activity can
also come from hooks or an uploaded archive (see
Optional conversation archives). q searches saved
metadata; repeated machineId values restrict machines. Clients that also
match their displayed machine names can pass repeated matchMachineId values
alongside q. Change the search or sort by starting a new cursor sequence.
GET /namespaces/:namespace/sessions/attention returns the personal namespace
owner's sidebar summary: needsInput, error, and the newest 20 sessions
with id, name, provider, attention, and since. Counts include all
matching sessions, not just those 20 previews. Authentication is required;
other users and organization namespaces are denied. The legacy
/namespaces/:namespace/terminal-sessions/attention path is an alias.
Attention comes from the last reported runState: waiting means
needs_input, and error means error. It survives the 45-second live-state
freshness window until a new state is reported; archived and superseded sessions
are excluded. Descriptors expose the same attention and durable lastRunState
alongside the existing fresh-only runState. Reading the summary opens no
machine or terminal connection.
Observed repository and activity metadata
Saved descriptors can also retain an observation of the actual Git root and the conversation's last activity on its enrolled machine. A working directory is not evidence of a Git repository, and bookmark creation is not conversation activity. Unobserved or unavailable values remain explicitly unknown.
The owner-only PATCH /namespaces/:namespace/terminal-sessions/:id/metadata
accepts a complete observation. It preserves the bookmark name, execution binding
and running terminal. Supply binding with the observed descriptor's exact
enrollmentId, machineId, username, cwd and codexSessionId, plus:
| Field | Meaning |
|---|---|
repositoryStatus | git, not_repository or unavailable |
repositoryRoot | Actual absolute Git root, or null unless status is git |
repositoryIdentity | Sanitized git:host[:port]/path identity, or null |
activityStatus | available or unavailable |
lastActivityAt | Exact conversation activity in UTC ISO format, or null when unavailable |
metadataObservedAt | UTC ISO timestamp of the metadata observation |
Dates use millisecond precision, for example 2026-10-17T10:00:00.000Z.
Repository identities contain no scheme, username, credentials, query or fragment;
the lowercase host and case-preserved path omit the final .git suffix. Path
segments use letters, digits, dots, underscores and hyphens. For a Git repository
without a safe remote identity, send null: the API derives a local: identity
scoped to the enrollment, machine, Unix user and actual Git root. Matching remote
identities can group repositories across machines; local identities cannot.
The API rechecks enrollment ownership and the exact saved binding. A changed
binding or an observation no newer than the stored one returns 409; do not
retry an old observation with a fabricated newer timestamp. Explicit unavailable
observations clear the corresponding old values. These are caller-observed
metadata, not a server-side filesystem probe or ongoing synchronization. Never
upload raw Git remotes, terminal output, conversation content or credentials.
This endpoint requires the matching metadata-capable API deployment; older
deployments do not accept it. Existing bookmarks return null metadata until
observed, and saving/opening a bookmark does not automatically inspect a host.
Limits
- At most 12 terminal connections per account across browser windows and CLI SSH, and 48 per gateway.
- Settings → Compute → Concurrent web terminals defaults to 12 and can lower the limit for this account in this browser. The frontend counts connecting and connected terminals across panels on the page; lowering the setting preserves existing connections.
- When a limit is reached, disconnect an unused terminal and retry. Disconnect and quota reasons remain visible in the terminal banner.
- A session closes after five minutes without input, output or resize, and always after thirty minutes. tmux and its processes keep running after either limit, and reconnecting returns to them.
- Access is checked again every few seconds. Revoking the enrollment or signing out closes the session.
- Terminal output goes only to your browser. DreamLake does not record, log or index it. Saved Codex sessions can retain the temporary browser-tab preview described above; live terminal scrollback is limited to 1000 lines.
Troubleshooting
- No terminal-enabled machines: confirm the daemon is online with SSH
enabled (
[ssh] enabled=true) and that the enrollment belongs to your personal namespace. - Connection takes long or times out: the gateway waits up to 30 seconds for the machine's daemon to start its SSH backend. Retry once. If it keeps failing, check the daemon on the machine.
- Control plane busy: when the Lakeshore control plane's SSH queue refuses
the request before granting anything, the session request answers HTTP 503
controlplane_busywithRetry-After(seconds), and the gateway retries on its own with a new key, within the same 30-second setup. If it still fails, try again later. HTTP 502controlplane_unavailablemeans the outcome is unknown; it is never retried automatically. - Reconnect shows a different shell: the connection command is set to Login shell or Custom. Switch to tmux to keep work across disconnects.
- Detached processes: anything you start outside tmux can stop when the session ends. Use tmux, or a tracked job, for long-running work.
Resource affiliations
Saved sessions can be linked to memos and every artifact kind. The relation is many-to-many metadata; it neither starts a terminal nor grants access. Current resource and session permissions are checked on every request. Resource moves keep the internal identity and require the new current namespace; reusable artifact names do not inherit another catalog record's links. Exact old saved-session IDs remain usable after listing-only Claude duplicate reconciliation.
GET /namespaces/NS/resources/TYPE/ID/sessionslists readable linked sessions.PUT /namespaces/NS/resources/TYPE/ID/sessions/SAVED_IDlinks one exact session.DELETEon the same path unlinks it. Both writes require{ "sessionNamespaceSlug": "SESSION_OWNER_NAMESPACE" }.GET /namespaces/SESSION_NS/terminal-sessions/SAVED_ID/resourceslists readable resources withtype,id,namespaceSlug,title, andcanManageLinks.
TYPE is note or artifact; ID is a memo ID or an artifact's logical name.
Writes return { "linked": true, "sessionId": "SAVED_ID" } (false for unlink)
and are idempotent. Both list directions return hasMore and nextCursor, accept
pageSize from 1 to 50 (default 25), and perform bounded indexed reads. The linked
session list accepts q for name, machine, directory and native UUID. Filtering
uses each bounded link page; an empty page with hasMore can have later matches.
No total-count or automatic all-catalog scan runs with the application.
Search and read uploaded Claude conversations
Production verified 2026-10-19: API 4cf8a2e3, UI 4243b42. Owner-scoped
body keyword search, click-to-read history, deep-link reload and narrow-screen
wrapping were verified in the authenticated website. Existing upload limits and
reader authority are unchanged; Nymph and the backup collector are unchanged.
In Sessions, choose Claude, then search by a keyword in the session title, metadata, or uploaded user/assistant messages in conversations you own. Shared conversations remain searchable by metadata and readable under their existing permissions; their body text never influences another viewer’s search pagination. Matching happens in the database before the existing bounded pagination and keeps the selected provider and machine filters. A session with no uploaded conversation can match metadata only. Tool and system payloads are excluded from the body-search text. Search text is refreshed atomically with each explicit conversation upload and cleared when it is deleted; older uploads must be re-uploaded once to populate it. A verified empty snapshot contains zero messages and is displayed as empty, not as a missing upload. Catalog responses never include conversation text. No new search service or index is required.
In the standalone Sessions page, clicking a saved Claude session opens its Conversation view without starting or attaching to a terminal. Choose Terminal explicitly to use the existing terminal workflow. A missing archive is shown as missing, not an empty conversation. Reading works independently of host liveness; it does not fetch local transcripts or trigger an upload. The S3 backup collector remains separate: a backup must be explicitly imported/uploaded into the conversation API to be readable here.
Optional conversation archives
The Memo activity sidebar lists contributing saved sessions before collapsed related resources. Affiliations can come from successful CLI content writes or explicit links; a link is not an independently verified authorship claim. Reading a memo or mentioning another memo does not invent a contributing session. Older memos can have no recorded session history.
CLI 0.79.0+ sessions upload-conversation accepts an explicitly selected native
Codex/Claude export; DREAMLAKE_CONVERSATION_FILE opts successful Memo and artifact
writes into snapshots. Without that setting, uploads carry session metadata only.
See CLI session archives.
An explicit conversation upload stores readable text separately from the saved terminal descriptor. The archive uses the session's existing reader permissions; sharing a memo never grants access to the archive or terminal. Only the session owner can replace or delete an archive. Uploads never start a process. Archived history remains readable when the host is offline or enrollment is revoked, provided the saved session and account permissions remain valid.
The API at /namespaces/NS/terminal-sessions/ID/conversation supports:
GET: currentconversation,revision, and exactproviderandnativeSessionId. A missing archive returns null content and revision.?metadata=trueomits stored text and returns only its identity/revision.PUT:{ conversation, expectedRevision }. Supply the last read revision (null for first upload). Concurrent replacement returns 409; identical retries are idempotent. An archive cannot substitute a different provider or native ID.DELETE: remove only the uploaded archive, preserving the session and native conversation on its host.
Conversation version 1 contains provider, nativeSessionId, and messages
with role (user, assistant, tool, or system), text, and optional ISO
timestamp. Maximum 20,000 messages and 8 MiB of JSON; oversized uploads fail
without truncation. Catalog responses never include these bytes. The archive is
a snapshot, not live transcript synchronization or a portable provider resume
file. It does not restore missing native state on another host.
A successful PUT also records the archive's newest message timestamp as the
session's lastActivityAt, so the session takes its place in sort=recent. It
only moves activity forward: an older archive never replaces newer activity
observed on the host or reported by hooks. Messages without a timestamp, before
2000, or more than five minutes ahead of the server clock are ignored. An
archive with none left, including an empty one, does not supply or advance
activity: the session keeps any activity it already has, and a previously
unknown session remains unknown. The upload time itself is never used, and
activityStatus and metadataObservedAt are not changed. Re-sending identical
content records the activity for an archive uploaded before this was recorded.
The archive's messages and revision stay the same; its updatedAt can
change.
Abstract and Full sessions
Session lists and the session view label each session by whether a readable conversation archive exists:
| Label | Meaning |
|---|---|
| Abstract | DreamLake holds only the session's metadata (name, provider, binding, observed activity). No conversation archive was uploaded. |
| Full session | A conversation archive exists and can be read, including a verified empty one. |
The label depends only on the archive. It is independent of whether a terminal
is bound (archiveOnly), of run state, of provider and of whether search text
was indexed. A Full session holds the snapshot from its last upload; it is not
kept in sync with the machine and does not make the session runnable. Built-in
DreamLake agent sessions are labelled by the same rule.
Session list routes (GET /namespaces/:namespace/terminal-sessions,
/terminal-sessions/available and a resource's linked sessions) and the
single-session reads (/:id/metadata and /:id) return
hasConversationArchive: true | false. List routes look the archives up in one
read of their ids for the sessions already shown to the reader; no archive text
is read or returned. Responses from older servers omit the field, and clients
show no label rather than Abstract.
Clicking a saved Codex or Claude row in a Memo's Contributing sessions opens its terminal in the panel to the right. It does not open the archive first or require an upload. Current host, enrollment and session execution authorization still apply, using the supported persistent or direct terminal runtime. A metadata-only registration without a verified host binding shows connection guidance, its native session ID and working directory, and Open Sessions for the owner. Connect the original machine and discover or register that exact session, then use Check connection again to reload its saved descriptor. Checking never selects a host or uploads conversation content. Read access to a public session does not grant terminal execution.
Explicit conversation history remains readable as inert text, independently of the terminal and host liveness. Missing archives do not disable terminal opening or basic memo editing. Session permissions remain separate from memo permissions.
SSH capacity and usage
Release requirements: usage reporting requires the coordinated November 4, 2026 control-plane, API, terminal-gateway and UI releases. Local capacity configuration requires Nymph 0.1.35 or later; numeric CLI quota errors require CLI 0.103.1 or later. Older deployments may still enforce 2 SSH sessions and 8 tunnels per worker, 32 combined per namespace, and local combined capacity of 10. Installing a skill or reading this page does not upgrade existing daemons. Check the actual usage response and installed daemon version; publishing a release does not restart enrolled hosts.
The new defaults are:
| Scope | Default limit | What consumes it |
|---|---|---|
| Enrolled worker | 20 SSH sessions | Browser terminals, CLI SSH and exec connections through DreamLake |
| Enrolled worker | 8 forwarding tunnels | DreamLake forwarding connections; separate from the SSH-session quota |
| Control-plane namespace | 128 combined sessions | All SSH sessions and tunnels across every worker and user in that namespace |
| Nymph process | 28 combined sessions | Local SSH and tunnel tasks being served by that daemon |
The namespace total is a shared concurrent ceiling, not a per-user allowance, daily budget or lifetime count. Five workers with 20 SSH sessions each use 100 namespace slots, leaving 28 for other SSH sessions or tunnels. Multiple DreamLake workspaces can reference the same control-plane namespace; those connections share its ceiling. Multiple enrolled workers on one physical machine each have a worker quota; physical-machine capacity remains shared.
Pending, ready and active sessions reserve slots. Closed or expired sessions and pending/ready attempts past their connect deadline do not count toward new admission. A saved agent bookmark does not reserve a slot. A detached tmux session does not consume a DreamLake SSH slot after its viewer connection closes, although its processes still consume machine resources. Normal OpenSSH connections outside DreamLake do not consume this counter. OpenSSH's MaxSessions is a different setting for channels within a connection.
Read usage
Open a host's details and select its enrolled Unix user. SSH sessions, Forwarding tunnels, and Namespace total show used of limit in use. Counts refresh every five seconds while the panel is mounted and on Refresh. They are observations, not reservations: another connection can claim the remaining slot before Connect is clicked. Offline, unauthorized, incompatible or unverified targets show unavailable rather than a fabricated zero. The panel does not create sessions while counting.
The authenticated API read is:
It requires namespace execution access and exact private host/enrollment ownership. The control-plane read is GET /v1/namespaces/:ns/ssh-usage/:workerId; it requires an admin or an active namespace token with an exact worker SSH grant. Session-delegated credentials cannot use this inventory endpoint. Responses contain counts only, with Cache-Control: private, no-store:
The namespace total is aggregate capacity, not disclosure of other hosts, owners or session identities. It may include users other than the current viewer. Admission calculates usage inside its existing fenced transaction; the read endpoint is a non-reserving snapshot and can change between its count queries.
Configure capacity
The control-plane operator sets these environment variables on every instance serving the same database:
| Variable | Default | Valid values | Applies to |
|---|---|---|---|
LAKESHORE_SSH_MAX_SESSIONS_PER_WORKER | 20 | Integer 1–4096 | Ordinary SSH sessions per worker |
LAKESHORE_SSH_MAX_TUNNELS_PER_WORKER | 8 | Integer 1–32 | Forwarding tunnels per worker |
LAKESHORE_SSH_MAX_SESSIONS_PER_NAMESPACE | 128 | Integer 1–4096 | Combined sessions per namespace |
The tunnel maximum matches the current bounded inventory API. Raising it beyond 32 requires a separate inventory/pagination change. An unset value uses its default. Empty strings, zero, negative values, fractions, whitespace, exponential notation and values above the bound fail startup. Zero does not mean unlimited or disable SSH. These are process-wide settings applied independently to each namespace/worker; they are not per-namespace overrides. No user-facing API changes them. Restart/redeploy the control plane through its existing service manager after changing them. Do not mix instances with different values: the shared transaction fence prevents races but does not reconcile different policies.
On the enrolled machine, the owner configures Nymph's existing TOML file:
Use the existing private state directory and SSH host key for an enrolled service; the example path is not a migration instruction.
Nymph [ssh] option | Default | Meaning |
|---|---|---|
enabled | false | Enables the SSH backend only when local command_execution also permits it. |
state_dir | Empty | Required private directory for enabled SSH; retains its host key and boot binding. |
sshd | /usr/sbin/sshd | Local OpenSSH server executable used by the backend. |
max_duration_s | 3600 | Total session lifetime in seconds, measured from creation. 0 disables the total limit; otherwise 60–14400. Keyboard activity never extends it. Nymph 0.1.42+. |
idle_timeout_s | 1800 | Keyboard inactivity limit, 60–14400 seconds. The CLI may request a shorter limit. Protocol grace is internal; setting both limits to 1800 is valid. Nymph 0.1.42+. |
renewable_expiry | true | Lets the control plane move an open keyboard-idle session's deadline forward through the daemon lease. false keeps every deadline fixed at open, and keyboard-idle sessions are refused for this host. Nymph 0.1.41+. |
max_sessions | 28 | Combined local SSH/tunnel task capacity, integer 1–4096; validated at configuration load. |
Keyboard-idle sessions
dl ssh and dl tmux request a 30-minute keyboard inactivity limit, shortened by the host’s idle_timeout_s policy. With Nymph 0.1.42+, max_duration_s independently caps total lifetime. Set max_duration_s = 0 and idle_timeout_s = 1800 to keep active sessions open and close them after 30 minutes idle. The CLI observes keystrokes and pastes before encryption and reports them, at most about once a minute, to the DreamLake backend. The backend rechecks the user's current access to that exact enrollment, exactly as for a new session, and asks the control plane to renew. The control plane accepts a renewal only from the backend that issued the session, for the same worker binding and with that session's credential, and advances the inactivity deadline, with an internal ten-second grace for clean client shutdown. The total lifetime limit is never extended by this grace. The session credential's expiry moves with it in place. Nymph applies the new deadline from its next 15-second lease reply. The relay connection, sshd and the remote shell are not touched by a renewal.
Remote output, mouse and focus reports, terminal replies, window resizes and SSH keepalives never renew a session. A host needs Nymph that advertises renewable expiry. Nymph 0.1.42+ advertises the two independent timeout policies; no extra margin is required in configuration. Older daemons retain their renewal-window behavior. A daemon or control plane without support falls back to a fixed session, with a CLI notice. Revoking the user's access, the grant, the enrollment or the issuing connection stops renewals; revoking a grant or connection also closes the session at once. A session whose person still holds another current grant to that enrollment is kept and renews under that grant.
There is no new Nymph environment-variable or CLI-flag override for max_sessions. It belongs in the config selected by --config or the existing service configuration. Omitted options use defaults; unknown options are rejected. Nymph reads this file at startup, not on every poll. nymph access --config /absolute/path/to/udf-daemon.toml inspects the file plus local policy without starting a worker; its settings.sshEnabled, sshMaxSessions, sshMaxDurationSeconds, sshIdleTimeoutSeconds and (newer daemons) sshRenewableExpiry describe that inspected startup configuration, not proof that an already-running daemon has reloaded it.
Keep local combined capacity at least the intended simultaneous SSH plus tunnel count for the worker (28 for the defaults). A deliberately lower local capacity still applies: the control plane does not currently advertise or negotiate this local setting, so its counters are control-plane admission limits, not guaranteed local slots. OS process/file-descriptor limits, memory and OpenSSH remain additional constraints. Do not increase those blindly or use quota changes to broaden grants.
Roll out or reduce limits
- Record deployed versions, current effective process settings, host enrollment and existing state directory. Inspect usage and active work before restarts.
- Deploy the configurable control plane initially with explicit legacy limits when older daemons remain. Pending responses stay bounded to ten sessions for compatibility; subsequent polls deliver additional sessions.
- Upgrade/configure each target Nymph with the required local capacity, validate its config, and restart through its existing supervisor in an agreed interruption window. A daemon restart can disconnect SSH viewers; capacity configuration is not a live update.
- Apply the selected limits consistently across control-plane instances, then deploy matching API/gateway and clients. Verify usage, a successful connection/disconnection, a limit refusal with counts, and recovery after a slot is released.
- Publish docs, refresh the public skill references, release the skill and update the CLI pin through their normal workflows. Track each publication separately.
Reducing a control-plane limit below current use does not terminate existing sessions. Usage can legitimately read used > limit; new admissions remain blocked until enough sessions close/expire. Restarting Nymph is different and can interrupt its sessions. Record rollback values and deployment versions; restoring an older Nymph requires removing unsupported new TOML fields first. Do not delete SSH state/host keys to roll back a capacity change.
Limit errors and recovery
HTTP 429 with session_limit means an admission quota was reached. The new response carries validated numeric usage fields; clients describe host SSH/tunnel usage and namespace total. Older servers without counts produce a generic limit message. Unknown or malformed upstream fields are not shown as numbers, and arbitrary upstream messages/credentials are never echoed.
Close only a connection/tunnel you intend to release, then refresh and retry. Closing an SSH viewer need not stop the underlying agent or tmux workload. A full namespace can block a host with free local slots. If counts appear stale, allow cleanup/connection deadlines to pass and inspect the lifecycle; do not delete session records to bypass the counter. 503 ssh_busy / controlplane_busy indicates the bounded write queue, not the concurrent-session quota. daemon_unavailable, terminal_not_ready and permission errors require their own readiness/authorization checks.
For the authority model and proposed live-configuration boundary, see Nymph permissions and commands.