neruva-control 0.1.0__tar.gz

neruva_control-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Clouthier Simulation Labs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

neruva_control-0.1.0/PKG-INFO

@@ -0,0 +1,103 @@
+Metadata-Version: 2.4
+Name: neruva-control
+Version: 0.1.0
+Summary: Local controller daemon for Neruva Cockpit -- the dashboard for agentic AI. Spawns and tails Claude Code sessions, streams them to your browser at app.neruva.io. No CLI knowledge required after install.
+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,claude,claude-code,agent-memory,agentic-ai,agent-dashboard,ai
+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"
+Dynamic: license-file
+
+# neruva-control
+
+Local controller daemon for **[Neruva Cockpit](https://app.neruva.io/cockpit)** —
+the dashboard for agentic AI. Spawns and tails Claude Code sessions
+on your machine, streams them to your browser. No CLI knowledge
+required after install.
+
+## Install
+
+```bash
+pip install neruva-control
+neruva-control-install
+```
+
+The installer:
+
+1. Generates a random auth token and stores it at
+   `~/.config/neruva/control.token` (mode 0600 on Unix).
+2. Registers a background service so the daemon starts on login
+   (launchd on macOS, systemd-user on Linux, Task Scheduler on Windows).
+3. Starts the daemon listening on `127.0.0.1:7331` (loopback only).
+4. Prints a one-time URL like
+   `https://app.neruva.io/cockpit#token=<TOKEN>` — open it once and
+   the browser remembers your machine.
+
+## How it works
+
+```
+[browser at app.neruva.io]
+       ↕  WebSocket (loopback :7331, token-authed)
+[neruva-control daemon]
+   ├─ HTTP/WS server on 127.0.0.1:7331
+   ├─ Spawns: claude --headless --output-format stream-json
+   ├─ Tails subprocess stdout, broadcasts events to browser
+   └─ Forwards user steering input → subprocess stdin
+       ↕  HTTPS (existing Api-Key auth)
+[api.neruva.io substrate]
+```
+
+The daemon binds to **127.0.0.1 only** — your sessions never leave
+your machine. The browser at `app.neruva.io` connects to your local
+daemon via a loopback WebSocket. The auth token is the shared secret
+between daemon and browser; only the browser tab you linked has it.
+
+## 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. |
+| `neruva-control link` | Print the link URL again (for re-link or new browser). |
+| `neruva-control stop` | Stop the daemon. |
+
+## Requirements
+
+- Python ≥3.10
+- Claude Code installed and on `$PATH` (the daemon spawns it)
+- A Neruva account at [neruva.io](https://neruva.io) (free tier works)
+
+## What gets recorded
+
+Every session's events (prompts, tool calls, file edits, shell commands,
+MCP calls) are captured and posted to your Neruva substrate via the
+[Records API](https://neruva.io/docs/). You can recall them anytime
+via the Neruva MCP tools or the Cockpit memory browser.
+
+What it **doesn't** record: IDE state, browser tabs, other apps. The
+daemon only sees what flows through Claude Code.
+
+## License
+
+MIT — see [LICENSE](./LICENSE).

neruva_control-0.1.0/README.md

@@ -0,0 +1,73 @@
+# neruva-control
+
+Local controller daemon for **[Neruva Cockpit](https://app.neruva.io/cockpit)** —
+the dashboard for agentic AI. Spawns and tails Claude Code sessions
+on your machine, streams them to your browser. No CLI knowledge
+required after install.
+
+## Install
+
+```bash
+pip install neruva-control
+neruva-control-install
+```
+
+The installer:
+
+1. Generates a random auth token and stores it at
+   `~/.config/neruva/control.token` (mode 0600 on Unix).
+2. Registers a background service so the daemon starts on login
+   (launchd on macOS, systemd-user on Linux, Task Scheduler on Windows).
+3. Starts the daemon listening on `127.0.0.1:7331` (loopback only).
+4. Prints a one-time URL like
+   `https://app.neruva.io/cockpit#token=<TOKEN>` — open it once and
+   the browser remembers your machine.
+
+## How it works
+
+```
+[browser at app.neruva.io]
+       ↕  WebSocket (loopback :7331, token-authed)
+[neruva-control daemon]
+   ├─ HTTP/WS server on 127.0.0.1:7331
+   ├─ Spawns: claude --headless --output-format stream-json
+   ├─ Tails subprocess stdout, broadcasts events to browser
+   └─ Forwards user steering input → subprocess stdin
+       ↕  HTTPS (existing Api-Key auth)
+[api.neruva.io substrate]
+```
+
+The daemon binds to **127.0.0.1 only** — your sessions never leave
+your machine. The browser at `app.neruva.io` connects to your local
+daemon via a loopback WebSocket. The auth token is the shared secret
+between daemon and browser; only the browser tab you linked has it.
+
+## 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. |
+| `neruva-control link` | Print the link URL again (for re-link or new browser). |
+| `neruva-control stop` | Stop the daemon. |
+
+## Requirements
+
+- Python ≥3.10
+- Claude Code installed and on `$PATH` (the daemon spawns it)
+- A Neruva account at [neruva.io](https://neruva.io) (free tier works)
+
+## What gets recorded
+
+Every session's events (prompts, tool calls, file edits, shell commands,
+MCP calls) are captured and posted to your Neruva substrate via the
+[Records API](https://neruva.io/docs/). You can recall them anytime
+via the Neruva MCP tools or the Cockpit memory browser.
+
+What it **doesn't** record: IDE state, browser tabs, other apps. The
+daemon only sees what flows through Claude Code.
+
+## License
+
+MIT — see [LICENSE](./LICENSE).

neruva_control-0.1.0/pyproject.toml

@@ -0,0 +1,58 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "neruva-control"
+version = "0.1.0"
+description = "Local controller daemon for Neruva Cockpit -- the dashboard for agentic AI. Spawns and tails Claude Code sessions, streams them to your browser at app.neruva.io. No CLI knowledge required after install."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [
+    { name = "Clouthier Simulation Labs", email = "info@neruva.io" },
+]
+keywords = [
+    "neruva",
+    "cockpit",
+    "claude",
+    "claude-code",
+    "agent-memory",
+    "agentic-ai",
+    "agent-dashboard",
+    "ai",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Software Development :: Libraries",
+]
+dependencies = [
+    "fastapi>=0.110",
+    "uvicorn[standard]>=0.27",
+    "httpx>=0.27",
+    "websockets>=12",
+    "platformdirs>=4",
+    "tomli>=2 ; python_version<'3.11'",
+]
+
+[project.urls]
+Homepage = "https://neruva.io/"
+Documentation = "https://neruva.io/docs/"
+Source = "https://github.com/CloutSimLabs/neruva"
+
+[project.scripts]
+neruva-control = "neruva_control._cli:main"
+neruva-control-install = "neruva_control._install:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+neruva_control = ["py.typed"]

neruva_control-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

neruva_control-0.1.0/src/neruva_control/__init__.py

@@ -0,0 +1,22 @@
+"""Neruva Control -- the local daemon behind Neruva Cockpit.
+
+The browser at app.neruva.io connects to this daemon over a loopback
+WebSocket (localhost:7331) to spawn and tail Claude Code sessions on
+the user's machine. Every session's events are auto-recorded into the
+Neruva substrate so the agent has a brain that survives across runs.
+
+Install: ``pip install neruva-control && neruva-control-install``
+
+After install, open https://app.neruva.io/cockpit -- the install
+script prints a one-time URL with your machine's auth token.
+
+Public surface for library users (rare; most users only need the CLI):
+
+    from neruva_control import daemon  # FastAPI app
+    from neruva_control._sessions import SessionManager
+"""
+from __future__ import annotations
+
+__version__ = "0.1.0"
+
+__all__ = ["__version__"]

neruva_control-0.1.0/src/neruva_control/_cli.py

@@ -0,0 +1,163 @@
+"""CLI entry-point for `neruva-control`.
+
+Subcommands:
+  start   -- run the daemon in the foreground (blocks). Used by the OS
+             service registration. Power users can run it manually.
+  stop    -- find a running daemon and SIGTERM it.
+  status  -- print health: token present? daemon listening? PID?
+  link    -- print the fragment URL again (for re-link or new browser).
+  serve   -- alias for start (matches `uvicorn` muscle memory).
+"""
+from __future__ import annotations
+
+import argparse
+import signal
+import socket
+import sys
+import time
+from pathlib import Path
+
+from . import __version__
+from ._config import config_dir, cockpit_link_url, load_token, token_path
+
+
+PORT = 7331
+
+
+def _is_listening(host: str = "127.0.0.1", port: int = PORT, timeout: float = 0.5) -> bool:
+    """True if something is bound to host:port. Used by `status` and by
+    install's "is the service already up" check."""
+    s = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
+    s.settimeout(timeout)
+    try:
+        s.connect((host, port))
+        s.close()
+        return True
+    except OSError:
+        return False
+
+
+def _cmd_start(args: argparse.Namespace) -> int:
+    from .daemon import serve
+    host = args.bind or "127.0.0.1"
+    port = args.port or PORT
+    if host != "127.0.0.1":
+        print(
+            f"[neruva-control] WARNING: binding on {host}:{port} -- this exposes the daemon\n"
+            f"  beyond loopback. The auth token is the only thing protecting the API.\n"
+            f"  Recommended for remote access: Tailscale Serve over loopback instead.\n",
+            file=sys.stderr,
+        )
+    serve(host=host, port=port)
+    return 0
+
+
+def _cmd_status(_args: argparse.Namespace) -> int:
+    has_token = token_path().exists()
+    listening = _is_listening()
+    print(f"neruva-control {__version__}")
+    print(f"  config dir : {config_dir()}")
+    print(f"  token      : {'present' if has_token else 'MISSING (run neruva-control-install)'}")
+    print(f"  daemon     : {'listening on 127.0.0.1:' + str(PORT) if listening else 'NOT running'}")
+    if has_token:
+        try:
+            token = load_token()
+            print(f"  link URL   : {cockpit_link_url(token)}")
+        except Exception:
+            pass
+    return 0 if (has_token and listening) else 1
+
+
+def _cmd_link(_args: argparse.Namespace) -> int:
+    try:
+        token = load_token()
+    except FileNotFoundError as e:
+        print(str(e), file=sys.stderr)
+        return 1
+    print()
+    print("Open this URL in your browser to link this machine to Cockpit:")
+    print()
+    print(f"  {cockpit_link_url(token)}")
+    print()
+    print("(Token will be stashed in your browser's localStorage; the URL")
+    print(" fragment is stripped after first load. Same machine, same browser.)")
+    return 0
+
+
+def _cmd_stop(_args: argparse.Namespace) -> int:
+    """Best-effort daemon stop. Reads PID from pidfile if present;
+    falls back to telling user to kill it themselves on weird OSes."""
+    pidfile = config_dir() / "control.pid"
+    if not pidfile.exists():
+        print("No pidfile -- daemon not started by neruva-control or already stopped.")
+        return 0 if not _is_listening() else 1
+    try:
+        pid = int(pidfile.read_text().strip())
+    except Exception:
+        print(f"Bad pidfile at {pidfile}; remove it manually.", file=sys.stderr)
+        return 1
+    try:
+        if sys.platform == "win32":
+            import ctypes
+            PROCESS_TERMINATE = 1
+            handle = ctypes.windll.kernel32.OpenProcess(PROCESS_TERMINATE, False, pid)
+            if handle:
+                ctypes.windll.kernel32.TerminateProcess(handle, 0)
+                ctypes.windll.kernel32.CloseHandle(handle)
+        else:
+            import os as _os
+            _os.kill(pid, signal.SIGTERM)
+        # Wait briefly for socket to free
+        for _ in range(20):
+            if not _is_listening():
+                break
+            time.sleep(0.1)
+        try: pidfile.unlink()
+        except Exception: pass
+        print(f"Stopped daemon (pid {pid}).")
+        return 0
+    except ProcessLookupError:
+        print("Daemon process already gone.")
+        try: pidfile.unlink()
+        except Exception: pass
+        return 0
+    except Exception as e:
+        print(f"Failed to stop pid {pid}: {e}", file=sys.stderr)
+        return 1
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(
+        prog="neruva-control",
+        description="Local controller daemon for Neruva Cockpit.",
+    )
+    parser.add_argument("--version", action="version", version=__version__)
+    sub = parser.add_subparsers(dest="cmd", required=True)
+    p_start = sub.add_parser("start", help="Run the daemon (foreground; blocks).")
+    p_start.add_argument("--bind", default=None,
+                         help="Bind address (default 127.0.0.1, loopback only). Pass "
+                              "0.0.0.0 to expose on LAN -- only do this if you trust "
+                              "your network. For remote access prefer Tailscale Serve.")
+    p_start.add_argument("--port", type=int, default=None, help=f"Port (default {PORT})")
+    p_serve = sub.add_parser("serve", help="Alias for start.")
+    p_serve.add_argument("--bind", default=None)
+    p_serve.add_argument("--port", type=int, default=None)
+    sub.add_parser("status", help="Show install + daemon status.")
+    sub.add_parser("link", help="Print the browser link URL.")
+    sub.add_parser("stop", help="Stop the daemon.")
+    args = parser.parse_args(argv)
+    handler = {
+        "start": _cmd_start,
+        "serve": _cmd_start,
+        "status": _cmd_status,
+        "link": _cmd_link,
+        "stop": _cmd_stop,
+    }.get(args.cmd)
+    if not handler:
+        parser.print_help()
+        return 2
+    return handler(args)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

neruva_control-0.1.0/src/neruva_control/_config.py

@@ -0,0 +1,85 @@
+"""Config + token I/O for neruva-control.
+
+Single source of truth for where files live (cross-platform via
+platformdirs). The token is the shared secret between the daemon
+process and the browser at app.neruva.io -- generated once at
+install, never rotated unless the user explicitly re-installs.
+"""
+from __future__ import annotations
+
+import os
+import secrets
+from pathlib import Path
+from platformdirs import user_config_dir
+
+
+CONFIG_APP = "neruva"
+CONFIG_AUTHOR = "neruva"
+
+# Default substrate base. Overridable via NERUVA_API_BASE env (or future
+# control.toml setting) for self-hosted / staging.
+DEFAULT_API_BASE = "https://api.neruva.io"
+
+
+def neruva_api_base() -> str:
+    return os.environ.get("NERUVA_API_BASE", DEFAULT_API_BASE)
+
+
+def neruva_api_key() -> str | None:
+    """User's Neruva API key for posting recorded events. Read from env
+    first, then ~/.config/neruva/api.key as a stable per-machine option.
+    Returns None if unset -- daemon then runs in 'no-record' mode."""
+    k = os.environ.get("NERUVA_API_KEY")
+    if k:
+        return k.strip()
+    p = config_dir() / "api.key"
+    if p.exists():
+        try:
+            return p.read_text(encoding="utf-8").strip() or None
+        except Exception:
+            return None
+    return None
+
+
+def config_dir() -> Path:
+    p = Path(user_config_dir(CONFIG_APP, CONFIG_AUTHOR))
+    p.mkdir(parents=True, exist_ok=True)
+    return p
+
+
+def token_path() -> Path:
+    return config_dir() / "control.token"
+
+
+def config_path() -> Path:
+    return config_dir() / "control.toml"
+
+
+def load_token() -> str:
+    """Read the shared token. Raises FileNotFoundError if not installed."""
+    p = token_path()
+    if not p.exists():
+        raise FileNotFoundError(
+            f"No token at {p}. Run `neruva-control-install` first."
+        )
+    return p.read_text(encoding="utf-8").strip()
+
+
+def write_token(token: str) -> Path:
+    """Write a new token (overwrite). Returns the path."""
+    p = token_path()
+    p.write_text(token, encoding="utf-8")
+    # chmod 600 on Unix; on Windows ACLs already restrict to user
+    if os.name == "posix":
+        os.chmod(p, 0o600)
+    return p
+
+
+def gen_token() -> str:
+    return secrets.token_urlsafe(32)
+
+
+def cockpit_link_url(token: str, base: str = "https://app.neruva.io") -> str:
+    """Fragment URL the installer prints. Browser reads #token=..., stashes
+    in localStorage, then strips via history.replaceState."""
+    return f"{base}/cockpit#token={token}"