Application Targets (Desktop, Web, Server)

Relevant source files

The following files were used as context for generating this wiki page:

• src-tauri/src/server_main.rs
• src-tauri/src/web/router.rs
• src/renderer/TauriApp.tsx
• src/renderer/App.tsx
• src/renderer/main.tsx
• AGENTS.md
• README.md
• package.json
• src/renderer/lib/tests/parity-checklist.test.ts

Termul is a multi-target application that provides a unified terminal and agent management experience across desktop, web browsers, and standalone servers. The architecture utilizes a shared Rust backend for core logic and a React/TypeScript frontend that adapts its behavior based on the runtime environment.

The system targets three primary environments:

1. Desktop: A native application built with Tauri 2.0.
2. Web: A responsive browser client, including Progressive Web App (PWA) support.
3. Server: A standalone termul-server that hosts the web client and manages remote agent processes.

Sources: AGENTS.md:7-12, README.md:162-171

Bootstrap and Environment Detection

The application determines its target environment during the bootstrap phase. The entry point src/renderer/main.tsx uses the isTauriContext() helper to detect if it is running within a Tauri webview.

• If Tauri context is detected, the app dynamic-imports TauriApp.tsx to enable desktop-native features and window APIs.
• If Browser context is detected, the app renders App.tsx and registers a Service Worker for PWA functionality.

Sources: src/renderer/main.tsx:43-65, src/renderer/lib/tests/parity-checklist.test.ts:311-325

The diagram shows the logic path taken by the renderer to switch between Desktop and Web targets.
Sources: src/renderer/main.tsx:50-65

Desktop Target (Tauri)

The desktop application uses Tauri 2.0 to wrap the React renderer in a native shell. It provides access to local system resources through Rust commands and specialized plugins.

Key Characteristics

• Native Integration: Uses TauriApp.tsx to handle window decorations, custom title bars, and native dialogs.
• IPC Communication: The renderer communicates with the Rust backend via invoke() for filesystem access, process management (PTY), and system events.
• OS Support: Targets Windows, macOS, and Linux with native platform packaging.
• Update System: Includes a built-in auto-updater using signed artifacts and a minisign public key.

Sources: README.md:58-65, src/renderer/TauriApp.tsx, src-tauri/tauri.conf.json:34-45

Web Target (Browser & PWA)

The web client provides a project-aware terminal experience within standard browsers. It is optimized for both desktop browsers and mobile devices.

Key Characteristics

• PWA Support: The web target includes a manifest and icons to enable native installation flows on mobile and desktop browsers.
• Non-Secure Context Fallbacks: Because certain APIs (like crypto.randomUUID or navigator.clipboard) are restricted in non-HTTPS environments, the web target implements safe fallbacks using getRandomValues or hidden textareas.
• Responsive UI: The layout adapts for "phone-width" viewports, though certain high-intensity features like the Canvas mode may be gated with an UNSUPPORTED_SURFACE error on mobile.
• Authentication: Uses bearer tokens and cookies (op_canvas_ct) for secure communication with the backend.

Sources: index.html:24-38, src/renderer/lib/tests/parity-checklist.test.ts:705-750, src/renderer/lib/tests/parity-checklist.test.ts:850-865

Feature	Desktop (Tauri) Implementation	Web Client Implementation
Transport	Tauri IPC (invoke)	HTTP REST & WebSockets
Persistence	Local tauri-plugin-store	Remote Durable Store (Host Authority)
Auth	Native System Access	Bearer Tokens / Cookies
UUID	Native crypto.randomUUID	CSPRNG Fallback (getRandomValues)

Sources: src/renderer/lib/tests/parity-checklist.test.ts:160-230, src/renderer/lib/tests/parity-checklist.test.ts:715-730

Server Target (termul-server)

The termul-server is a standalone Rust binary that provides the infrastructure for remote access and web client hosting. It uses the Axum framework for routing and middleware.

Server Responsibilities

• Static File Serving: Serves the pre-built web bundle (dist-web) with gzip compression and immutable caching headers for assets.
• API Routing: Handles ACP (Agent Client Protocol) requests, filesystem operations, and Git worktree management through HTTP and WebSocket endpoints.
• Agent Management: Manages the lifecycle of AI agents, including an "idle agent reaper" that disposes of processes with no active sessions or subscribers after 15 minutes.
• Security: Implements loopback guards and project boundary enforcement to ensure API calls remain within permitted directories.

Sources: src-tauri/src/server_main.rs, src-tauri/src/web/router.rs:18-40, CHANGELOG.md:10-25, src/renderer/lib/tests/parity-checklist.test.ts:985-1005

The sequence diagram illustrates how the termul-server mediates between the web client and backend agent processes.
Sources: src-tauri/src/web/router.rs, CHANGELOG.md:10-20, src/renderer/lib/tests/parity-checklist.test.ts:660-685

Parity and Adapters

To maintain consistency across targets, the renderer uses an adapter pattern. Feature modules import from facades that branch logic based on the detected context.

• API Facades: Files like terminal-api.ts or workspace-manifest-api.ts serve as seams that redirect calls to either tauri-*-api.ts or web-*-api.ts.
• Parity Testing: The project includes an automated parity checklist test suite (parity-checklist.test.ts) that verifies both Tauri and Web implementations exist for critical domains like Sessions, Terminals, and Filesystems.
• REST vs WS: While the Desktop target uses direct IPC, the Web target often splits data between REST (for one-shot actions like listCatalog) and WebSockets (for streaming data like terminal I/O and agent history).

Sources: src/renderer/lib/tests/parity-checklist.test.ts:15-50, src/renderer/lib/tests/parity-checklist.test.ts:500-550

Build Commands

The project defines specific scripts in package.json to generate artifacts for each target.

Target	Build Command	Output Path
Desktop (Tauri)	bun run build:tauri	src-tauri/target/release/bundle/
Web Client	bun run build:web	dist-web/
Standalone Server	cargo build --bin termul-server	target/release/termul-server

Sources: package.json:65-80, README.md:144-155

Termul's architecture ensures that developers and AI agents can interact with workspaces through a native desktop environment, a remote browser client, or a self-hosted server, maintaining functional parity across all three application targets.