Web Server Mode

Relevant source files

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

• web_server.design.md
• src-tauri/src/web_server.rs
• src/lib/apiAdapter.ts
• src/components/StreamMessage.tsx
• src/i18n/locales/en.json

Introduction

Web Server Mode is a specialized execution state for the Opcode application that enables access to Claude Code sessions through web browsers and mobile devices. Unlike the standard Tauri desktop environment, this mode hosts a Rust-based Axum server to provide a REST API and WebSocket interface, mirroring the desktop app's core functionalities while overcoming environment-specific constraints.
Sources: web_server.design.md:5-10, src-tauri/src/web_server.rs:608-613

The architecture allows the frontend to operate in a "Web Mode" by utilizing DOM events and standard HTTP/WebSocket protocols instead of Tauri-specific IPC (Inter-Process Communication). This is achieved through a unified API adapter that detects the environment and routes commands to either Tauri invoke calls or the web server's endpoints.
Sources: src/lib/apiAdapter.ts:10-53, web_server.design.md:23-40

System Architecture

The Web Server Mode utilizes a three-tier architecture to bridge the browser UI with the underlying Claude binary execution.

The diagram shows the communication flow from the React frontend through the Axum server to the spawned Claude subprocess.
Sources: web_server.design.md:12-21, src-tauri/src/web_server.rs:567-606

Environment Detection

The apiAdapter.ts module handles the logic for determining whether the application should use Tauri-specific commands or standard web protocols. It checks for Tauri-specific indicators like window.__TAURI__ or the User Agent string.
Sources: src/lib/apiAdapter.ts:31-53

Backend Implementation (src-tauri/src/web_server.rs)

The backend is built using the Axum framework and manages asynchronous tasks for Claude execution.

Key Components

• AppState: A shared state containing a HashMap of active WebSocket sessions, using thread-safe Arc<Mutex<...>> wrappers.
• WebSocket Handler: Manages real-time bidirectional communication, spawning a dedicated task for each Claude command execution.
• Claude Execution Functions: execute_claude_command, continue_claude_command, and resume_claude_command handle the spawning of the claude subprocess with specific flags like --output-format stream-json and --dangerously-skip-permissions.
  Sources: src-tauri/src/web_server.rs:55-70, src-tauri/src/web_server.rs:200-260, src-tauri/src/web_server.rs:360-385

REST API Endpoints

Endpoint	Method	Description
/api/projects	GET	Lists discovered Claude projects.
/api/projects/{project_id}/sessions	GET	Retrieves session history for a specific project.
/api/settings/claude/version	GET	Returns the mock status for web server mode.
/api/sessions/execute	GET	Stub for direct execution (redirects to WS).
/api/sessions/{sessionId}/cancel	GET	Placeholder for session cancellation.
/ws/claude	WS	Main entry point for streaming Claude execution.
Sources: src-tauri/src/web_server.rs:567-606, src/lib/apiAdapter.ts:143-228

Communication Protocol

WebSocket messages follow a structured JSON format to ensure compatibility between the Rust backend and TypeScript frontend.

Request Structure

{
  "command_type": "execute | continue | resume",
  "project_path": "/absolute/path/to/project",
  "prompt": "User instruction",
  "model": "claude-3-5-sonnet-20241022",
  "session_id": "optional-uuid"
}

Sources: web_server.design.md:46-54, src-tauri/src/web_server.rs:72-79

Response Stream

The server streams different message types to indicate the status of the background process:

• start: Indicates the process has been spawned.
• output: Contains a line of output from the Claude process (often parsed as a sub-JSON object).
• completion: Signals the process has finished successfully or with an error.
• error: Reports failures in spawning or parsing the request.
  Sources: web_server.design.md:56-63, src-tauri/src/web_server.rs:260-300

Frontend Integration

Stream Processing Logic

The frontend uses the StreamMessage and ToolWidgets components to render the raw data received over WebSockets. Because Web Server Mode sends JSON-formatted output, the frontend must handle these messages appropriately.

Event Mapping

In Web Mode, the application replaces Tauri's listen system with standard DOM CustomEvent listeners.

• claude-output: Dispatched whenever new content is received from the stream.
• claude-complete: Indicates the session has ended.
• claude-error: Reports connection or execution failures.
  Sources: src/lib/apiAdapter.ts:300-350, web_server.design.md:41-44

Configuration and Deployment

Binary Discovery

The server attempts to locate the Claude binary in the following order:

1. Bundled binary: src-tauri/binaries/claude-code-x86_64-unknown-linux-gnu
2. System PATH: claude, claude-code
3. Standard locations: /usr/local/bin/claude, /opt/homebrew/bin/claude, etc.
   Sources: src-tauri/src/web_server.rs:23-53

Build Commands

Web Server Mode can be initialized using specific build scripts defined in the project:

• Development: nix-shell --run 'just web' builds the frontend and starts the Rust server on port 8080.
• Access: The server binds to 0.0.0.0 to allow external access from devices on the same network.
  Sources: web_server.design.md:86-90, src-tauri/src/web_server.rs:608-610

Current Limitations

• Session Isolation: As of the current design, the backend dispatches generic events (claude-output) instead of session-scoped events (claude-output:${sessionId}), which may cause interference in multi-session environments.
• Process Cancellation: The /api/sessions/{sessionId}/cancel endpoint is currently a stub and does not terminate the underlying OS process.
• Stderr Capture: Current implementation focuses on stdout; error streams from the Claude binary may not be fully captured in the WebSocket stream.
  Sources: web_server.design.md:126-155, src-tauri/src/web_server.rs:188-195

Conclusion

Web Server Mode provides a flexible alternative to the Opcode desktop application, enabling mobile and remote workflows. By abstracting the differences between Tauri IPC and standard WebSockets through the apiAdapter, Opcode maintains a consistent UI experience across different platforms while providing robust debugging and tracing capabilities for developers.
Sources: web_server.design.md:104-124, src/i18n/locales/en.json:600-650