Control local and remote CODE AGENTS servers from one desktop app

[dnviti]

Problem / Motivation

The installed desktop app currently controls only the CODE AGENTS server running on the same computer. Developers who work across their local machine and several remote instances must open each remote server separately in a browser or installed web app.

That workaround provides access, but it fragments a daily workflow across separate session lists, sign-ins, notifications, settings, and server contexts. It also prevents the desktop app from becoming the single controller that the desktop experience is intended to provide.

This work is the remote-controller follow-up explicitly deferred by #84 and depends on that desktop foundation being complete.

Goal

Make one installed desktop app the unified controller for the local computer and any practical number of remote CODE AGENTS servers.

Users can see sessions from every available server together, choose the target when starting work, receive attention from background servers, and reach every feature supported by the selected server and their role without losing the existing zero-configuration local experience.

Scope

Unified controller

• Keep a permanent Local computer entry that starts with the desktop app and preserves all existing local sessions, settings, and data without a migration choice.
• If the local server cannot start, mark Local computer unavailable with a useful reason while keeping saved remote servers usable.
• Show local and remote sessions in one combined list ordered by most recent activity, with an always-visible server label and a server filter.
• Show connection, authentication, compatibility, and insecure-certificate status without hiding saved servers or trapping the user on an error screen.
• In New Session, always present the server chooser and preselect the server used for the previous new session. The created session belongs only to the server the user confirms.
• Keep all configured servers connected for status and attention notifications. Every notification identifies its server and opens the correct session.
• Keep every command, approval, and destructive or privileged confirmation visibly tied to its target server.
• For projects, conversations, usage, runtime profiles, deploy targets, server updates, and other server-owned features, require an explicit server choice and expose everything that server and the signed-in role support.
• Preserve terminal and structured-conversation workflows; session resume, history, search, export, plans, questions, approvals, attachments, and notifications; files, editing, transfers, Git and GitHub views; projects, usage, profiles, environments, deploy targets, and authorized server-update controls whenever the chosen server supports them.
• Hide browser/PWA installation controls inside the installed desktop app while leaving browser and PWA use unchanged.
• Share desktop-only appearance and chat-display preferences across servers. Keep permissions, profiles, infrastructure settings, and other server-owned choices scoped to their server.
• Keep desktop-package update notices separate from server-update notices and identify which installation each notice affects.

Connection management

• Put remote-server management in Settings and keep it reachable when a server is offline, signed out, incompatible, or blocked by a certificate error.
• Let users add a remote server using a unique friendly name and a verified HTTPS address.
• Confirm that an address is a reachable, compatible CODE AGENTS server before saving it, while allowing a verified server to remain saved in a signed-out state.
• Keep one saved entry and one remembered GitHub account per server. Reject duplicate server entries.
• Allow renaming without disrupting the connection. Treat an address change as a new destination: verify it again and clear the previous sign-in and certificate approval while retaining the chosen display name.
• Impose no fixed user-visible limit on saved servers and keep names, filters, and status usable as the catalog grows.
• Reconnect interrupted servers automatically, show the last successful contact, and offer manual retry.
• Keep incompatible servers visible with clear upgrade guidance instead of exposing a partially broken controller.

LAN discovery

• Provide an explicit Find servers action in Settings; do not scan automatically at startup or in the background.
• Discover only servers whose operator has deliberately enabled LAN discoverability.
• Before authentication, expose only the operator-provided server name, connection address, CODE AGENTS identity, and compatibility information.
• Show discovered candidates for review and require the same verification, naming, sign-in, and certificate decisions as a manually entered address before saving them.
• Treat discovery as a way to find existing servers only.

Authentication, offline state, and certificate handling

• Complete each remote server’s normal GitHub sign-in in a dedicated in-app window and return directly to the unified controller.
• Remember authentication independently for each server across desktop launches. Signing out of one server does not affect any other server.
• When a server is offline, retain only its last-known session name, server identity, runtime, status, and last activity. Do not cache transcripts, files, credentials, command output, or other session content.
• Keep that metadata across desktop launches until the server refreshes it, the user signs out, or the saved server is removed.
• Mark offline sessions unavailable, disable actions that require the server, and offer retry, connection editing, removal, or another server.
• On sign-out, clear that server’s cached session metadata immediately.
• On removal, clear the saved connection, remembered sign-in, and cached metadata without deleting or stopping anything on the remote server. If sessions are running, warn that visibility will be lost and leave the work running.
• Keep the server catalog, trust choices, authentication, and cached metadata on the current desktop installation only.
• Provide an Ignore invalid SSL certificates toggle for each exact saved server. Keep it off by default and never apply it to other servers or external sign-in pages.
• Enabling the override requires an explicit warning that commands, files, credentials, approvals, and session content could be intercepted.
• Once approved, allow self-signed, untrusted, expired, and hostname-mismatched certificates for that server and show a persistent insecure badge on the server and its sessions.
• If that server later presents a different invalid certificate, pause the connection and require renewed approval.

Non-goals

• Installing or provisioning CODE AGENTS on another machine.
• Starting, stopping, restarting, or configuring a remote operating-system service.
• Cross-server bulk session actions, updates, settings changes, scheduling, or fleet administration.
• Automatic LAN scanning, discovery without server-operator opt-in, internet-wide discovery, or account-based server discovery.
• More than one remembered account for the same server.
• Plain-HTTP remote connections.
• Multiple native windows or a separate window for each server.
• Cloud synchronization, import, or export of the saved server catalog.
• Offline copies of transcripts, files, command output, or credentials.
• Making a feature available when the selected server, platform, feature configuration, or signed-in role does not support it.
• Replacing or changing browser/PWA access, creating a mobile app, or adding product analytics.

Security / Safety Considerations

• A remote CODE AGENTS session can run commands and reach files with the authority granted by that server. The target server must therefore remain visible throughout work and be repeated before risky actions.
• Authentication and authorization remain server-owned. Connecting through the desktop app must not broaden a user’s role or expose administrator-only controls.
• Remembered authentication and cached session metadata are sensitive local data. They remain isolated by server and are cleared on sign-out or removal as agreed.
• Ignoring certificate failures removes protection against an impersonated or intercepted server. The override is explicit, narrowly scoped, visibly persistent, and renewed when the invalid certificate changes.
• LAN discovery is opt-in and reveals only the minimum information needed to recognize and connect to a server. It reveals no users, sessions, credentials, files, or usage information.
• Removing a saved server is a local controller action only. It never stops work or deletes remote data.
• Background notifications honor the desktop user’s notification preferences and always identify the originating server.

Acceptance Criteria

• An existing desktop user upgrades and sees all prior local sessions and settings under Local computer without setup or data loss.
• Local computer starts with the app and can launch sessions as before.
• A local startup failure leaves Settings and saved remote servers usable and explains why Local computer is unavailable.
• A user can add, rename, test, edit, and remove remote servers from Settings on every supported desktop platform.
• An unreachable address, unrelated website, unsupported server version, denied sign-in, expired sign-in, and certificate failure each identify the affected server and offer an appropriate recovery action without breaking the rest of the controller.
• A verified server can be saved while signed out and signed into later through a dedicated in-app GitHub flow.
• Authentication survives a desktop restart independently for each server, and signing out of one server leaves every other server signed in.
• The same server cannot be saved twice, and changing its address requires fresh verification while clearing the previous sign-in and certificate approval.
• Local and remote sessions appear in one list ordered by global recent activity, each with an unambiguous server label and working server filter.
• New Session shows the server chooser, preselects the last-used server, and creates work only on the server the user confirms.
• A background session on any connected server can raise a labeled attention notification that returns the user to the correct server and session.
• An interrupted server reconnects automatically, reports its last successful contact, and also supports manual retry.
• Offline session metadata remains visible and unavailable actions remain disabled without exposing cached transcripts, files, credentials, or output.
• Signing out or removing a server clears its cached metadata; removal also clears its remembered sign-in and never changes remote data.
• Removing a server with running work warns the user and leaves that work running.
• Projects, conversations, usage, profiles, environments, deploy targets, server updates, and other server-owned surfaces require an explicit server choice and respect that server’s roles and capabilities.
• All supported terminal, structured-conversation, session, history, plan, approval, file, GitHub, project, usage, profile, environment, administration, and update features work remotely whenever the selected server and user role support them.
• Every session view and every privileged or destructive confirmation identifies its target server.
• Desktop-package and server-update notices remain available simultaneously and cannot be confused with one another.
• Desktop-only appearance and chat-display preferences follow the user across servers while server-owned settings remain isolated.
• The certificate override is off by default, affects only the exact approved server, accepts every agreed certificate-failure category, and never weakens another server or external site.
• Enabling the override requires a clear interception-risk confirmation and produces a persistent insecure badge.
• A different invalid certificate blocks reconnection until the user explicitly approves it.
• A user-triggered LAN scan finds an opted-in server, exposes only the agreed minimal identity, and requires review and verification before saving it.
• A server that has not opted into discovery is not advertised, and no automatic background scan occurs.
• No product cap prevents additional server entries, and the catalog remains navigable through names, filters, and visible status.
• The controller adds no product analytics and does not synchronize or export its server catalog.
• New controls, statuses, warnings, and selectors are fully usable by keyboard, screen reader, touch, focus navigation, and non-color cues.
• The complete experience passes on Linux, Windows, Intel macOS, and Apple Silicon macOS packages.
• An end-to-end demonstration uses Local computer, one valid-certificate remote, and one invalid-certificate remote to show combined sessions, targeted launches, isolated sign-ins, background attention, offline recovery, certificate-change approval, and restart persistence.
• Desktop, certificate, authentication, service, configuration, troubleshooting, and changelog documentation describe the completed behavior.
• dnviti provides final product sign-off.

Suggested Phasing

1. Preserve the local experience and add the saved-server catalog, manual verification, isolated sign-in, compatibility handling, and certificate safety.
2. Add the combined session experience, explicit server targeting, background status and notifications, offline metadata, and server-scoped product surfaces.
3. Add operator-controlled LAN discovery and candidate review.
4. Complete cross-platform verification, the agreed end-to-end demonstration, accessibility review, and documentation.

The issue remains open until every phase and acceptance criterion is complete.