DreamLake

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:

  1. Open Compute in the organization namespace and select the machine.
  2. 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-idle dl ssh session, 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 ssh session 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-ssh does 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.

SurfaceListGrantRevoke
APIGET /namespaces/:namespace/hosts/:hostId/access-grantsPOST 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_IDdl hosts access grant HOST_ID --enrollment ENROLLMENT_ID --user USERNAMEdl 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 agentdreamlake_host_access_grantsdreamlake_host_access_grantdreamlake_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.

SurfaceList people and teamsGrant a teamRevoke receipt
ComputeBrief › Access › Terminal access lists Person and Team rowsChoose Organization team, read the warning under Grant and grantSays how many connections stay open through another grant
APIGET …/access-grants?grantees=allPOST with {"enrollmentId": "ENROLLMENT_ID", "team": "TEAM_SLUG"}, returns teamGrantadds stillAuthorizedConnections
CLI (0.132.0 or later)dl hosts access list HOST_IDdl hosts access grant HOST_ID --enrollment ENROLLMENT_ID --team TEAM_SLUGdl 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 agentdreamlake_host_access_grants (teamGrants)dreamlake_host_access_grant with teamdreamlake_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, policy unfile); 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_CONTENT or PROJECT_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.

SurfaceFileUnfile
ComputeBrief › 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
APIPOST /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_IDdl 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 agentdreamlake_resource_project_api_write, which also needs an explicit service-account grant on that Projectthe same tool

Connection command

The terminal button in the session header (Connection command) selects the program a new session starts with:

OptionWhat runsOn disconnect
tmux (default, session web-ssh)tmux new-session -A -s web-ssh: attaches to the session, or creates ittmux keeps running. Reconnect to return to the same windows and processes.
Login shellYour account's login shellThe shell ends. Reconnecting starts a new one.
CustomOne single-line command, run by your account's shell with a terminalThe 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.py or python 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.

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.

InterfaceCore read/search contractBoundary
RESTGET /namespaces/:ns/terminal-sessions, /terminal-sessions/available, /:id/metadata, and owner /sessions/attentionq, `searchIn=title
GUISession registry and /session command resultsSearch/panel opening does not start a provider; terminal connection is explicit
CLI / TypeScriptExisting sessions command and client.sessions API; companion release adds search scope and CLI aliasesExact registry IDs and existing target resolution; no implicit host
PythonCompanion SDK DreamLakeClient().sessions: list/search/available/get/attention/targets/target/referenceRead-only; no PTY or provider start
Built-in agentdreamlake_sessions_list and dreamlake_session_getSearch scope, fresh state, durable attention, binding metadata and native memo references; caller authorization retained
GraphQLNo session-registry query or mutation is exposedUse REST; unrelated GraphQL resource queries do not imply session parity
External MCPNo standalone session-registry MCP server is exposed by these repositoriesBuilt-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.

QueryMeaning
limit (1–100), cursorPage 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=includeAlso list enrollments of archived hosts. They are excluded by default.
hostId, enrollmentIdExact 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.

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:

FieldMeaning
sessionId, targetId, enrollmentId, tmuxSessionExact saved binding; tmuxSession is not an active tmux assertion in direct mode
observedAtTimestamp of this machine observation
kind, capabilitiestmux or direct, with { persistent, canStop, canShare }; all three are false for direct
statusready (direct preflight only), absent, running, exited, legacy, dependency_missing or unavailable
managed, generationVerified DreamLake ownership and runtime generation; generation is otherwise null
pane{ id, pid, dead, exitStatus } for an observed pane, otherwise null
clientsNumber of attached tmux viewers, or null when unknown
dependencies{ tmux, codex }; codex: null means not checked during this action
reason, createdOptional 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.

toml
[sessions]
enabled = true
include_default_roots = true
codex_homes = ["/home/alice/.codex-work", "/home/alice/.codex-personal"]
claude_config_dirs = ["/home/alice/.claude-work"]

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:

FieldMeaning
repositoryStatusgit, not_repository or unavailable
repositoryRootActual absolute Git root, or null unless status is git
repositoryIdentitySanitized git:host[:port]/path identity, or null
activityStatusavailable or unavailable
lastActivityAtExact conversation activity in UTC ISO format, or null when unavailable
metadataObservedAtUTC 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_busy with Retry-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 502 controlplane_unavailable means 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/sessions lists readable linked sessions.
  • PUT /namespaces/NS/resources/TYPE/ID/sessions/SAVED_ID links one exact session.
  • DELETE on the same path unlinks it. Both writes require { "sessionNamespaceSlug": "SESSION_OWNER_NAMESPACE" }.
  • GET /namespaces/SESSION_NS/terminal-sessions/SAVED_ID/resources lists readable resources with type, id, namespaceSlug, title, and canManageLinks.

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: current conversation, revision, and exact provider and nativeSessionId. A missing archive returns null content and revision. ?metadata=true omits 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:

LabelMeaning
AbstractDreamLake holds only the session's metadata (name, provider, binding, observed activity). No conversation archive was uploaded.
Full sessionA 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:

ScopeDefault limitWhat consumes it
Enrolled worker20 SSH sessionsBrowser terminals, CLI SSH and exec connections through DreamLake
Enrolled worker8 forwarding tunnelsDreamLake forwarding connections; separate from the SSH-session quota
Control-plane namespace128 combined sessionsAll SSH sessions and tunnels across every worker and user in that namespace
Nymph process28 combined sessionsLocal 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:

GET /namespaces/:slug/hosts/:hostId/enrollments/:enrollmentId/ssh-usage

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:

json
{"sessions":{"used":3,"limit":20},"tunnels":{"used":1,"limit":8},"namespace":{"used":17,"limit":128}}

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:

VariableDefaultValid valuesApplies to
LAKESHORE_SSH_MAX_SESSIONS_PER_WORKER20Integer 1–4096Ordinary SSH sessions per worker
LAKESHORE_SSH_MAX_TUNNELS_PER_WORKER8Integer 1–32Forwarding tunnels per worker
LAKESHORE_SSH_MAX_SESSIONS_PER_NAMESPACE128Integer 1–4096Combined sessions per namespace
sh
export LAKESHORE_SSH_MAX_SESSIONS_PER_WORKER=20
export LAKESHORE_SSH_MAX_TUNNELS_PER_WORKER=8
export LAKESHORE_SSH_MAX_SESSIONS_PER_NAMESPACE=128

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:

toml
[ssh]
enabled = true
state_dir = "/home/worker/.local/state/dreamlake/ssh"
sshd = "/usr/sbin/sshd"
max_duration_s = 3600
idle_timeout_s = 1800
max_sessions = 28

Use the existing private state directory and SSH host key for an enrolled service; the example path is not a migration instruction.

Nymph [ssh] optionDefaultMeaning
enabledfalseEnables the SSH backend only when local command_execution also permits it.
state_dirEmptyRequired private directory for enabled SSH; retains its host key and boot binding.
sshd/usr/sbin/sshdLocal OpenSSH server executable used by the backend.
max_duration_s3600Total 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_s1800Keyboard 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_expirytrueLets 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_sessions28Combined 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

  1. Record deployed versions, current effective process settings, host enrollment and existing state directory. Inspect usage and active work before restarts.
  2. 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.
  3. 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.
  4. 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.
  5. 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.