neruva-control 0.3.3

Local daemon for Neruva Cockpit -- the web dashboard for agentic AI on your own machine. Two agent modes: Neruva Code (reads/edits files, runs commands, debugs) and Neruva Computer (sees screen, clicks, types, navigates apps). Every session has persistent memory, semantic recall across runs, plan caching that gets cheaper over time, and mid-flight chat-steering. Loopback-only; runs on 127.0.0.1.

neruva-control

Local daemon for Neruva Cockpit — the web dashboard for agentic AI on your own machine.

Cockpit runs in your browser. This daemon runs on your laptop. Together they let an AI:

• Neruva Code — read your files, edit them, run commands, debug — autonomously
• Neruva Computer — see your screen, click, type, navigate apps — like a person would
• Remember everything across sessions via the Neruva substrate (semantic recall + plan caching)
• Take mid-flight direction — type a message while the agent is working and it adjusts

All on your machine. Nothing leaves your loopback except (optionally) the substrate writes you opt into.

Install

pip install "neruva-control[agent]"
neruva-control-install

The installer:

1. Generates an auth token at ~/.config/neruva/control.token (mode 0600 on Unix)
2. Registers a background service so the daemon starts on login (launchd / systemd-user / Task Scheduler)
3. Starts the daemon on 127.0.0.1:7331 (loopback only — never exposed to the network)
4. Prints a one-time link https://neruva.io/cockpit#token=<TOKEN> — open once, browser remembers your machine

The [agent] extra pulls in pyautogui + Pillow for the Neruva Computer screenshot/click executor. Skip it if you only want Neruva Code.

How it works

[browser at neruva.io/cockpit]
       ↕ WebSocket (loopback :7331, token-authed)
[neruva-control daemon]
   ├─ POST /v1/sessions {agent_type: "code"|"computer", initial_task}
   ├─ Routes to:
   │   • Neruva Code     — agentic loop: read/edit files, run bash
   │   • Neruva Computer — agentic loop: screenshot, click, type
   ├─ Streams every step to the browser over WS
   ├─ Accepts mid-flight "chat-steering" input via WS
   └─ Records every event to your Neruva substrate
       ↕ HTTPS (Api-Key auth)
[api.neruva.io substrate]
   ├─ Records (semantic memory, every session)
   ├─ Plan cache (replay successful task templates, ~50% cheaper)
   ├─ Memory enrichment (pre-task: "what did we do before?")
   └─ Cross-session graph RAG

The daemon binds to 127.0.0.1 only. The browser tab at neruva.io/cockpit connects via loopback WebSocket using a one-time token. The token is the only shared secret.

What the agents can do

Mode	Tools
Neruva Code	read_file, write_file, edit_file, search_files, run_bash, done
Neruva Computer	screenshot, click, type, key, scroll, wait, done

Both agents:

• Receive a memory preamble of past relevant work before each task
• Check the substrate plan cache before deriving a new plan from scratch
• Save the completed plan back to the cache for next time
• Accept mid-flight directives via the Cockpit chat input

Quick start (after install)

1. Open the link the installer printed (or run neruva-control link to print it again)
2. In Cockpit, pick a Mode (Neruva Code or Neruva Computer)
3. Type a task: "Fix the failing test in tests/test_auth.py" or "Open Notepad and draft a haiku about coffee"
4. Watch it work. Type into the chat at any time to redirect.

Commands

Command	What it does
neruva-control-install	One-shot install (generates token, registers service, prints link URL)
neruva-control start	Run the daemon foreground (used by service)
neruva-control status	Show install + daemon health + version
neruva-control link	Print the link URL again (re-link or new browser)
neruva-control stop	Stop the daemon

Configuration

Drop a .env at ~/.config/neruva/.env (Linux/macOS) or %APPDATA%\neruva\neruva\.env (Windows). The daemon auto-loads it at startup so you never touch your shell profile.

NERUVA_API_KEY=nv_...

Pre-existing shell env vars always take precedence over the .env file. The daemon also looks for ./.env in the cwd as a dev convenience.

Requirements

• Python ≥3.10
• [agent] extra: pyautogui + Pillow (skip if Code-only)
• A Neruva account at neruva.io

Privacy

• Daemon listens on 127.0.0.1 only — never on a network interface
• Sessions stream over loopback WebSocket; never leave your machine in transit
• Substrate writes (records, plan cache) are opt-in and go to your account at api.neruva.io
• Screenshots for Neruva Computer are sent to the action model for the next click decision and not stored beyond that turn unless you opt into full recording

License

MIT — see LICENSE.