DOCSEARCHbyAlgolia
Submit Docs

openclaw-nerve

repository·master·Indexed 21 days ago

https://github.com/daggerhashimoto/openclaw-nerve

A high-level cockpit and web interface for OpenClaw agents, providing fleet control, workspace management, and real-time observability. It supports chat, voice input, TTS, and agent monitoring in the browser. Key features include support for TTS, chart, and kanban markers for interactive agent responses, as well as a dedicated one-command installer and update CLI.

Tokens
52.6K
Snippets
149
Records
246
Agent score
73%

What's inside openclaw-nerve

  1. Understand the Nerve Frontend Architecture

    master

    The Nerve frontend is built with React 19, TypeScript, Vite, and Tailwind CSS v4. The application follows a modular feature-based structure where each feature (e.g., chat, sessions, workspace) contains its own components, hooks, and business logic.

    Global state is managed through a hierarchy of React Context Providers, which are nested in a specific dependency order to ensure data flows correctly from the connection layer up to the UI components.

  2. Understand the Backend Architecture and Stack

    master

    The Nerve backend is built using the Hono web framework and TypeScript, running on Node.js ≥22. The system is structured into an entry point, a middleware stack, a set of API routes, core libraries, and specialized services.

    Core Entry Points

    • server/index.ts: Responsible for starting the HTTP and HTTPS servers, setting up the WebSocket proxy, initializing file watchers, and handling graceful shutdowns.
    • server/app.ts: Defines the Hono application, including the middleware stack, route mounting, and static file serving with SPA fallback.

  4. Access Nerve documentation and setup guides

    master

    The docs/ directory contains the primary technical documentation for Nerve. Use the following entry points to navigate the system:

    Core Documentation

    • Architecture: Understand the codebase structure and system design.
    • Configuration: Learn about .env setup, authentication, access modes, TTS providers, and UI settings.
    • API: Reference backend endpoints and their behaviors.
    • Security: Review the threat model and hardening notes.
    • Troubleshooting: Find solutions for common failures and fixes.
    • Updating: Understand the built-in updater flow and rollback procedures.
    • Installer Steps: See a breakdown of what the installer performs.
    • Agent Markers: Learn how to use TTS, charts, and kanban markers.

    Setup and Deployment

    • AI Agent Setup: Specific instructions for configuring AI agents.
    • Nerve Agent Install Contract: Detailed requirements and expectations for the installation process.
    • Deployment Scenarios:
      • Single Machine: Run everything on one machine.
      • Hybrid Cloud/Local: Use a cloud Gateway with Nerve running on your laptop.
      • Full Cloud: Run both Nerve and the Gateway in the cloud.
    • Tailscale Integration: How to add Tailscale to an existing Nerve installation.

  5. Nerve security and network binding

    master

    By default, Nerve binds to 127.0.0.1 (localhost), meaning it is only accessible from the local machine.

    To expose Nerve to your network, set the HOST environment variable to 0.0.0.0. When bound to a network, Nerve uses built-in password authentication to protect the UI and endpoints. Security features include:

    • Signed cookies for sessions.
    • Hashed password storage.
    • Authenticated WebSocket upgrades.
    • Server-side gateway token injection for trusted connections.

  6. Understand the Nerve architecture and system boundaries

    master

    Nerve is a local-first web interface for OpenClaw that provides chat, voice, and workspace tooling. To use it effectively, you must understand that it operates across three distinct boundaries. The level of functionality available to you depends on whether the Nerve server has direct access to the agent's workspace filesystem.

    The Three Boundaries

    1. Browser ↔ Nerve server: The connection between your web browser and the Nerve backend (Hono/Node).
    2. Nerve server ↔ OpenClaw gateway: The connection between the Nerve backend and the OpenClaw gateway (typically via WebSocket).
    3. Nerve server ↔ agent workspace filesystem: The direct access the Nerve server has to the files used by the agent.

    Deployment Parity

    • Full Parity (Deployment A): Occurs when the Nerve server has local access to the same workspace filesystem as the gateway-backed agent. This enables the full file browser, mutations, and local watchers.
    • Partial Fallback (Deployment B/Split-host C): Occurs when the Nerve server cannot access the workspace directory locally. In this mode, the UI falls back to using Gateway RPC for specific routes, resulting in a constrained experience.
    ┌──────────────────────────────────────────────────────────────────┐
│  Browser (React SPA)                                             │
│                                                                  │
│  ┌──────────┐  ┌──────────┐  ┌───────────┐  ┌────────────────┐  │
│  │ ChatPanel│  │ Sessions │  │ Workspace │  │ Command Palette│  │
│  └────┬─────┘  └────┬─────┘  └─────┬─────┘  └────────────────┘  │
│       │              │              │                             │
│  ┌────┴──────────────┴──────────────┴────────────────────────┐   │
│  │           React Contexts (Gateway, Session, Chat, Settings)│   │
│  └────────────────────────────┬──────────────────────────────┘   │
│                               │ WebSocket (/ws proxy)            │
└───────────────────────────────┼──────────────────────────────────┘
                                │
┌───────────────────────────────┼──────────────────────────────────┐
│  Nerve Server (Hono + Node)   │                                  │
│                               │                                  │
│  ┌────────────────────────────┴─────────────┐                    │
│  │         WebSocket Proxy (ws-proxy.ts)     │                   │
│  │  - Intercepts connect.challenge               │                   │
│  │  - Injects device identity (Ed25519)      │                   │
│  └────────────────────────────┬──────────────┘                   │
│                               │                                  │
│  ┌───────────────┐  ┌────────┴─────┐  ┌───────────────────────┐ │
│  │ REST API      │  │ SSE Stream   │  │ Static File Server    │ │
│  │ /api/*        │  │ /api/events  │  │ Vite build → dist/    │ │
│  └───────┬───────┘  └──────────────┘  └───────────────────────┘ │
│          │                                                       │
│  ┌───────┴──────────────────────────────────────────────────┐    │
│  │ Services: TTS (OpenAI, Replicate, Edge), Whisper,       │    │
│  │ Claude Usage, TTS Cache, Usage Tracker                   │    │
│  └──────────────────────────────────────────┬────────────────┘    │
└──────────────────────────────┬───────────────────────────────────┘
                               │ HTTP / WS
                    ┌──────────┴───────────────┐
                    │  OpenClaw Gateway         │
                    │  (default:                │
                    │   ws://127.0.0.1:18789,   │
                    │   but may be remote)      │
                    └──────────────────────────┘

  7. Understand Workspace Scoping Rules

    master

    Nerve uses a hierarchical workspace scoping model. The workspace scope (which includes Memory, Config, Skills, and file-browser state) is derived from the owning top-level agent.

    Scoping Rules:

    • Root sessions: Use their own top-level agent as the workspace scope.
    • Subagents and cron-run views: Inherit the workspace of their owning top-level agent.
    • Child sessions: Do not create a separate workspace scope; they stay within the parent's scope.
    • Global items: Crons and Kanban remain global and do not switch when the workspace agent changes.
    • Dirty files: Cross-agent dirty file prompts only trigger when the owning top-level agent is changed.

  8. Compare Nerve Cloud Deployment Topologies

    master

    Choosing between Same-Host and Split-Host deployment depends on whether you require full workspace control or just chat capabilities.

    FeatureSame Host (Recommended)Split Hosts
    Nerve ↔ GatewayLocalRemote
    Nerve ↔ WorkspaceLocalUsually Remote
    ResultFull feature parity (Files, Memory, Config, Previews)Partial parity (Chat works, but workspace features degrade)

    When to use Split-Host: Only when infrastructure requires separation and you can accept limited file browser capabilities or provide a shared filesystem mount.

  9. Understand the limitations of remote workspace fallback mode

    master

    If the Nerve server cannot access the agent's workspace filesystem directly, the application enters a partial fallback mode. In this mode, many workspace features are restricted or unavailable. Use this knowledge to troubleshoot why certain UI elements (like file moving or image previews) are not working.

    Feature Parity Comparison

    FeatureLocal Workspace (Full Parity)Remote Workspace (Fallback Mode)
    Config Files (SOUL.md, TOOLS.md, etc.)Normal local read/writeGateway fallback read/write (allowlisted files only)
    File TreeFull nested treeTop-level listing only
    Text FilesAny allowed path in workspaceTop-level text files only
    File Operations (Rename, Move, Trash)Supported501 Not supported for remote workspaces
    Previews (Images/Binary)SupportedNot available
    Memory DataFull MEMORY.md + recent daily filesLimited MEMORY.md fallback; daily files are local-only
    Skills TabLocal openclaw skills listNo dedicated gateway file fallback

    Note: If you require full workspace functionality, ensure the Nerve server has direct filesystem access to the agent's workspace.

  10. Identify when an agent requires manual confirmation

    master

    While local repair and local setup can be automated, agents must ask for confirmation before performing any action that changes exposure, trust, or install ownership.

    Actions requiring consent:

    • Installing OpenClaw.
    • Exposing Nerve beyond localhost (e.g., LAN access, public internet exposure).
    • Setting up reverse proxies or Tailscale.
    • Destructive actions (reinstalling, replacing, or deleting existing installs).
    • Changing remote gateway authentication or allowlists.
    • Making cloud-hosted assumptions that change the security posture.

  11. Understand the Marker Processing Pipeline

    master

    When an agent response is received, Nerve processes markers in a specific sequence to transform raw text into a rich UI. The final output shown to the user is the 'cleaned' text with all markers stripped.

    Processing Order:

    1. TTS extraction: [tts:...] markers are extracted and queued for audio.
    2. Chart extraction: [chart:{...}] markers are extracted and attached to the message object.
    3. Image extraction: Inline image references are extracted.
    4. Markdown rendering: Remaining text is rendered as markdown with syntax highlighting.
    5. Tool result rendering: Tool call sentinels are converted to collapsible <details> elements.

  12. How the Nerve Update Process Works

    master

    The update process follows a strict lifecycle to ensure stability. If any stage fails after the snapshot is taken, the updater attempts an automatic rollback.

    Update Flow: lock → preflight → resolve → confirm → snapshot → git checkout → npm install + build → restart → health check → done

    Snapshots: Before changes are made, the updater saves the current git ref, the version from package.json, and a SHA-256 hash of .env (along with a timestamped backup of .env). Snapshots are stored in ~/.nerve/updater/. Note that .env is only backed up and is never overwritten.

    Rollback: Rollback restores the snapshot ref, cleans node_modules, rebuilds, and restarts the service. It can be triggered automatically on failure or manually via --rollback.

    Health Checks: After a restart, the updater polls GET /health (must return 2xx) and GET /api/version (must match the target version) using exponential backoff (2s, 4s, 8s) up to a 60-second deadline.