Shared sessions
An owner can share an existing session with authenticated controller users or create a browser link that anyone holding it can open without a server account. View only shares live terminal output and bounded scrollback; Control also allows prompts and interactive replies. View-only public links read the existing tmux pane without attaching a terminal client. Control uses the existing terminal stream and its input lease.
In Projects, open Shared sessions or press Shift+S. On a selected owned
session, Shift+S opens its access editor. Choose a user or public link and press
v for view, c for control, or d to revoke. The highlighted row determines
the recipient; the panel displays it above these actions. Users are created through the existing server
controller invitation flow. Public browser links also work for the local implicit
operator, without enabling server users or creating recipient accounts.
Public browser links
Select an owned Claude or Codex session and open Shared sessions / Shift+S.
Press l or click Create view link to create and copy a view-only link.
Press e to choose one hour, 24 hours (the default), seven days or until revoked.
Authorization expiry and the public address have independent lifetimes. Frontend
updates retain the separate relay and hostname. A relay restart, provider outage
or host reboot can change a free tunnel hostname before the grant expires; the
same share ID/token still works on the controller's current public origin. Web
Access records recent origin changes. For durable links, configure Integrations
→ Web link settings → Own domain / HTTPS reverse proxy. Temporary Quick Tunnel
addresses cannot be reserved or resurrected without provider-side stable routing.
L / Create control link explicitly grants input control as well.
Before creating a control link or changing view-only access to control, the
console warns that provider subscription terms may restrict multiple people
using the same account and asks you to check those terms. Confirm the action to
grant control, or cancel without changing access. View-only links skip this
warning. Don't show again is saved only when you confirm and applies to your
devctrl user across native, browser and desktop clients; other users keep their
own preference. In the terminal, Space toggles the checkbox, Enter confirms and
Esc cancels. The browser uses a native checkbox.
Anyone holding the resulting link sees that one terminal in a separate browser
screen. There is no console login, project picker or account invitation.
The compact header uses the same native model and effort labels as Projects'
Mosaic cards. It shows the session name, agent icon, project/repository names,
activity, known active-subagent count, installed native goal and view/control
mode. Only verified native goal completion shows 100%; token spending is not
completion. A missing model stays unknown, expired native evidence becomes
unknown (stale), and Codex's unspecified effort is model default, not an
inferred effort level. Header changes arrive on the existing terminal WebSocket
within one second, including while terminal output is idle. No console-wide
state or owner API is polled. On a small screen the header wraps above the
terminal and keeps the project and full title available as text/tooltips.
View-only mode has no navigation, input or console controls. Scroll up to read recent history; live refresh preserves that scroll position. Temporary network interruptions reconnect automatically without starting another agent process. Silent open connections also recover: a client watchdog obtains a fresh one-use connection ticket after missing server keepalives, with bounded backoff and continued retries during a prolonged outage. Returning online or resuming a background tab triggers another check. Recovery never replays control input; editing stays disabled until the current control grant is verified. Unchanged snapshots retain scrollback, selection and the current scroll position.
Use arrows to select a public link; y copies a link created during this visit,
and d or x revokes it. v and c change an existing link's role without
changing its URL or expiry. Role changes disconnect its viewers and invalidate
previous connection tickets; visitors reconnect with the same link. A revoked link disconnects its open visitors immediately,
without detaching the owner or stopping the native provider. The reusable secret
is returned only when the link is created; only its hash is stored. If the panel
has been closed, create a fresh link to copy and revoke the old one.
The controller and web gateway must be reachable through public web access. The native panel reads the current public gateway origin from the controller's fresh status, including when the native UI reaches a remote controller through SSH. It does not substitute the laptop's loopback address or copy the full console sign-in key. Run both controller and gateway on the server to keep links working while the laptop is asleep.
Free tunnel addresses can change after gateway recreation. Link capabilities survive controller restart, but an old tunnel address cannot redirect visitors. Create/copy a link using the current gateway address, or configure a stable HTTPS origin. A visitor can attach only while the exact coding provider is already running; opening or reconnecting a public link cannot launch or resume it. Shell sessions are not supported by public links.
A view link exposes all output printed in this terminal, including the bounded recent output replay. A control link lets visitors direct the running agent with its existing resources. Neither role grants raw console APIs, project ownership, accounts, credentials, approvals, service grants or access to another session.
The recipient sees an owner-labelled shared-session card in Projects' shared session picker. Enter or click attaches to that exact native session. It does not add the owner's private project, editable workspace, account, secrets, service grants or approval queue to the recipient's own resources.
Input and terminal layout
View-only public visitors receive a read-only capture stream with up to 2,000 recent lines, bounded to 256 KiB. Identical captures are reused and unchanged content is not retransmitted. Idle connections receive periodic keepalives. The current viewport is retained when new output arrives while reading history. Repeated identical snapshots, including a reconnect replay, leave the browser's terminal untouched. Changed captures replace the screen in one buffered write; they retain terminal modes and restore a selected history span when its text is unchanged. A browser resize refreshes the capture for its new local dimensions without resizing the agent's terminal in view-only mode.
Interactive participants share one existing host terminal transport. Connecting another viewer does not detach the first viewer, open another tmux client, restart an agent or create another workspace. Output is broadcast to authorized viewers; the controller keeps at most 256 KiB of recent terminal bytes for a newly attached interactive participant.
One participant owns the input lease at a time. This prevents different people's
keystrokes from composing a single mixed prompt. The browser displays the role,
input owner and participant count, with Take input, Release input and
Detach buttons. In a native terminal, Ctrl+\ takes/releases available
input; Ctrl+] detaches. A lease cannot be taken while someone else owns it.
The owner can transfer input to a connected control participant from the access
editor with t. Disconnecting releases that participant's lease.
Each public browser connection has its own guest participant identity, even when
several visitors open the same link. The owner can transfer input to a connected
control guest using the same owner-only input-transfer API.
Only the input owner can resize the native terminal. Other viewers follow its dimensions instead of repeatedly resizing the underlying agent for their own windows. Users with view-only access cannot acquire input, send bytes, resize, or submit arbitrary host terminal protocol commands.
Owner visibility
Projects list rows and Mosaic tiles show three levels of sharing status:
- SHARED, cyan: a user grant or unexpired public link exists.
- WATCHING NOW, yellow: visitors are currently viewing the session.
- WATCHING / CONTROL, magenta: connected visitors include someone authorized to control input. The watching count includes control visitors.
The owner's native terminal also displays a persistent tmux footer with current watcher and control counts. It becomes yellow for viewers or magenta when control visitors are present, and clears when they disconnect. This changes the tmux status bar without injecting prompts or restarting the provider. Sharing metadata is visible only to the session owner; no guest identity or link capability is included in Project status.
Boundaries and lifetime
Sharing does not change runtime ownership. New sessions from different application users still require different containers and checkouts, including when they use the same Git repository. Resource usage, cleanup ownership and provider quota remain charged to the session's original owner. Terminal grants do not authorize kill/delete, launches, container reuse, approval decisions or account administration.
Control deliberately lets someone interact with the owner's running agent, using the environment and resources already available to that agent. Grant it to people who should be able to direct that session. Viewers see everything printed in the shared terminal; the feature does not redact terminal contents after the owner chooses to share them. Provider credentials are not returned in sharing metadata, copied into another user's account, or embedded in reusable images.
Role changes and revocation close the affected open stream immediately. Input and output also recheck the grant, authenticated user, and provider process generation; expired/disabled users and expired public links lose an idle connection within one second. A changed native generation requires a fresh attachment. A guest may attach only to a currently running provider and cannot start/resume it; the owner must resume an ended one. Grants survive controller restart in the existing controller SQLite database.
Shared application-project ownership is a different capability and is not implemented here: sharing a terminal does not merge users' project namespaces.
API
GET /v1/session-sharing: the current user's minimal received session cards.GET /v1/sessions/:id/sharing: owner-only grants, active-user names and connected participants.GET /v1/session-sharing/public-origin: authenticated current public gateway origin, without its console key.POST /v1/sessions/:id/sharing/links: owner-only create; body{ "role": "observe" | "control", "lifetimeMs": positive_integer | null }. Defaults: view only and 24 hours; finite lifetimes are capped at 30 days. Returns the new link secret once, a fragment-basedviewerPath, and a fullurlwhen public access is ready.DELETE /v1/sessions/:id/sharing/links/:linkId: owner-only revoke and disconnect public viewers.PUT /v1/sessions/:id/sharing/links/:linkId, body{ "role": "observe" | "control" }: owner-only change to an unexpired, unrevoked link; disconnects its viewers and invalidates old-role tickets.GET /v1/public/session-links/:linkId: allowlisted header metadata: name/kind/status/role/expiry, project/repository display names, model summary, normalized activity, active-subagent count and short native goal. Requires this link's bearer capability. Never returns account/native session IDs, runtime paths, configuration, credentials or other Projects.GET /v1/public/session-links/:linkId?history=1: the same exact-session authorization, returning bounded recent terminal history.POST /v1/public/session-links/:linkId/tickets, body{ "token": "link capability" }: creates a 30-second one-use ticket bound to this link and the browser Origin.WS /v1/public/session-links/:linkId/terminal?ticket=...: existing shared terminal protocol plus deduplicatedterminal.metadataheader updates; accepts only that link's ticket and Origin. The reusable link secret is not included in the WebSocket URL.PUT /v1/sessions/:id/sharing/:userId, body{ "role": "observe" | "control" }.DELETE /v1/sessions/:id/sharing/:userId: revoke and disconnect that user's viewer.POST /v1/sessions/:id/sharing/input, body{ "userId": "connected-user" | null }: owner-only input transfer/release.- Existing
/v1/terminals/attachand/v1/sessions/previewsaccept an explicitly granted exact session without granting any other resource access.