<!-- source: https://docs.dreamlake.ai/lakeshore/hosts/browser-terminal @ 0.1.192 b2f973b1 -->
# 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](#share-a-machine-with-a-teammate).
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](#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](/lakeshore/hosts/enroll.md) 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](https://cli.dreamlake.ai/host-enrollment#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`.

| 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](/lakeshore/hosts/native-cartpole-demo.md)) 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.

| Interface | Core read/search contract | Boundary |
| --- | --- | --- |
| REST | `GET /namespaces/:ns/terminal-sessions`, `/terminal-sessions/available`, `/:id/metadata`, and owner `/sessions/attention` | `q`, `searchIn=title|all`, provider/machine filters and bounded cursors; read authority unchanged |
| 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](https://cli.dreamlake.ai/sessions).
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](https://github.com/dreamlake-ai/nymph/releases/tag/v0.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](/lakeshore/hosts/testing.md) 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](https://github.com/dreamlake-ai/nymph/blob/main/docs/session-responsiveness.md).

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](#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_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](https://cli.dreamlake.ai/sessions/#optional-conversation-upload-0790).

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:

| 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:

```text
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**:

| 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 |

```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]` 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

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](/lakeshore/hosts/nymph-permissions.md).
