Remote-only (client) install: connect to a remote assistant/stack

[itlackey]

Summary

Support installing OpenPalm as a client only — no local stack — and connecting to an assistant running on another computer or container. Also covers the PWA install path (same app, connection-management-only mode).

Plan

Implemented as part of the UI Runtime Modes refactor. See docs/technical/ui-runtime-modes-plan.md for the full design.

Architecture decisions (resolved)

• Connection management moves to /connections (new route, no longer under /admin). All modes — host, browser, PWA — can reach it without host admin auth.
• ConnectionEntry model replaces the old endpoint model. Adds a kind field (local-opencode | remote-opencode | openpalm-client-api). endpoints.json is not renamed.
• pwa-static host mode is the client-only install. The same SvelteKit build; capabilities hide host controls. No local assistant/guardian containers started. UI is the only process.
• Auth: Guardian Basic auth matching the OpenCode implementation. Coordinated with Guardian: mTLS adapter auth + keep authn/authz seams generic  #435 — no parallel credential mechanism.
• Connection config: stored in endpoints.json under OP_HOME/config/. Credentials remain file-based secrets (knowledge/secrets/), consistent with the existing secret boundary.
• Connection status: surfaced in the /connections UI and in the chat empty state.
• Wizard deep-link: after a "set up later" install, landing at /connections/new is the default when no connection is configured.

What a client-only install exposes

• /connections — add/switch/manage remote assistants
• /chat — when an active connection is established
• /api/runtime — public, returns hostMode: 'pwa-static' and connection-scoped capabilities
• No host lifecycle, no Docker, no /api/host/*

What a remote assistant exposes for clients to attach to

The Guardian /oc/* ingress (existing). The openpalm-client-api connection kind (preferred for mobile/PWA) routes through Guardian. The remote-opencode kind connects to a raw OpenCode instance directly (dev/advanced only).

Implementation

• Phase 2 of the runtime modes plan: routes/connections/, /api/connections/*, internal model rename
• Phase 6: PWA manifest + service worker enabling the installable client-only mode

Open questions (resolved)

• What does a remote stack expose for a client to attach to? → Guardian /oc/* ingress
• How is the remote endpoint authenticated? → Guardian Basic auth; aligned with Guardian: mTLS adapter auth + keep authn/authz seams generic  #435 Bearer seam
• Should a client-only install skip seeding assistant/guardian compose services? → Yes. pwa-static host mode starts no containers.

Related

• docs/technical/ui-runtime-modes-plan.md — full plan
• Guardian: mTLS adapter auth + keep authn/authz seams generic  #435 — Guardian auth (coordinates the remote auth strategy)
• Guardian state store (bun:sqlite): ingress/client registry + optional restart persistence #433 — Guardian state store (principal registry used by remote connections)
• Guardian LAN/mDNS self-advertisement #488 — mDNS (how remote assistants advertise themselves on LAN)

[fwdslsh-dev]

Direction ratified 2026-07-06 (docs/technical/ui-client-split-assessment.md): the host/client split re-scopes the runtime-modes plan's Phases 5–6. What changes for this issue:

• Phase 2 scope here is unchanged — /connections, ConnectionEntry.kind, no endpoints.json rename — with one addition: break the endpoints-state ↔ chat-state bidirectional import while in there (prerequisite for the Extract packages/client (@openpalm/client) + packages/ui-kit — thin static client app (Phase 5) #555 extraction).
• The client-only install is delivered by @openpalm/client (Extract packages/client (@openpalm/client) + packages/ui-kit — thin static client app (Phase 5) #555): a static PWA-ready app with client-held connections in IndexedDB and direct guardian calls (Basic/Bearer per Guardian: mTLS adapter auth + keep authn/authz seams generic  #435) — not the adapter-node build. The pwa-static host mode is served from two origins: localhost (harness/CLI, zero TLS) or the official hosted URL (see re-scoped PWA mode: installable client from two origins — localhost (zero TLS) + official hosted URL #511).
• Constraint to note: any phone → guardian connection requires HTTPS on the guardian (mixed content + secure-context rules) — tracked in Guardian edge TLS + CORS for remote clients (Phase 6.5 — gates the phone/PWA story) #557. Desktop/localhost clients can reach plain-HTTP LAN guardians.
• Pairing UX for adding a remote connection is paste-or-scan (host app mints a QR / one-time code) — plan §6.6.

---

Generated by Claude Code