NyxClaw

Local-first control surface for OpenClaw, Hermes Agent, local LLMs, and explicit Cloud/API chat lanes.

NyxClaw's server binds to localhost and serves the browser UI there. Local-engine traffic stays on the machine, and agent-runtime traffic stays on loopback or the local shell boundary. Prompts are sent off-machine only when a selected NyxClaw lane or the underlying runtime setup uses a Cloud/API provider.

NyxClaw's boundary is deliberate: it does not embed a competing agent runtime. OpenClaw remains the default agentic runtime, and Hermes Agent can be selected as a peer runtime when discovered. NyxClaw provides the browser UI, local model proxying, guarded API surface, memory/session UX, and cockpit-style visibility; the selected runtime provides the agent service and tool execution layer.

Why NyxClaw

Local-first. No telemetry and no required cloud account. Local-engine and gateway traffic stays on localhost; Cloud/API egress is explicit through NyxClaw or inherited from the user's OpenClaw configuration.

Agent-runtime aware. NyxClaw keeps OpenClaw as the default runtime while also supporting Hermes Agent through the same guarded runtime adapter surface. Runtime selection, status, traces, and delegation stay inside NyxClaw's localhost security model.

Security-first. Defense-in-depth from input to output — prompt injection defense, approval-gated tools, credential isolation, egress control, and signed inter-agent communication. Verified by 663 automated red-team tests.

Memory-augmented. NyxClaw remembers. A trust-aware persistent memory store accumulates knowledge across sessions and automatically enriches conversations with relevant context.

MCP-native. Use NyxClaw as a tool server for Claude Code, Cursor, Windsurf, or any MCP-compatible AI assistant. Your configured NyxClaw stack becomes accessible through a guarded interface.

Honest scope. NyxClaw does a focused set of things well. See Limitations for what it deliberately does not do.

Features

Web Interface

• Chat Interface — Switch among local LLMs, agent runtimes, and Cloud/API chat lanes with streaming where the selected provider supports it
• OpenClaw Session Hub — Discover OpenClaw sessions read-only, group them by agent/source folder, search across metadata, open transcript details, continue with agentId + sessionId, and refresh from transcript files returned by OpenClaw
• OpenClaw Gateway Integration — Connect directly to the local OpenClaw gateway for agent turns, status, and structured traces
• Hermes Agent Runtime — Auto-discover Hermes native or WSL installs and delegate agent turns through the same normalized runtime event contract
• Workflows Hub — View Local, OpenClaw, and Hermes Kanban, Goals, Cron, and Dreaming surfaces side by side. Local kanban, goals, and dreams are durable NyxClaw records; local workflow writes, Hermes kanban actions, and runtime-backed cron actions use dry-run approval tokens before execution. Capability cards label read-only, approval, and dry-run posture. Kanban, Cron, and Dreaming are also first-class main-sidebar destinations for direct access. Raw task prompts/payloads are omitted.
• Agent Cockpit — See OpenClaw-backed activity, workspace state, skills, memory, and structured trace cards in the browser
• Local Model Proxy — Keep browser traffic same-origin while NyxClaw proxies chat, embedding, and summary calls to LM Studio or Ollama
• Cloud/API Relay — Route selected API-key providers through NyxClaw's guarded router with history, system prompt, and session metadata preserved
• Dashboard — Overview of agent activity, session stats, and system status
• Session Management — Mutable NyxClaw conversations plus read-only OpenClaw sessions; mutation/export actions stay NyxClaw-only until safe OpenClaw APIs are implemented
• Model Catalog — Browse the curated local/cloud model catalog with VRAM estimates, and install Ollama models with progress bars
• Settings Console — Configure local engines, read provider-owned model status, select agent runtime behavior, manage persona/memory/rules/channels, switch appearance, configure storage, enter API keys, and inspect provenance
• Collapsible Main Sidebar — Collapse the desktop main sidebar into an icon-only minibar after choosing a workspace, preserving direct access to Chat, Workflows, Memory, API Keys, Skill Sources, Security, and other surfaces
• Skill Sources — Inspect and edit the unified NyxClaw/OpenClaw skill inventory, including SKILL.md content and per-skill config
• Security Panel — View active protections and test the firewall layer
• NyxSearch — Command palette with fuzzy search across sessions and settings

Settings Surface

The Settings page is grouped into three live sections:

• Engine: Local Engines points NyxClaw at LM Studio or Ollama and lets you test/rescan models; Model Params shows read-only provider-owned status, selected model, detected context, loaded context, and loaded-model inventory.
• Behavior: Agent controls autonomy presets, agent mode, OpenClaw/Hermes runtime selection, coding-intent routing, danger-zone capabilities, permission resets, and localhost gateway security. AI Persona manages the system prompt and Nyx persona preset. Memory filters and edits workspace memories. Rules Engine manages enforcement rules, and Channels manages route toggles plus webhook URLs.
• System: Appearance switches Void/Daylight themes, Storage chooses browser localStorage or server-backed sessions plus paths, API Keys stores cloud provider keys locally, and Provenance verifies the signed event ledger.

The main sidebar promotes Memory and API Keys directly, while the Settings page remains the full grouped console. The sidebar's Settings section also includes Skill Sources for the unified skill inventory/editor and Security for active protection status.

Memory intentionally remains dual-access: the sidebar keeps frequent recall and edits one click away, while Settings keeps the full Behavior console grouped for operators who are already tuning agent policy. To roll back the promoted sidebar surfaces at build time, set VITE_NYXCLAW_PROMOTED_SIDEBAR_SURFACES=0; the unified Workflows and Settings entries remain available.

Terminal CLI

npx -y nyxclaw@latest install                     # one-line bootstrap
nyxclaw ask "summarize the OWASP LLM Top 10"      # one-shot query
git diff | nyxclaw ask "review this change" --json  # piped input
nyxclaw chat                                        # multi-turn REPL
nyxclaw chat --resume last                          # resume previous session
nyxclaw models catalog --tier lightweight            # browse model catalog
nyxclaw models install qwen3:14b                    # install with progress bar
nyxclaw memory add "I prefer Wednesday deploys."    # store a fact
nyxclaw memory search "deploy"                      # recall by keyword
nyxclaw start --daemon                              # background server
nyxclaw doctor                                      # environment health check
nyxclaw doctor --strict                             # CI-style warning failures
nyxclaw update --dry-run                            # preview latest package version
nyxclaw onboard                                     # interactive setup wizard

LLM-facing CLI commands run through the same guard chain as the web interface.

MCP Server

NyxClaw exposes 8 always-on tools via the Model Context Protocol:

| Tool | Description | | -------------------- | ------------------------------- | | nyx_ask | Send a guarded LLM query | | nyx_memory_search | Recall from trust-aware memory | | nyx_memory_add | Store a fact with trust scoring | | nyx_memory_stats | Memory store statistics | | nyx_sessions | List chat sessions | | nyx_session_export | Export session as Markdown | | nyx_models | Current model/provider config | | nyx_doctor | Environment health check |

Add to your Claude Code config:

{
  "mcpServers": {
    "nyxclaw": { "command": "nyxclaw-mcp" }
  }
}

Persistent Memory

NyxClaw's memory store persists knowledge across sessions with trust-aware retrieval:

• Trust scoring — entries ranked by provenance (user, agent, system)
• Biological decay — unused entries fade over time; recalled entries get reinforced
• Memory-augmented chat — relevant memories are automatically injected into conversations
• Workspace isolation — memories scoped per workspace

Agent Boundary Security

NyxClaw treats agent output, tool results, and recalled memory as untrusted at the boundary with OpenClaw:

• Scanned for injection before display, storage, or reuse
• Attributed with provenance (who said it, where it came from)
• Filtered through trust-aware memory policy before recall
• Signed with HMAC-SHA256 for NyxClaw-managed inter-agent envelopes

Quick Start

Recommended install mirrors OpenClaw's npm package flow. It does not require GitHub access to the NyxClaw repository. Node.js 24 LTS is the preferred runtime for new installs; NyxClaw still supports Node.js 22+. OpenClaw currently supports Node.js 22.14+ when you are on the older LTS path, and Hermes Agent's installer manages its own Python/Node support.

npx -y nyxclaw@latest install
nyxclaw onboard
nyxclaw start

nyxclaw install prepares NyxClaw only: it checks Node 22+, creates ~/.nyxclaw, runs a doctor summary, and leaves model downloads to explicit model commands. It does not mutate OpenClaw, install Hermes Agent, or pull local LLM weights.

Expected first-run output is a short checklist. Node.js and State should be green. Local LLM, OpenClaw, Hermes Agent, and Cloud/API can be yellow on a fresh machine; that means the optional backend is not configured yet, not that the package failed. The install still finishes as long as there are no red error rows. Run nyxclaw doctor any time for the full environment report.

Current platform verification:

• Windows 11 PowerShell: freshly tested with npm global install, .cmd shims, daemon start/status, doctor, LM Studio local chat, and OpenClaw relay.
• WSL2 / Linux: freshly tested with a clean npm install smoke and Unix-style global-bin layout.
• macOS: expected to work through the standard Node/npm/Homebrew path below, but not freshly tested by the maintainers because we do not currently have Mac hardware. Please treat macOS as beta until a real-device install report is available.

Update NyxClaw as you use it:

nyxclaw update --dry-run
nyxclaw update

nyxclaw update --dry-run checks the registry version without changing packages. nyxclaw update installs nyxclaw@latest globally. OpenClaw stays explicit: run nyxclaw update --openclaw only when you want NyxClaw to update OpenClaw too.

If you are starting fresh and want a second agent runtime next to OpenClaw, install Hermes Agent by Nous Research separately. NyxClaw can run Local, OpenClaw, Hermes Agent, and Cloud/API lanes side by side; Hermes is auto-discovered when installed.

Linux, macOS, or WSL2:

curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash
source ~/.bashrc    # or source ~/.zshrc
hermes setup
nyxclaw doctor

Windows users should prefer the WSL2 command above for the most battle-tested Hermes path. Hermes also offers a native Windows PowerShell installer as an early beta:

irm https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.ps1 | iex
hermes setup
nyxclaw.cmd doctor

If you are replacing an older global npm install manually:

npm uninstall -g nyxclaw
npm install -g nyxclaw@latest
nyxclaw install

If OpenClaw is not installed yet:

npm install -g openclaw@latest
openclaw onboard --install-daemon

Open the printed localhost URL for the web dashboard. The default is http://localhost:47291, and NyxClaw falls back through ports 47291-47299 when the default port is busy.

On startup, NyxClaw checks the local OpenClaw Gateway. If a healthy loopback Gateway is already running, NyxClaw reuses it. If OpenClaw is installed but the Gateway is down, NyxClaw starts the configured gateway port; the default is:

openclaw gateway run --bind loopback --port 18789

Set NYXCLAW_OPENCLAW_AUTOSTART=0 before nyxclaw start if you want to manage the OpenClaw Gateway yourself. If OpenClaw is not installed, NyxClaw still renders and can run local or Cloud/API chat flows after setup, but the OpenClaw session hub stays unavailable until OpenClaw is installed; gateway routing and the agent cockpit require a reachable OpenClaw Gateway.

Everyday commands:

nyxclaw start        # start the server
nyxclaw start --daemon
nyxclaw chat
nyxclaw doctor
nyxclaw migrate      # import an existing OpenClaw setup

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash
nvm install 24
npx -y nyxclaw@latest install
nyxclaw onboard
nyxclaw start

Status: expected path, not freshly tested by the maintainers on Mac hardware. NyxClaw ships a normal npm bin entry, so npm should create the nyxclaw command in the active global prefix on macOS the same way it does for other global CLI packages.

brew install node
node --version
npm --version
npx -y nyxclaw@latest install
nyxclaw onboard
nyxclaw start

If brew is not found in a new terminal, run the brew shellenv command that Homebrew printed during install. If nyxclaw is not found after a global npm install, add $(npm prefix -g)/bin to your shell startup file. Avoid running global npm installs with sudo; fix the Node/npm prefix instead. On Apple Silicon, Ollama and LM Studio can use Metal acceleration.

WSL2 is the recommended Windows path because it matches OpenClaw's strongest runtime path. From an elevated PowerShell:

wsl --install -d Ubuntu-24.04

Then open Ubuntu and use the WSL2 / Linux commands above.

Native PowerShell can still install the npm package. Use the .cmd shims below so a restrictive PowerShell execution policy cannot block npm's .ps1 shims:

# Requires Node.js 24 LTS recommended, Node.js 22+ minimum.
winget install OpenJS.NodeJS.LTS
node --version
npm --version
npx.cmd -y nyxclaw@latest install
nyxclaw.cmd onboard
nyxclaw.cmd start

If nyxclaw.cmd is not found after a global npm install, run npm config get prefix, add that directory to your user PATH without a \bin suffix, then open a new PowerShell window.

git clone https://github.com/aleks7732/NyxClaw.git
cd NyxClaw
npm install
npm run cli -- install --no-global
npm run cli -- start

Source checkout commands:

npm run cli -- onboard
npm run cli -- start
npm run cli -- chat
npm run cli -- doctor

The public install path above is the path for normal users; source checkout requires repository access.

Requirements

• Node.js 24 LTS recommended; Node.js 22+ supported
• OpenClaw installed for the OpenClaw session hub; a reachable OpenClaw Gateway is required for gateway routing and agent cockpit traces
• Ollama and/or LM Studio for local inference, or a configured Cloud/API provider for remote inference

Already using OpenClaw? Run nyxclaw onboard or nyxclaw migrate to preview/import supported config, API keys, agent definitions, workspace files, and a non-copying session index. Skills are discovered from NyxClaw and OpenClaw directories where available.

Setting Up Local LLMs

curl -fsSL https://ollama.com/install.sh | sh
ollama serve
ollama pull qwen3:8b

Browse additional models at ollama.com/library.

Install LM Studio from lmstudio.ai, then enable the local server and load a model. NyxClaw connects automatically on port 1234.

Measured LM Studio tool-use results from WSL2, May 2026:

• google/gemma-4-31b: strongest default result; completed 10 same-turn tool calls and 20 sequential tool steps in the local probe.
• google/gemma-4-26b-a4b: passed the same ceiling, with slightly less confidence than 31B from the comparative pass.
• qwen/qwen3.6-35b-a3b: strong sequential behavior, but needs Qwen think-output handling or an empty-think prefill to avoid surfacing <think>...</think> blocks.

The local QC pass was a WSL2 + LM Studio snapshot from May 2026, not a general benchmark; re-check loaded model behavior on your own hardware before treating any model as a default.

Remote LLMs via LM Link (Tailscale)

LM Link lets you run LM Studio on a GPU machine and use it from a lighter laptop over Tailscale. NyxClaw treats the linked endpoint as LM Studio-compatible; run nyxclaw doctor to verify connectivity.

Uninstall

Three lines per shell. Run each one, press Enter. An error like "cannot find path" / "No such file or directory" means nothing was there — skip to the next line.

macOS, Linux, or WSL2:

npm uninstall -g nyxclaw
rm -rf ~/.nyxclaw
cd ~ && rm -rf NyxClaw

Windows PowerShell:

npm uninstall -g nyxclaw
Remove-Item -Recurse -Force "$HOME\.nyxclaw"
cd ~ ; Remove-Item -Recurse -Force NyxClaw

That removes: the global nyxclaw command, the config + memory + sessions at ~/.nyxclaw/, and the repo folder itself. Leaves OpenClaw / Ollama / LM Studio untouched.

Troubleshooting

nyxclaw doctor
nyxclaw update --dry-run

Environment health check: Node version, port, config, auth token, Ollama, LM Studio, OpenClaw, Hermes Agent, runtime workflow smoke mode, and disk space. Each failure includes an actionable hint.

Workflow validation defaults to non-mutating API smoke. From a NyxClaw source checkout (not a global npm install):

npm run smoke:runtime-workflows

Real workflow smoke writes require explicit env gates and only use disposable nyxclaw-smoke-* fixtures. See Hermes Runtime for the exact gates and cleanup behavior.

Port in use? NyxClaw tries ports 47291-47299 automatically. Override with NYXCLAW_PORT=<port>.

Managing OpenClaw yourself? Set NYXCLAW_OPENCLAW_AUTOSTART=0 before starting NyxClaw. The Gateway must still bind loopback; NyxClaw never connects to an external OpenClaw host.

Architecture

graph TD
    Browser["Browser<br/><code>localhost:47291</code>"]
    CLI["CLI<br/><code>nyxclaw chat/ask</code>"]
    MCP["MCP Clients<br/><small>Claude Code, Cursor</small>"]
    Server["NyxClaw Server<br/><small>Express 5 + Vite</small>"]
    Guard["NyxClaw Guard + Proxy"]
    OpenClaw["OpenClaw Gateway<br/><small>localhost:18789</small>"]
    SessionStores["OpenClaw Session Stores<br/><small>read-only JSONL via discovery</small>"]
    Memory["Memory Store"]
    Ollama["Ollama<br/><small>localhost:11434</small>"]
    LMStudio["LM Studio<br/><small>localhost:1234</small>"]
    Cloud["Cloud/API Providers<br/><small>explicit opt-in</small>"]

    Browser -->|"REST + SSE"| Server
    CLI -->|"direct"| Guard
    MCP -->|"stdio"| Guard
    Server --> Guard
    Guard -->|"OpenClaw turns"| OpenClaw
    Guard -->|"session discovery/detail"| SessionStores
    OpenClaw --> Ollama
    OpenClaw --> LMStudio
    OpenClaw --> SessionStores
    Guard -->|"local chat / embeddings"| Ollama
    Guard -->|"local chat / embeddings"| LMStudio
    Guard -->|"cloud chat when selected"| Cloud
    Guard --> Memory

    style Browser fill:#C15F3C,stroke:#C15F3C,color:#fff
    style CLI fill:#C15F3C,stroke:#C15F3C,color:#fff
    style MCP fill:#C15F3C,stroke:#C15F3C,color:#fff
    style Server fill:#1a1a1a,stroke:#C15F3C,color:#F5F5DC
    style Guard fill:#1a1a1a,stroke:#C15F3C,color:#F5F5DC
    style OpenClaw fill:#1a1a1a,stroke:#C15F3C,color:#F5F5DC
    style SessionStores fill:#1a1a1a,stroke:#444,color:#F5F5DC
    style Memory fill:#1a1a1a,stroke:#444,color:#F5F5DC
    style Ollama fill:#1a1a1a,stroke:#444,color:#F5F5DC
    style LMStudio fill:#1a1a1a,stroke:#444,color:#F5F5DC
    style Cloud fill:#1a1a1a,stroke:#444,color:#F5F5DC

• Frontend: React 19, Tailwind CSS 4
• Backend: Express 5, TypeScript, ESM
• CLI: Global nyxclaw binary (compiled runtime)
• MCP: @modelcontextprotocol/sdk (stdio transport)
• Auth: Auto-generated localhost-only bearer tokens
• Validation: Zod parse-time schemas for provider API responses

Scripts

| Command | Description | | ------------------------------- | ---------------------------------------------------------- | | nyxclaw install | Bootstrap NyxClaw state + host check | | nyxclaw start | Start the NyxClaw server | | nyxclaw start --daemon | Start in background | | nyxclaw chat | Multi-turn REPL with memory recall | | nyxclaw ask <prompt> | One-shot guarded LLM query | | nyxclaw mcp | Start MCP server (stdio) | | nyxclaw doctor | Environment health check | | nyxclaw doctor --strict | Fail on warnings for CI/preflight | | nyxclaw update | Install nyxclaw@latest globally | | nyxclaw onboard | Interactive setup wizard | | nyxclaw models list | List installed models | | nyxclaw memory search <query> | Search persistent memory | | nyxclaw test | Source checkout only: run 663-test security red team suite | | nyxclaw test --unit | Source checkout only: run unit tests | | nyxclaw build | Source checkout only: production build | | nyxclaw typecheck | Source checkout only: TypeScript type checking | | nyxclaw lint | Source checkout only: ESLint | | nyxclaw format --check | Source checkout only: Prettier format check | | nyxclaw audit | Source checkout only: npm audit |

Security

NyxClaw binds to 127.0.0.1 only and enforces multiple defense layers from input to output. All layers are verified by a 663-test automated red-team suite covering the OWASP LLM Top 10, multi-agent security, and traditional vulnerability classes.

See SECURITY.md for the vulnerability disclosure policy.

API Documentation

The primary REST API is documented in OpenAPI 3.1 and served interactively at /api/docs on the active NyxClaw port, normally http://localhost:47291/api/docs.

Agent runtime routes live under /api/runtimes/* and expose OpenClaw/Hermes status, skills, workflow inventory/details/actions, local workflow records, and normalized SSE agent turns.

Limitations / Non-Goals

• Single-user, localhost server. Not designed for multi-user or networked deployments.
• No hosted/cloud deployment path. By design. Exposing NyxClaw to the internet is unsupported; Cloud/API providers are outbound inference lanes selected by the user, not NyxClaw hosting.
• Agent runtimes stay external. NyxClaw integrates with OpenClaw and Hermes Agent; it does not replace their runtime or tool execution layers.
• No built-in model serving. NyxClaw connects to local inference engines such as Ollama or LM Studio, or to configured Cloud/API providers.

Links

• npm package — public install artifact
• CHANGELOG.md — release notes
• SECURITY.md — security policy and responsible disclosure
• API Docs — OpenAPI 3.1 specification
• Hermes Runtime — Hermes Agent runtime setup and security posture

License

MIT