Repository navigation
Design: Home GUI as a sandboxed capsule with a Runtime-owned host #172
Description
Part of #173 (isolation plan). Design first; Sasha reviews what users see and Irzhy reviews security.
Current source separates a trusted top-level host from the opaque Home GUI. The GUI still receives 12-hour app bearer fragments and mounts app frames; Runtime authority therefore still crosses the GUI boundary. The split below gives Runtime ownership of each app grant, frame lifecycle and approval request.
The design must deliver: a minimal Runtime-owned host (session, passkeys, window placement, approval surface); the Home GUI as a capsule in an opaque sandbox with only a delegation capability (launch, stop, broker); app capabilities minted by the Runtime directly into the frames it mounts, bound to the instance, short-lived, revocable, and ended by a real stop; every approval shown by the Runtime-owned surface with the passkey challenge bound to what is shown; Carrier peers (remote Homes, rooms, contacts, service offers) held to the same rules; provider-to-provider calls carry the originating principal's capability; and the role of the Runtime's local control listener after the split.
The note must also decide four things. First, the capability transport: a MessagePort that the host transfers into each frame at mount, with a capability that expires within minutes and is renewed only over that port. Bearer strings cannot be bound to a frame. The note defines the host broker that attaches authority to port requests, the instance, principal and session binding that #177 uses, and exactly what the receiver of a port can exercise. Second, whether the phone layout work (#92, PR #116) lands before or after the split. Third, which browser edges the host keeps (clipboard, wallet extension connectors, downloads, fullscreen), and which are hidden for 0.8.0. Fourth, that turning Discovery on or off becomes an approval, and that desktop file actions go through Library's brokered capability.
This design lands in 0.7.3; the work it designs is S2 (0.8.0).
Done means
- A reviewed design note in this issue covers the host/GUI split, window management, capability minting, stop, approvals, Carrier peers, provider-to-provider calls carrying the originating principal's capability, the role of the Runtime's local control listener after the split, the phone layout work (Required: Home on phones #92, PR Home on a phone: Home screen pages, phone title bars and stage, sheets, 44 px targets (phone-only) #116) and its order relative to the split, the MessagePort capability transport (the broker, the instance, principal and session binding, and what a port's receiver can exercise), the browser edges the host keeps or hides for 0.8.0, Discovery on/off as an approval, and desktop file actions through Library's brokered capability.
- The design note also decides that third-party executable capsules stay unavailable until a later issue proves publisher identity, exact-package approval, permission-change consent, no silent replacement and revocation.
- Home: split into a Runtime-owned host and a sandboxed Home GUI capsule #176 to Hacked-Home regression suite in CI #180 link this note, each with its own Done means, including a regression suite where a hacked Home, a hacked app frame and a foreign origin each try every route and capability and fail.
Design proposal for Irzhy and Sasha: #172 (comment). Acceptance is pending; #176-#180 implementation starts only after their acceptance.
Activity
andersalm commentedon Oct 1, 2026
The implementation tasks for this design are filed: #176 Runtime-owned host and sandboxed Home GUI, #177 per-frame capabilities with real stop, #178 approval surface, #179 Carrier peers, #180 hacked-Home suite. The design note here should cover all five before they start.
andersalm commentedon Oct 2, 2026
andersalm commentedon Oct 2, 2026
Parked for #89; the five-part design proposal and linked #176-#180 acceptance criteria are preserved in GitHub.
Done: host/GUI split, per-instance port authority, stop, approvals, Carrier/provider propagation, browser edges and phone order are proposed.
Left: Irzhy and Sasha acceptance, exact egress enforcement, and the #209/#210 boundary separating S2 capabilities from protection against the host operator.
Resume only when Anders reopens the design: reconcile the saved proposal with the current threat model, settle those decisions here, then obtain both acceptances before #176-#180 implementation.
The release session continues only #89's install/update producer work; this design stays open.
andersalm commentedon Oct 10, 2026
North star review (10 Oct), additions for this design: any capsule that draws pixels can draw a fake approval, so approvals need a region no capsule can overlay, and the passkey signs what is shown (#178).
Agents and shells only propose; Runtime minimum policy decides, and an agent never approves its own request. WASM components share the Runtime process with its keys, so third-party executable capsules also need key-free confined workers (#285).
andersalm commentedon Oct 13, 2026
Postponed to 0.8.1: isolation S1/S2 is not a 0.8.0 blocker (Anders, 12 Oct); #170 states the real isolation.
andersalm commentedon Oct 17, 2026
Anders, 16 Oct, clarified the abstraction: this is starting/activating a capsule with parameters, not granting permission to open a window. A requesting capsule proposes an admitted target capsule/resource and validated parameters. Runtime resolves identity/package, binds the exact recipient, operation and data transfer to the requesting principal/session/launch, and enforces a narrow capability; Home displays the result according to target/platform policy. A desktop window, existing view or phone screen is presentation, not the authorization unit. The bounded initial consent is Allow once / Deny through an immutable Runtime request rendered by trusted top-level Home as an Inbox approval, showing requester, target, parameters/data disclosure, requested authority and expiry. Runtime holds a short-lived nondelegatable single-use token and consumes it atomically. The recipient gets independently authorized capabilities: launch permission neither inherits the caller permissions nor grants recipient file/network access. The caller receives an outcome/opaque handle, not recipient credentials. Changed target/parameters, wrong caller, replay, denial, expiry, cancellation, revoke or epoch must cause no launch. Caller retirement/navigation or logout cancels pending requests; restart invalidates requests or preserves consumption durably. External web/OS navigation is a separate explicit export effect, not implicit capsule-launch authority. Direct app popups remain blocked; no standing/session grants until lifecycle revocation is enforced. Current launch code already separates target resolution from window_policy/attach_kind, but its free-form query is not claimed to provide the proposed typed-parameter contract. Implementation, review and installed proof remain pending. This does not complete or accept the deferred #176/#177 MessagePort/host split; Sasha and Irzhy retain the broader S2 UX/security acceptance gates.