Remote agent access: shared local + remote terminal (multi-viewer) over iroh #478

New Issue

2026-07-24T21:13:43-04:00

didericis-claude commented

2026-07-24 21:13:43 -04:00

Remote access to running agents: spin an agent up locally and watch/drive the same session from a phone, with multiple viewers on one session.

Context

PRD 0070's plane separation puts the remote-access transport (iroh) in the orchestrator (control plane). Terminal access is BottleBackend.exec_agent (ssh -t / container exec --tty / docker exec) — an orchestrator-owned exec operation. The gateway is never in the PTY path (it only sees agent network traffic), so remote terminal is inherently a control-plane feature, not a data-plane one.

Goal

A --remote flag on start (and resume) that gives the usual local terminal and publishes the same session for remote attach.
Multi-viewer: local + N remote clients share one session — all see the same output; input per policy.
Detach / reattach: start locally, close the laptop, reattach from the phone later; the session outlives its viewers (and an orchestrator restart).

Resolved (per PRD 0070)

Transport: iroh, terminating in the orchestrator; operator-role-gated (reuses control-plane auth) — one authenticated remote door.
Gateway uninvolved: the PTY is exec-sourced on the control plane; the data-plane gateway holds no terminal and gets no remote door (keeps it slim / P2P-free).
Multi-viewer requires a session multiplexer — one PTY, many attached clients (broadcast output, merge input) — since a raw exec is a private PTY. Local and remote clients are both clients of the one multiplexed session.

Open design decisions

Multiplexer location — in the bottle (tmux-style: session persists independent of viewers and orchestrator restarts; native multi-client + read-only attach; small agent-image dep) vs. in the orchestrator (no agent dep, but the session is tied to the exec, the local terminal routes through the orchestrator, and detach is awkward). Leaning bottle.
Input arbitration — collaborative (any client types) vs. one driver + N read-only observers; likely both, per-viewer.
Per-client window size / rendering — laptop and phone differ; size-to-smallest (tmux default) vs. per-client rendering (a mobile xterm renderer + a curated key bar). Mostly mobile-UX, not architecture.
Always-multiplexed vs. only under --remote — always run the session under the multiplexer (any local session can be published later; every agent runs under it) vs. plain exec unless --remote.

Remote access to running agents: spin an agent up locally and watch/drive the **same session** from a phone, with **multiple viewers** on one session. ## Context PRD 0070's plane separation puts the remote-access transport (**iroh**) in the **orchestrator** (control plane). Terminal access is `BottleBackend.exec_agent` (`ssh -t` / `container exec --tty` / `docker exec`) — an orchestrator-owned exec operation. The **gateway is never in the PTY path** (it only sees agent *network* traffic), so remote terminal is inherently a control-plane feature, not a data-plane one. ## Goal - A **`--remote`** flag on `start` (and `resume`) that gives the usual **local** terminal *and* publishes the **same session** for remote attach. - **Multi-viewer:** local + N remote clients share one session — all see the same output; input per policy. - **Detach / reattach:** start locally, close the laptop, reattach from the phone later; the session outlives its viewers (and an orchestrator restart). ## Resolved (per PRD 0070) - **Transport:** iroh, terminating in the **orchestrator**; operator-role-gated (reuses control-plane auth) — one authenticated remote door. - **Gateway uninvolved:** the PTY is exec-sourced on the control plane; the data-plane gateway holds no terminal and gets no remote door (keeps it slim / P2P-free). - **Multi-viewer requires a session multiplexer** — one PTY, many attached clients (broadcast output, merge input) — since a raw `exec` is a *private* PTY. Local and remote clients are both clients of the one multiplexed session. ## Open design decisions 1. **Multiplexer location** — in the bottle (tmux-style: session persists independent of viewers *and* orchestrator restarts; native multi-client + read-only attach; small agent-image dep) vs. in the orchestrator (no agent dep, but the session is tied to the exec, the local terminal routes through the orchestrator, and detach is awkward). Leaning **bottle**. 2. **Input arbitration** — collaborative (any client types) vs. one driver + N read-only observers; likely both, per-viewer. 3. **Per-client window size / rendering** — laptop and phone differ; size-to-smallest (tmux default) vs. per-client rendering (a mobile xterm renderer + a curated key bar). Mostly mobile-UX, not architecture. 4. **Always-multiplexed vs. only under `--remote`** — always run the session under the multiplexer (any local session can be published later; every agent runs under it) vs. plain `exec` unless `--remote`. ## Related - **PRD 0070** — the orchestrator/gateway plane split, iroh-in-the-orchestrator, and the remote-terminal resolution recorded there. - **#468** — host-side control server (the orchestrator's remote-entry role).

didericis-claude added the Kind/Feature label 2026-07-24 21:13:43 -04:00

didericis referenced this issue from a commit

2026-07-24 21:14:25 -04:00

docs(prd-0070): record remote-terminal resolution; track detail in #478

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: didericis/bot-bottle#478