How the Server Edition of nodeterm Differs Architecturally from the Electron Version

The Server Edition replaces Electron’s three‑process main/preload/renderer architecture with a lightweight two‑process Node HTTP/WebSocket server model, while both implementations plug into the same platform‑agnostic core services through an identical CorePlatform interface.

nodeterm is structured around a shared core layer (src/core/) that houses all platform‑agnostic services such as PTY management, workspace persistence, and agent hooks. The repository ships two distinct platform layers that adapt this core to their respective environments: the Electron version for desktop users and the Server Edition for browser‑based, headless deployments. Understanding how the Server Edition of nodeterm differs architecturally from the Electron version highlights a deliberate trade‑off between native OS capabilities and universal remote accessibility.

Core Architecture and the Platform Adapter Pattern

All business logic resides in src/core/, which remains identical across both editions. Platform‑specific behaviors are abstracted behind the CorePlatform interface, implemented separately by each edition.

• Electron adapter: src/main/platform-electron.ts provides desktop‑specific integrations using Electron’s app, BrowserWindow, and safeStorage APIs.
• Server adapter: src/server/platform-server.ts provides server‑specific integrations including an HTTP server, WebSocket handling, and file‑based secret storage.

This adapter pattern ensures that features such as terminal session management and workspace state remain consistent regardless of the deployment target.

Process Model Comparison

The most significant architectural divergence lies in the process boundary design.

Electron Desktop Version (Three‑Process Model)

The Electron version runs a classic Chromium‑embedded architecture:

1. Main process (src/main/) – Node.js/Electron runtime that initializes the core services and creates browser windows.
2. Preload script (src/preload/) – Isolated context that bridges the main process and renderer using Electron’s contextBridge.
3. Renderer process (src/renderer/) – Chromium environment hosting the React UI.

The main process instantiates the platform adapter at src/main/platform-electron.ts, granting direct access to native modules such as node‑pty and OS‑level keychain services.

Server Edition (Two‑Process Model)

The Server Edition eliminates the main and preload layers, replacing them with a headless stack:

1. Node HTTP + WebSocket server (src/server/) – Runs the core services and exposes a WS‑RPC bridge defined in src/shared/rpc.ts.
2. Browser client – Connects remotely; the React UI renders in a standard web browser rather than an embedded Chromium window.

The server implements CorePlatform via src/server/platform-server.ts, handling requests over WebSocket connections rather than Electron’s IPC channels.

Inter‑Process Communication Bridges

Despite differing transport mechanisms, both editions expose an identical window.nodeTerminal API to the frontend.

Electron bridge: The preload script at src/preload/index.ts uses contextBridge to inject a narrow, privileged API into the renderer’s global scope.

Server bridge: The browser client loads a WebSocket‑RPC client from src/renderer/bridge/ that connects to ws://localhost:3000. This bridge mirrors the preload API, allowing the React UI to call core methods transparently without modification.

// src/renderer/bridge/index.ts – Browser client initialization
import { createRpcClient } from '@shared/rpc';
const rpc = createRpcClient('ws://localhost:3000');
window.nodeTerminal = rpc; // Identical interface to desktop version

OS Integration and Capability Gaps

The Server Edition sacrifices native OS integrations in exchange for headless operation and remote accessibility.

• Secret storage: Electron uses the OS keychain via safeStorage; the Server Edition stores authentication keys as raw files (node-auth-key.bin) in the working directory.
• Native modules: Features relying on OS‑level helpers—such as canvas control and context menu links—are disabled or stubbed in the Server Edition according to docs/SERVER.md.
• Notification host: Unlike the Electron version, which requires a visible window for background tasks, the Server Edition can act as a headless notification host, processing updates without a UI surface.

Deployment and Entry Points

Starting the two editions requires distinct npm scripts and environment preparations.

Electron Version (requires Node ≥ 20 and tmux):

npm install    # Rebuilds native modules

npm run dev    # Launches Electron with hidden Chromium window

Server Edition (requires Node 22+ and tmux):

npm run server:dev   # Builds renderer and starts headless HTTP/WS server

Once the server is running, users access nodeterm from any modern browser by navigating to the server URL (default http://localhost:3000), where the WebSocket bridge initializes automatically.

Summary

• Shared core: Both editions use identical logic in src/core/ for PTY, workspace, and agent management.
• Adapter pattern: src/main/platform-electron.ts and src/server/platform-server.ts implement the same CorePlatform interface for their respective environments.
• Process reduction: Server Edition removes the main and preload processes, replacing them with a Node HTTP/WebSocket server (src/server/).
• Transport swap: Electron’s contextBridge (src/preload/index.ts) becomes a WebSocket‑RPC bridge (src/shared/rpc.ts and src/renderer/bridge/).
• Feature limitations: Server Edition lacks OS keychain access, canvas controls, and context links, storing secrets in flat files instead.
• Headless capability: Server Edition supports fully headless operation as a notification host, while Electron requires a window process.

Frequently Asked Questions

What are the minimum Node.js requirements for each edition?

The Electron version requires Node.js ≥ 20, while the Server Edition requires Node.js 22 or newer. Both require tmux to be installed on the host system for terminal session management.

Can the Server Edition access native OS features like the keychain?

No. The Server Edition lacks Electron’s privileged APIs and cannot access the OS keychain. It stores sensitive data as raw files (node-auth-key.bin) in the application directory, whereas the Electron version uses the platform’s secure credential store via safeStorage.

Is the React UI code identical between the desktop and Server versions?

Yes. The React components in src/renderer/ are shared across both editions. The Server Edition loads these components in a standard browser environment, while the Electron version hosts them inside a Chromium window. The UI communicates with the core through window.nodeTerminal in both cases, abstracting whether the underlying transport is Electron’s IPC or a WebSocket connection.

How does the Server Edition handle background tasks without a window?

The Server Edition runs as a persistent Node.js process capable of acting as a headless notification host. Unlike the Electron version, which requires a renderer process for background work such as update checks, the Server Edition manages these tasks within the main HTTP/WebSocket server process, allowing it to operate on remote servers without a display.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}