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, decoupled egress firewall control, and signed inter-agent communication. Verified by 853 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. The chat surface includes the OpenClaw-style composer, multi-attachment previews, dynamic slash commands, new/export/send/queue/stop controls, input history, thread search, pins, hidden-message recovery, queue notices, a side thread panel, and realtime Talk controls with non-destructive unavailable states.
• 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 real Hermes CLI installs and delegate turns through hermes chat -q ... --quiet, preserving NyxClaw's normalized runtime event contract. Supports Hermes model/provider, toolsets, skills, max-turns, worktree, checkpoints, permission-bypass, and native Hermes session resume IDs.
• 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, inspect blocked egress events, and test the decoupled egress firewall layer
• NyxSearch — Command palette with fuzzy search across sessions and settings

Advanced OpenClaw Features

A suite of high-fidelity, operator-grade features for staging, debugging, and executing advanced OpenClaw agent policies:

1. Unified Skill Store / Discovery Interface — A visual catalog to auto-discover local Python and MCP skills. Operators can toggle execution permission profiles (Auto-Approve, Ask Operator, Block) on a granular per-tool level.
2. Custom Agent Factory — An interactive visual builder for creating bespoke OpenClaw-compatible agent profiles. Configure friendly name, emoji, workspace paths, custom system prompts, temperature thresholds, model targets, and bound capabilities with direct JSON schema exports.
3. Visual Credential & OAuth Vault — Streamlined, secure browser-based OAuth flows directly writing authorized tokens to local ~/.openclaw/config.json via Nyx Vault proxy boundaries, eliminating raw credential leaks in console logs.
4. Thinking Budget Controller & Streaming Trace — Operator-level control over agent reasoning limits directly in the Chat Header, paired with collapsible, high-fidelity <think> reasoning traces in chat message bubbles.
5. Dynamic Sandbox Egress Shield — A live telemetry cockpit visualizing blocked directory traversals and outbound SSRF boundary escapes (such as link-local metadata queries) with one-click whitelisting overlays ("Allow Path" and "Trust IP Address").

These features ship in the existing Settings → Behavior and Settings → System surfaces. The first-run onboarding wizard ships a chat-first install path; advanced surfaces are discoverable from the persistent sidebar after setup.

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.

Runtime Center (opt-in via NYXCLAW_RUNTIME_CENTER=1) adds a unified cockpit at the top of the Control sidebar — OpenClaw, Hermes, Ollama / LM Studio, and Cloud / API lanes side by side, with health chips and inline edits where you own the configuration. Source-checkout docs: docs/RUNTIME-CENTER.md.

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 |

Optional MCP tools (disabled by default): when NYXCLAW_WEB_SEARCH_MCP=1, NyxClaw also exposes web_search and web_fetch through the same guard/defuser pipeline used by the web-search route.

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.

Hermes feature tracking: this adapter invokes the external Hermes CLI only. Future feature-port candidates from the Hermes audit include check-gated tool registries, a shared command registry, MCP client/server surfaces, cron and webhook automation, session search, curator-backed skill provenance, delegation observability, and background process notifications. Hermes Agent is MIT-licensed by Nous Research; any ported feature should preserve that attribution.

Linux, macOS, or NyxClaw running inside 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-native NyxClaw should use a Windows-native hermes command or set NYXCLAW_HERMES_BIN / HERMES_BIN to the exact executable. Hermes 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.

Open-internet support status

• Local desktop (supported): the default; loopback-only.
• Docker on a private network (supported): NYXCLAW_DOCKER=1 binds 0.0.0.0; intended for trusted home LAN / private VPN segments.
• Public internet, trusted authenticated users (supported via opt-in): requires NYXCLAW_PUBLIC_MODE=1 plus a configured auth provider (OIDC or reverse-proxy). The agent-execution-safety waves are complete — the in-host local agent reaches sandbox/egress/CPU/mem/approval parity with the delegated runtimes, and delegating never weakens a runtime's native guarantees. See docs/INTERNET-DEPLOYMENT.md (included with the package) for the supported topology, reverse-proxy contract, env reference, and IR runbook, and docs/open-internet-launch-readiness-assessment-2026-05-28.md in the source repository for the GO checklist. Threat model: trusted authenticated users, not the hostile public — DDoS/bot mitigation is the proxy's job.

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 docs/HERMES-RUNTIME.md (included with the package) for the exact gates and cleanup behavior.

Chat visual smoke is also source-checkout-only:

npm run build
npm run smoke:chat-visual

The smoke launches a temporary localhost NyxClaw server, drives the chat UI with Playwright, and captures screenshots under output/playwright/chat-visual/ for desktop expanded, sidebar minibar, attachment preview, slash menu, queue/stop, thread side panel, and Talk-unavailable fallback states. Set NYXCLAW_SMOKE_URL=http://127.0.0.1:<port> to drive an existing server, or NYXCLAW_SMOKE_TALK_REAL=1 to attempt the installed OpenClaw Gateway Talk path instead of the deterministic unavailable fixture.

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

Browser              CLI                  MCP Clients
localhost:47291      nyxclaw chat/ask     (Claude Code, Cursor)
   |                    |                    |
   | REST + SSE         | direct             | stdio
   v                    v                    v
NyxClaw Server ----> NyxClaw Guard + Proxy
(Express 5 + Vite)      |
        +---------------+------------------+----------------+
        |               |                  |                |
        v               v                  v                v
  OpenClaw Gateway   Local engines     Cloud/API        Memory Store
  localhost:18789    Ollama :11434     providers
        |            LM Studio :1234   (explicit opt-in)
        v
  OpenClaw Session Stores
  (read-only JSONL via discovery)

• 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 — for Claude Code / Cursor integration) | | 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 853-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 by default and enforces multiple defense layers from input to output. All layers are verified by an 853-test automated red-team suite covering the OWASP LLM Top 10, multi-agent security, and traditional vulnerability classes. Outbound network traffic is protected by a decoupled egress firewall service, ensuring secure external network calls without in-process agent overhead.

See SECURITY.md (included with the package) for the vulnerability disclosure policy.

API Documentation

The primary REST API is documented in OpenAPI 3.1 (docs/openapi.yaml, included with the package) 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

• Localhost-first, single-user by default. Multi-user or networked deployment exists only through the documented opt-ins above (NYXCLAW_DOCKER=1 for private networks, NYXCLAW_PUBLIC_MODE=1 behind an auth provider for trusted authenticated users) — never as the default posture.
• No hosted/cloud deployment path. By design. NyxClaw never hosts your agents in the cloud; 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 (included with the package)
• SECURITY.md — security policy and responsible disclosure (included with the package)
• docs/openapi.yaml — OpenAPI 3.1 specification (included with the package)
• docs/HERMES-RUNTIME.md — Hermes Agent runtime setup and security posture (included with the package)

License

MIT