groove-dev 0.12.4 → 0.12.6

package/README.md

@@ -12,7 +12,7 @@ npm i -g groove-dev
 groove start
 ```
 
-Open `http://localhost:31415` — your command center is ready.
+The GUI opens at `http://localhost:31415`. On a VPS? GROOVE detects it and tells you exactly what to do.
 
 ---
 
@@ -61,6 +61,125 @@ GROOVE auto-detects monorepo workspaces (npm, pnpm, lerna) and lets you spawn ea
 - **Task negotiation** — duplicate roles get assigned non-overlapping work
 - **Knock protocol** — agents signal before shared/destructive actions
 
+## Remote Access
+
+Run GROOVE on a VPS and manage your agents from anywhere. No ports exposed to the internet. No tokens. No custom auth code. Zero attack surface.
+
+### How It Works
+
+GROOVE never opens ports to the public internet. Instead, it uses battle-tested transport layers — SSH tunnels and WireGuard (Tailscale) — to keep your daemon private.
+
+```
+Your laptop                          Your VPS
+┌──────────┐    SSH tunnel      ┌──────────────────┐
+│ Browser  │ ◄────────────────► │ GROOVE daemon    │
+│ localhost│    encrypted       │ 127.0.0.1:31415  │
+└──────────┘                    └──────────────────┘
+                                Zero open ports
+```
+
+The daemon always binds to `127.0.0.1`. Nothing reaches it from the public internet. Your SSH keys handle auth. Your browser connects to `localhost` on your machine, and the tunnel forwards traffic securely to the VPS.
+
+### Setup
+
+**On your VPS:**
+
+```bash
+npm i -g groove-dev      # install
+groove start             # start the daemon
+```
+
+**On your laptop:**
+
+```bash
+npm i -g groove-dev                    # install (one-time)
+groove connect user@your-server-ip     # open the GUI
+groove disconnect                      # close when done
+```
+
+That's it. The GUI opens in your browser automatically.
+
+GROOVE auto-detects your environment — VS Code Remote, plain SSH, or local — and tells you exactly what to do. SSH config aliases work too: `groove connect my-vps`.
+
+### Tailscale / LAN Access
+
+For multi-device access (phone, tablet, other machines on your network):
+
+```bash
+groove start --host tailscale    # auto-detects your Tailscale IP
+groove start --host 192.168.1.5  # explicit IP
+```
+
+Open `http://<ip>:31415` from any device on the same network. Tailscale handles auth via WireGuard.
+
+### What's Blocked
+
+GROOVE will reject any attempt to expose the daemon directly to the internet:
+
+```bash
+groove start --host 0.0.0.0     # REJECTED — not allowed
+```
+
+This is by design. Direct exposure requires custom auth, rate limiting, TLS management — attack surface we refuse to create. SSH and WireGuard solve this better than we ever could.
+
+### Federation (Preview)
+
+Pair GROOVE daemons across machines with Ed25519 key exchange. The security layer is built — cross-server agent coordination (typed contracts, federated registry) is coming soon.
+
+```bash
+groove federation pair 100.64.1.5      # pair two daemons
+groove federation list                  # see paired peers
+groove federation status                # show keypair + peers
+```
+
+Every cross-server message is signed with Ed25519 keys generated during a pairing ceremony. The receiving daemon verifies the signature before accepting any contract. Replay attacks are rejected (5-minute timestamp window). Tampered payloads are rejected. Unknown senders are rejected.
+
+```
+Server A                              Server B
+┌──────────────┐  signed contract  ┌──────────────┐
+│ GROOVE daemon│ ◄────────────────►│ GROOVE daemon│
+│ Ed25519 key  │   verify + audit  │ Ed25519 key  │
+└──────────────┘                   └──────────────┘
+```
+
+Contracts are typed data (method, path, input/output schema) — not freeform text. No surface for prompt injection. Full audit trail on both sides.
+
+### Audit Log
+
+Every state-changing operation is logged to `.groove/audit.log`:
+
+```bash
+groove audit           # view recent entries
+groove audit -n 50     # last 50 entries
+```
+
+```
+2:14:32 PM  agent.spawn          id=a1 role=backend provider=claude-code
+2:14:35 PM  agent.spawn          id=a2 role=frontend provider=claude-code
+2:33:12 PM  agent.rotate         oldId=a1 newId=a3 role=backend
+2:45:00 PM  federation.pair      peerId=f63dc52b14b9 peerHost=100.64.1.5
+```
+
+Append-only, `0600` permissions, auto-rotates at 5MB. When team auth is added, every entry will include who performed the action.
+
+### Security Model
+
+| Threat | Defense |
+|--------|---------|
+| Remote attackers | Zero open ports. Daemon binds to private interface only. |
+| Network eavesdroppers | SSH (tunnel) or WireGuard (Tailscale) encryption. |
+| Spoofed federation contracts | Ed25519 signature verification on every message. |
+| Replay attacks | 5-minute timestamp window. Reject old/future contracts. |
+| Malformed peer data | Public key validation at pairing time. Peer IDs restricted to hex. |
+| Path traversal | Peer IDs sanitized. No filesystem access across servers. |
+| Privilege escalation | No auth code to exploit. Transport layer handles all access control. |
+
+**What we explicitly don't defend against:** Compromised SSH keys, root access to VPS, malicious AI provider responses (out of scope — we're a process manager).
+
+**The principle:** "There's nothing to attack" is better than "we have a security system and here's why it's good." GROOVE has zero auth code. The transport layer does all the work.
+
+---
+
 ## Works With Everything
 
 | Provider | Auth | Models |
@@ -76,7 +195,7 @@ Works in any terminal, any IDE, any OS. Technical and non-technical users alike.
 
 ## The GUI
 
-Open `http://localhost:31415` after starting the daemon:
+Open the dashboard after starting the daemon (local or remote):
 
 - **Agent Tree** — visual node graph with Bezier spline connections, role badges, live status
 - **Chat** — instruct agents, query without disrupting, continue completed agents, streaming text
@@ -99,7 +218,7 @@ GROOVE routes tasks to the cheapest model that can handle them. Planners get Opu
 
 ```
     ┌──────────────────────────────────────────────┐
-    │             GROOVE DAEMON (:31415)            │
+    │             GROOVE DAEMON (:31415)           │
     │                                              │
     │  Registry · Introducer · Lock Manager        │
     │  Journalist · Rotator · Adaptive · Indexer   │

package/node_modules/@groove-dev/daemon/src/firstrun.js

@@ -22,7 +22,7 @@ export function isFirstRun(grooveDir) {
 }
 
 // Show welcome banner on every startup
-export function printWelcome(port, host = '127.0.0.1') {
+export function printWelcome(port, host = '127.0.0.1', firstRun = false) {
   const providers = listProviders();
   const installed = providers.filter((p) => p.installed);
   const notInstalled = providers.filter((p) => !p.installed);
@@ -53,6 +53,7 @@ export function printWelcome(port, host = '127.0.0.1') {
   }
 
   console.log('');
+
   const isRemote = host !== '127.0.0.1';
 
   // Detect environment
@@ -63,17 +64,12 @@ export function printWelcome(port, host = '127.0.0.1') {
   const isServer = !isVSCode && (isSSH || isHeadless);
 
   if (isRemote) {
-    // Bound to network interface (Tailscale/LAN)
-    console.log(`  GUI:   http://${host}:${port}`);
-    console.log(`  Host:  ${host} (network-accessible)`);
+    console.log(`  Open:  http://${host}:${port}`);
   } else if (isVSCode) {
-    // VS Code Remote — port forwarding happens automatically
-    console.log(`  GUI:   http://localhost:${port}`);
+    console.log(`  Open:  http://localhost:${port}`);
     console.log(`         VS Code forwards this port automatically.`);
   } else if (isServer) {
-    // Plain SSH / headless — need groove connect
     const sshUser = process.env.SUDO_USER || process.env.USER || 'user';
-
     let serverIp = '';
     const sshConn = process.env.SSH_CONNECTION || '';
     if (sshConn) {
@@ -92,20 +88,14 @@ export function printWelcome(port, host = '127.0.0.1') {
       }
     }
     serverIp = serverIp || '<your-server-ip>';
-
-    console.log(`  Daemon running on port ${port}`);
-    console.log('');
-    console.log('  To open the GUI, open a terminal on your Mac/PC and run:');
-    console.log('');
+    console.log('  Open the GUI from your Mac/PC:');
     console.log(`    npx groove-dev connect ${sshUser}@${serverIp}`);
   } else {
-    // Local machine with display
-    console.log(`  GUI:   http://localhost:${port}`);
+    console.log(`  Open:  http://localhost:${port}`);
   }
 
-  console.log('');
-  console.log('  Docs:   https://docs.groovedev.ai');
-  console.log('  GitHub: https://github.com/grooveai-dev/groove');
+  console.log(`  Stop:  groove stop (or Ctrl+C)`);
+  console.log(`  Docs:  https://docs.groovedev.ai`);
   console.log('');
 }
 

package/node_modules/@groove-dev/daemon/src/index.js

@@ -89,7 +89,8 @@ export class Daemon {
     }
 
     // First-run detection
-    if (isFirstRun(this.grooveDir)) {
+    this._firstRun = isFirstRun(this.grooveDir);
+    if (this._firstRun) {
       this.config = runFirstTimeSetup(this.grooveDir);
     } else {
       this.config = loadConfig(this.grooveDir);
@@ -224,7 +225,7 @@ export class Daemon {
         writeFileSync(resolve(this.grooveDir, 'daemon.port'), String(this.port));
         writeFileSync(resolve(this.grooveDir, 'daemon.host'), this.host);
 
-        printWelcome(this.port, this.host);
+        printWelcome(this.port, this.host, this._firstRun);
 
         // Start background services
         this.journalist.start();

package/node_modules/@groove-dev/daemon/src/journalist.js

@@ -27,7 +27,6 @@ export class Journalist {
     // Run first cycle immediately, then on interval
     this.cycle();
     this.interval = setInterval(() => this.cycle(), intervalMs);
-    console.log(`  Journalist started (every ${intervalMs / 1000}s)`);
   }
 
   stop() {

package/node_modules/@groove-dev/daemon/src/rotator.js

@@ -20,7 +20,6 @@ export class Rotator extends EventEmitter {
     if (this.interval) return;
     this.enabled = true;
     this.interval = setInterval(() => this.check(), CHECK_INTERVAL);
-    console.log('  Rotator started (auto-rotation enabled)');
   }
 
   stop() {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "groove-dev",
-  "version": "0.12.4",
+  "version": "0.12.6",
   "description": "Open-source agent orchestration layer for AI coding tools. GUI dashboard, multi-agent coordination, zero cold-start (Journalist), infinite sessions (adaptive context rotation), AI Project Manager, Quick Launch. Works with Claude Code, Codex, Gemini CLI, Ollama.",
   "license": "FSL-1.1-Apache-2.0",
   "author": "Groove Dev <hello@groovedev.ai> (https://groovedev.ai)",

package/packages/daemon/src/firstrun.js

@@ -22,7 +22,7 @@ export function isFirstRun(grooveDir) {
 }
 
 // Show welcome banner on every startup
-export function printWelcome(port, host = '127.0.0.1') {
+export function printWelcome(port, host = '127.0.0.1', firstRun = false) {
   const providers = listProviders();
   const installed = providers.filter((p) => p.installed);
   const notInstalled = providers.filter((p) => !p.installed);
@@ -53,6 +53,7 @@ export function printWelcome(port, host = '127.0.0.1') {
   }
 
   console.log('');
+
   const isRemote = host !== '127.0.0.1';
 
   // Detect environment
@@ -63,17 +64,12 @@ export function printWelcome(port, host = '127.0.0.1') {
   const isServer = !isVSCode && (isSSH || isHeadless);
 
   if (isRemote) {
-    // Bound to network interface (Tailscale/LAN)
-    console.log(`  GUI:   http://${host}:${port}`);
-    console.log(`  Host:  ${host} (network-accessible)`);
+    console.log(`  Open:  http://${host}:${port}`);
   } else if (isVSCode) {
-    // VS Code Remote — port forwarding happens automatically
-    console.log(`  GUI:   http://localhost:${port}`);
+    console.log(`  Open:  http://localhost:${port}`);
     console.log(`         VS Code forwards this port automatically.`);
   } else if (isServer) {
-    // Plain SSH / headless — need groove connect
     const sshUser = process.env.SUDO_USER || process.env.USER || 'user';
-
     let serverIp = '';
     const sshConn = process.env.SSH_CONNECTION || '';
     if (sshConn) {
@@ -92,20 +88,14 @@ export function printWelcome(port, host = '127.0.0.1') {
       }
     }
     serverIp = serverIp || '<your-server-ip>';
-
-    console.log(`  Daemon running on port ${port}`);
-    console.log('');
-    console.log('  To open the GUI, open a terminal on your Mac/PC and run:');
-    console.log('');
+    console.log('  Open the GUI from your Mac/PC:');
     console.log(`    npx groove-dev connect ${sshUser}@${serverIp}`);
   } else {
-    // Local machine with display
-    console.log(`  GUI:   http://localhost:${port}`);
+    console.log(`  Open:  http://localhost:${port}`);
   }
 
-  console.log('');
-  console.log('  Docs:   https://docs.groovedev.ai');
-  console.log('  GitHub: https://github.com/grooveai-dev/groove');
+  console.log(`  Stop:  groove stop (or Ctrl+C)`);
+  console.log(`  Docs:  https://docs.groovedev.ai`);
   console.log('');
 }
 

package/packages/daemon/src/index.js

@@ -89,7 +89,8 @@ export class Daemon {
     }
 
     // First-run detection
-    if (isFirstRun(this.grooveDir)) {
+    this._firstRun = isFirstRun(this.grooveDir);
+    if (this._firstRun) {
       this.config = runFirstTimeSetup(this.grooveDir);
     } else {
       this.config = loadConfig(this.grooveDir);
@@ -224,7 +225,7 @@ export class Daemon {
         writeFileSync(resolve(this.grooveDir, 'daemon.port'), String(this.port));
         writeFileSync(resolve(this.grooveDir, 'daemon.host'), this.host);
 
-        printWelcome(this.port, this.host);
+        printWelcome(this.port, this.host, this._firstRun);
 
         // Start background services
         this.journalist.start();

package/packages/daemon/src/journalist.js

@@ -27,7 +27,6 @@ export class Journalist {
     // Run first cycle immediately, then on interval
     this.cycle();
     this.interval = setInterval(() => this.cycle(), intervalMs);
-    console.log(`  Journalist started (every ${intervalMs / 1000}s)`);
   }
 
   stop() {

package/packages/daemon/src/rotator.js

@@ -20,7 +20,6 @@ export class Rotator extends EventEmitter {
     if (this.interval) return;
     this.enabled = true;
     this.interval = setInterval(() => this.check(), CHECK_INTERVAL);
-    console.log('  Rotator started (auto-rotation enabled)');
   }
 
   stop() {