Metadata-Version: 2.4
Name: neruva-control
Version: 0.3.5
Summary: 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.
Author-email: Clouthier Simulation Labs <info@neruva.io>
License: MIT
Project-URL: Homepage, https://neruva.io/
Project-URL: Documentation, https://neruva.io/docs/
Project-URL: Source, https://github.com/CloutSimLabs/neruva
Keywords: neruva,cockpit,neruva-code,neruva-computer,agent,agentic-ai,agent-memory,agent-dashboard,computer-use,computer-control,screen-control,code-agent,ai,llm
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: fastapi>=0.110
Requires-Dist: uvicorn[standard]>=0.27
Requires-Dist: httpx>=0.27
Requires-Dist: websockets>=12
Requires-Dist: platformdirs>=4
Requires-Dist: tomli>=2; python_version < "3.11"
Provides-Extra: pair
Requires-Dist: aiortc>=1.9; extra == "pair"
Provides-Extra: agent
Requires-Dist: pyautogui>=0.9.54; extra == "agent"
Requires-Dist: pillow>=10.0; extra == "agent"
Dynamic: license-file

# neruva-control

Local daemon for **[Neruva Cockpit](https://neruva.io/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

```bash
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.

```env
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](https://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](./LICENSE).
