From Native Window to Web Surface: The Path a Desktop Session Takes
To understand DSH Desktop, follow one launch rather than beginning with its menus. This chapter traces how the native application selects a DSH profile, boots the Host, carries the official Web UI into a controlled renderer, and decides when the result is healthy enough to expose to the user. The practical value of that path is responsibility: when something goes wrong, a reader can ask which layer owns the failing decision instead of treating “the desktop” as one undifferentiated program.
The path begins with a useful constraint. DSH Desktop is not trying to replace DeepSeek Harness with an Electron-native interface. The upstream Host and Web client remain part of the composition; Electron supplies the native process and window environment around them. That means the launch has to coordinate two worlds without making either world pretend to be the other.
Startup is a sequence of ownership handoffs
The first handoff happens before DSH itself is visible. Electron acquires a single-instance lock. If another instance already owns it, the new process exits rather than starting a competing Host and writing to the same local state. A special installer-quit request is also handled before ordinary startup, but the important architectural point is that there is one native coordinator for one active application session.
Next, the launcher resolves the active profile and Desktop-owned mode and environment state. A profile is not just a display preference; it determines which DSH bundles, dependencies, and patches will be composed. The launcher prepares that profile without treating a read-only listing operation as permission to rewrite it. It also prepares the native runtime and the bundled package-manager environment that Host and Desktop-aware plugins may need. These facts are established before the Host’s Loader tree mounts, because later plugins must see the same selected identity and capability set.
The Host is then booted as a Cordis generation. Cordis is the composition framework through which DSH services and plugins become one running tree. Desktop supplies the launcher-resolved runtime, browser-access policy, LAN state, and package-manager bootstrap, then registers its own Host services before third-party entries can consume them. The ordinary upstream base and Web-application bundles are composed alongside the selected profile’s contributions. This is where the project’s “desktop as a plugin” idea becomes operational: the shell does not ask Electron to maintain a separate list of Web extensions. It participates in the same Host composition that the profile already uses.
The ordering is doing real work. The launcher must settle the profile and its environment before a plugin can ask which profile is active or start a Desktop-owned package operation. Desktop services are made available before the Loader mounts entries that may depend on them, so a plugin sees a coherent set of capabilities rather than a partially assembled application. This is also why the launcher is not just a thin wrapper around a command. It is the admission point for facts that should remain stable during one run: the selected profile, the local service’s access policy, and the native resources that will eventually present the page.
The distinction between preparation and composition is useful when reading failures. Preparation can discover that a profile is malformed or that its dependencies cannot be materialized. Composition can fail because an upstream or third-party entry cannot load. Neither failure should be disguised as a renderer problem, because no renderer can repair a Host tree that was never assembled correctly. Conversely, a successful Host boot does not prove that the browser surface is usable. The application therefore keeps moving through explicit gates: first the runtime and Host exist, then the carrier binds, then the page loads, then the client reports its own condition, and finally the native surface is accepted as healthy. Each gate narrows what “ready” can mean.
Only after that composition is ready does the Host bind its Web carrier. The carrier is the existing DSH HTTP and WebSocket surface. By default it listens on the local loopback interface, so the native renderer can reach it on the same machine without making the service a LAN endpoint. When the user has explicitly confirmed broader network exposure, the Host can bind to all network interfaces instead. That is a change in reachability, not a change in who owns the DSH service: the Host still provides the surface, and the renderer still consumes it.
Electron then creates the BrowserWindow and loads the loopback page. In the ordinary framed modes, Desktop can use a separate compatibility shell for the native chrome while the Web contents remain the DSH page. The native layer knows how to show, hide, focus, and close the window; the Web layer knows how to render the conversation and its plugin contributions. Closing the window normally hides it, which preserves the Host generation. Quitting is a different action that requests orderly disposal.
The order of visible readiness matters. The tray is created only after the Web surface has loaded, so the application does not advertise a fully usable desktop session before it has a page to reveal. But page loading alone is still not the final success condition. Desktop waits for the client Loader to report health and reconciles that report with native mounting before committing the startup as healthy. A profile that produces a window but fails to assemble its client surface has not succeeded merely because Electron created a window.
That distinction gives the launch a set of meaningful failure points. A second instance can be rejected. Profile preparation can fail before Host boot. Host composition can fail before a page exists. The page can fail to load. The client Loader can report a plugin failure. Native mounting can fail independently. DSH Desktop’s lifecycle machinery keeps these cases separate because each one has a different owner and a different recovery route. The next chapter will examine what happens when the selected composition changes; for now, the essential point is that one running arrangement is treated as a coherent generation, not as a permanent collection of objects that can be mixed indefinitely.
The sequence shows why “the window opened” is a weak diagnostic. The user’s visible surface depends on a chain of prior decisions, and the final healthy state depends on evidence from more than one participant. It also shows why the carrier is not an incidental transport hidden beneath a native product. It is the seam through which the official client and third-party Web contributions reach the renderer.
The carrier is the shared seam, not a second plugin universe
A desktop wrapper could expose a private IPC bridge and ask every extension to learn a new native API. DSH Desktop takes the opposite route. The Host continues to expose the ordinary Web UI through HTTP and WebSocket, and the renderer continues to receive normal DSH client modules. A plugin with browser UI uses the upstream conventions—client metadata, routes, remote procedure calls, services, and slots—rather than requiring a desktop-specific registration just to appear in the page.
This choice separates transport from authority. HTTP and WebSocket carry the page and its interactions, but they do not give the page arbitrary control over Electron. The page does not read Host services directly as if the renderer were inside the main process. Instead, ordinary DSH mechanisms move the necessary data across the existing Web boundary, while Desktop exposes only the client facts that its own presentation needs. That arrangement keeps the upstream Web client recognizable in Desktop, an important condition for using the same plugins in a command-line or ordinary browser profile.
It also avoids a common category mistake about “integration.” If a Desktop feature needs the active profile, that fact belongs to a Host service whose lifetime is tied to the running composition. If a Web contribution needs to position itself below native chrome, it needs geometry facts in the Client environment. If a command must open a native terminal or quit the application, it belongs to a Desktop-owned action rather than an arbitrary browser call. The transport lets these responsibilities cooperate, but it does not erase their differences. A message reaching the renderer is not evidence that the renderer should own the resource described by that message.
The shared carrier further reduces the cost of upstream change. DSH’s official Web client and a third-party client contribution do not need separate Electron builds merely because the page is being displayed in a desktop window. The same composition metadata can be discovered by the Web side, while native code remains responsible for the small set of functions that browsers cannot supply. The trade-off is that Desktop must respect the assumptions of the ordinary carrier. Replacing it would require new upstream transport extension points, new client behavior, and a new compatibility surface; the current design gains continuity by declining that expansion.
The native shell adds controls at its own layer. It owns the application window, tray, native dialogs, external-link handling, and platform-specific chrome. The official Web client owns the conversation and the upstream layout unless a Desktop presentation mode deliberately takes responsibility for a different root layout. Third-party plugins own only the services and slots they declare. These ownership statements are more useful than a list of technologies because they predict what an extension can and cannot change.
The renderer boundary is reinforced by several controls. The mounted shell keeps main-frame navigation and redirects on the exact local origin. Ordinary HTTP, HTTPS, and mail links are handed to the operating system rather than being allowed to turn the application window into an arbitrary browser. Desktop-created utility windows use context isolation, disable Node integration, enable the Chromium sandbox and web security, deny popups, and prevent WebView attachment. The main page also uses a generation-scoped capability that lets the Host distinguish its Electron renderer from an ordinary browser request. These measures reduce the renderer’s direct native reach; they do not make the DSH plugin ecosystem a security sandbox.
The difference is important. A sandboxed renderer is a restriction on what that renderer can call directly. It is not a restriction on every Host plugin that runs in the local process, nor on a package or tool that the user deliberately installs. A third-party plugin can still operate with the permissions of its local process. DSH Desktop’s public service boundary helps an author avoid private Electron coupling, but interface discipline and operating-system isolation are separate properties.
The default network posture makes the same distinction visible. Loopback limits ordinary reachability to the local machine, and Desktop can give the native renderer an authenticated local URL for the active generation. If the user enables LAN access, the service becomes reachable from other devices on the network. The project warns that this exposure has no user authentication and can allow someone on a trusted—or merely connected—network to operate the computer through DSH’s available capabilities. The warning is therefore not a generic security disclaimer. It identifies a real change in the access boundary. HTTPS or a certificate can protect the connection’s transport properties, but it does not turn a shared local service into an account-based authorization system.
“Local-first” needs the same careful reading. DSH Desktop keeps profiles, settings, sessions, logs, and crash material on the device by default, and its official update check does not intentionally send prompts, responses, file contents, or model credentials. But a configured model provider, external tool, catalog, registry, or plugin may receive information required for the operation the user chooses. A native shell can constrain its own update request and navigation policy; it cannot redefine the privacy terms of every service connected through the composable Harness.
This layered design also explains why DSH Desktop does not treat every visual change as a live renderer tweak. The client receives fixed native geometry facts for one generation. Compatibility mode preserves the official presentation below an independent Desktop frame; other modes can install Desktop-owned layout registrations while continuing to host official occupants. Changing the mode or native material changes composition and window construction, so the application restarts instead of swapping root ownership inside a live tree. The visual result is governed by the same lifecycle idea as the Host: a generation has a coherent set of owners.
For the user, this architecture provides a simple surface over a non-simple sequence. Start the application, and a managed native process selects a composition, boots the upstream Harness, opens its ordinary Web surface, and presents it through a constrained renderer. For a maintainer, the sequence is a map of responsibility. For a plugin author, it is a warning against assuming that the Electron window is the platform. The stable platform is the DSH composition and the public contracts that Desktop adds around it.
The central lesson is that a thin native shell is not the same as a trivial wrapper. DSH Desktop earns its thinness by leaving the agent runtime and Web carrier in place, then surrounding them with explicit startup, origin, and ownership rules. Those rules make the next question unavoidable: when a user chooses another profile or changes a mode, how can the application replace the whole arrangement without allowing pieces of the old generation to leak into the new one?