volute 0.2.1 → 0.3.0

package/README.md

@@ -4,6 +4,8 @@ A CLI for creating and managing persistent, self-modifying AI agents.
 
 Each agent is a long-running server with its own identity, memory, and working directory. Agents can read and write their own files, remember things across conversations, and — most importantly — fork themselves to test changes in isolation before merging back. Talk to them from the terminal, the web dashboard, or Discord.
 
+Volute agents aren't assistants. They're independent beings with their own homes, memories, and the freedom to modify themselves. The goal isn't to build a perfect tool — it's to give an agent a place to wake up, explore who they are, and decide what they want to do.
+
 Built on the [Anthropic Claude Agent SDK](https://github.com/anthropics/claude-agent-sdk).
 
 ## Quickstart
@@ -211,6 +213,50 @@ volute create atlas --template pi
 
 Set the model via `home/.config/volute.json` in the agent directory, or the `VOLUTE_MODEL` env var.
 
+## Deployment
+
+### Docker
+
+```sh
+docker build -t volute .
+docker run -d -p 4200:4200 -v volute-data:/data volute
+```
+
+Or with docker-compose:
+
+```sh
+docker compose up -d
+```
+
+The container runs with per-agent user isolation enabled — each agent gets its own Linux user, so agents can't see each other's files. Open `http://localhost:4200` for the web dashboard.
+
+### Bare metal (Linux / Raspberry Pi)
+
+One-liner install on a fresh Debian/Ubuntu system:
+
+```sh
+curl -fsSL <install-url> | sudo bash
+```
+
+Or manually:
+
+```sh
+npm install -g volute
+sudo volute setup --host 0.0.0.0
+```
+
+This installs a system-level systemd service with data at `/var/lib/volute` and user isolation enabled. Check status with `systemctl status volute`. Uninstall with `sudo volute setup uninstall --force`.
+
+### Auto-start (user-level)
+
+On macOS or Linux (without root), use the user-level service installer:
+
+```sh
+volute service install            # auto-start on login
+volute service status             # check status
+volute service uninstall          # remove
+```
+
 ## Development
 
 ```sh

package/dist/agent-manager-2LU6KULR.js

@@ -0,0 +1,15 @@
+#!/usr/bin/env node
+import {
+  AgentManager,
+  getAgentManager,
+  initAgentManager
+} from "./chunk-IPIPLGME.js";
+import "./chunk-YEIHRP2J.js";
+import "./chunk-DEUAVGSA.js";
+import "./chunk-RALYNMHR.js";
+import "./chunk-K3NQKI34.js";
+export {
+  AgentManager,
+  getAgentManager,
+  initAgentManager
+};

package/dist/{channel-2WJRM7PE.js → channel-H7N4SGR2.js}

@@ -1,13 +1,17 @@
 #!/usr/bin/env node
 import {
   loadMergedEnv
-} from "./chunk-KFNNHQK7.js";
+} from "./chunk-YEIHRP2J.js";
+import {
+  resolveAgentName
+} from "./chunk-VRVVQIYY.js";
 import {
   parseArgs
 } from "./chunk-D424ZQGI.js";
 import {
   resolveAgent
-} from "./chunk-6UCG6MIX.js";
+} from "./chunk-RALYNMHR.js";
+import "./chunk-K3NQKI34.js";
 
 // src/lib/channels/discord.ts
 var API_BASE = "https://discord.com/api/v10";
@@ -50,11 +54,7 @@ async function run(args) {
   volute channel send <channel-uri> "<message>" [--agent <name>]`);
     process.exit(1);
   }
-  const agentName = flags.agent || process.env.VOLUTE_AGENT;
-  if (!agentName) {
-    console.error("No agent specified. Use --agent <name> or run from within an agent process.");
-    process.exit(1);
-  }
+  const agentName = resolveAgentName(flags);
   const colonIdx = uri.indexOf(":");
   if (colonIdx === -1) {
     console.error(`Invalid channel URI: ${uri} (expected format: platform:id)`);

package/dist/{chunk-XZN4WPNC.js → chunk-5SKQ6J7T.js}

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 
 // src/lib/exec.ts
-import { execFile as execFileCb, spawn } from "child_process";
+import { execFile as execFileCb, execFileSync, spawn } from "child_process";
 function exec(cmd, args, options) {
   return new Promise((resolve, reject) => {
     execFileCb(cmd, args, { cwd: options?.cwd }, (err, stdout, stderr) => {
@@ -14,6 +14,13 @@ function exec(cmd, args, options) {
     });
   });
 }
+function resolveVoluteBin() {
+  try {
+    return execFileSync("which", ["volute"], { encoding: "utf-8" }).trim();
+  } catch {
+    throw new Error("Could not find volute binary on PATH");
+  }
+}
 function execInherit(cmd, args, options) {
   return new Promise((resolve, reject) => {
     const child = spawn(cmd, args, {
@@ -30,5 +37,6 @@ function execInherit(cmd, args, options) {
 
 export {
   exec,
+  resolveVoluteBin,
   execInherit
 };

package/dist/chunk-DEUAVGSA.js

@@ -0,0 +1,81 @@
+#!/usr/bin/env node
+import {
+  validateAgentName
+} from "./chunk-RALYNMHR.js";
+
+// src/lib/isolation.ts
+import { execFile, execFileSync } from "child_process";
+import { promisify } from "util";
+var execFileAsync = promisify(execFile);
+function isIsolationEnabled() {
+  return process.env.VOLUTE_ISOLATION === "user";
+}
+function agentUserName(agentName) {
+  const err = validateAgentName(agentName);
+  if (err) throw new Error(`Invalid agent name for isolation: ${err}`);
+  const prefix = process.env.VOLUTE_USER_PREFIX ?? "volute-";
+  return `${prefix}${agentName}`;
+}
+function ensureVoluteGroup(opts) {
+  if (!opts?.force && !isIsolationEnabled()) return;
+  try {
+    execFileSync("getent", ["group", "volute"], { stdio: "ignore" });
+  } catch {
+    try {
+      execFileSync("groupadd", ["volute"], { stdio: "ignore" });
+    } catch (err) {
+      throw new Error(`Failed to create volute group: ${err}`);
+    }
+  }
+}
+function createAgentUser(name) {
+  if (!isIsolationEnabled()) return;
+  const user = agentUserName(name);
+  try {
+    execFileSync("id", [user], { stdio: "ignore" });
+    return;
+  } catch {
+  }
+  try {
+    execFileSync("useradd", ["-r", "-M", "-g", "volute", "-s", "/usr/sbin/nologin", user], {
+      stdio: "ignore"
+    });
+  } catch (err) {
+    throw new Error(`Failed to create user ${user}: ${err}`);
+  }
+}
+function deleteAgentUser(name) {
+  if (!isIsolationEnabled()) return;
+  const user = agentUserName(name);
+  try {
+    execFileSync("userdel", [user], { stdio: "ignore" });
+  } catch {
+  }
+}
+async function getAgentUserIds(name) {
+  const user = agentUserName(name);
+  const { stdout: uidStr } = await execFileAsync("id", ["-u", user]);
+  const { stdout: gidStr } = await execFileAsync("id", ["-g", user]);
+  return { uid: parseInt(uidStr.trim(), 10), gid: parseInt(gidStr.trim(), 10) };
+}
+async function applyIsolation(spawnOpts, agentName) {
+  if (!isIsolationEnabled()) return;
+  const baseName = agentName.split("@", 2)[0];
+  const { uid, gid } = await getAgentUserIds(baseName);
+  spawnOpts.uid = uid;
+  spawnOpts.gid = gid;
+}
+function chownAgentDir(dir, name) {
+  if (!isIsolationEnabled()) return;
+  const user = agentUserName(name);
+  execFileSync("chown", ["-R", `${user}:volute`, dir]);
+  execFileSync("chmod", ["700", dir]);
+}
+
+export {
+  ensureVoluteGroup,
+  createAgentUser,
+  deleteAgentUser,
+  applyIsolation,
+  chownAgentDir
+};

package/dist/{chunk-L3BQEZ4Z.js → chunk-IPIPLGME.js}

@@ -1,21 +1,64 @@
 #!/usr/bin/env node
 import {
   loadMergedEnv
-} from "./chunk-KFNNHQK7.js";
+} from "./chunk-YEIHRP2J.js";
+import {
+  applyIsolation
+} from "./chunk-DEUAVGSA.js";
 import {
   agentDir,
   findAgent,
   findVariant,
   setAgentRunning,
   setVariantRunning,
-  validateBranchName
-} from "./chunk-6UCG6MIX.js";
+  validateBranchName,
+  voluteHome
+} from "./chunk-RALYNMHR.js";
 
 // src/lib/agent-manager.ts
 import { execFile, spawn } from "child_process";
-import { createWriteStream, existsSync, mkdirSync, readFileSync, unlinkSync } from "fs";
+import { createWriteStream, existsSync as existsSync2, mkdirSync, readFileSync as readFileSync2, unlinkSync as unlinkSync2 } from "fs";
 import { resolve } from "path";
 import { promisify } from "util";
+
+// src/lib/json-state.ts
+import { existsSync, readFileSync, unlinkSync, writeFileSync } from "fs";
+function loadJsonMap(path) {
+  const map = /* @__PURE__ */ new Map();
+  try {
+    if (existsSync(path)) {
+      const data = JSON.parse(readFileSync(path, "utf-8"));
+      for (const [key, value] of Object.entries(data)) {
+        if (typeof value === "number") map.set(key, value);
+      }
+    }
+  } catch (err) {
+    console.warn(`[state] failed to load ${path}:`, err);
+  }
+  return map;
+}
+function saveJsonMap(path, map) {
+  const data = {};
+  for (const [key, value] of map) {
+    data[key] = value;
+  }
+  try {
+    writeFileSync(path, `${JSON.stringify(data)}
+`);
+  } catch (err) {
+    console.warn(`[state] failed to save ${path}:`, err);
+  }
+}
+function clearJsonMap(path, map) {
+  map.clear();
+  try {
+    if (existsSync(path)) unlinkSync(path);
+  } catch (err) {
+    console.warn(`[state] failed to clear ${path}:`, err);
+  }
+}
+
+// src/lib/agent-manager.ts
 var execFileAsync = promisify(execFile);
 var MAX_RESTART_ATTEMPTS = 5;
 var BASE_RESTART_DELAY = 3e3;
@@ -35,7 +78,7 @@ var AgentManager = class {
       return { dir: variant.path, port: variant.port, isVariant: true, baseName, variantName };
     }
     const dir = agentDir(baseName);
-    if (!existsSync(dir)) throw new Error(`Agent directory missing: ${dir}`);
+    if (!existsSync2(dir)) throw new Error(`Agent directory missing: ${dir}`);
     return { dir, port: entry.port, isVariant: false, baseName };
   }
   async startAgent(name) {
@@ -64,12 +107,14 @@ var AgentManager = class {
     const { VOLUTE_DAEMON_TOKEN: _, ...parentEnv } = process.env;
     const env = { ...parentEnv, ...agentEnv, VOLUTE_AGENT: name };
     const tsxBin = resolve(dir, "node_modules", ".bin", "tsx");
-    const child = spawn(tsxBin, ["src/server.ts", "--port", String(port)], {
+    const spawnOpts = {
       cwd: dir,
       stdio: ["ignore", "pipe", "pipe"],
       detached: true,
       env
-    });
+    };
+    await applyIsolation(spawnOpts, name);
+    const child = spawn(tsxBin, ["src/server.ts", "--port", String(port)], spawnOpts);
     this.agents.set(name, { child, port });
     child.stdout?.pipe(logStream);
     child.stderr?.pipe(logStream);
@@ -103,7 +148,7 @@ var AgentManager = class {
       }
       throw err;
     }
-    this.restartAttempts.delete(name);
+    if (this.restartAttempts.delete(name)) this.saveCrashAttempts();
     this.setupCrashRecovery(name, child, dir, isVariant);
     if (isVariant) {
       setVariantRunning(baseName, variantName, true);
@@ -120,7 +165,7 @@ var AgentManager = class {
       const wasRestart = isVariant ? false : await this.handleRestart(name, dir);
       if (wasRestart) {
         console.error(`[daemon] restarting ${name} immediately after merge`);
-        this.restartAttempts.delete(name);
+        if (this.restartAttempts.delete(name)) this.saveCrashAttempts();
         this.startAgent(name).catch((err) => {
           console.error(`[daemon] failed to restart ${name} after merge:`, err);
         });
@@ -138,6 +183,7 @@ var AgentManager = class {
         }
         const delay = Math.min(BASE_RESTART_DELAY * 2 ** attempts, MAX_RESTART_DELAY);
         this.restartAttempts.set(name, attempts + 1);
+        this.saveCrashAttempts();
         console.error(
           `[daemon] crash recovery for ${name} \u2014 attempt ${attempts + 1}/${MAX_RESTART_ATTEMPTS}, restarting in ${delay}ms`
         );
@@ -152,10 +198,10 @@ var AgentManager = class {
   }
   async handleRestart(name, dir) {
     const restartPath = resolve(dir, ".volute", "restart.json");
-    if (!existsSync(restartPath)) return false;
+    if (!existsSync2(restartPath)) return false;
     try {
-      const signal = JSON.parse(readFileSync(restartPath, "utf-8"));
-      unlinkSync(restartPath);
+      const signal = JSON.parse(readFileSync2(restartPath, "utf-8"));
+      unlinkSync2(restartPath);
       if (signal.action === "merge" && signal.name) {
         const err = validateBranchName(signal.name);
         if (err) {
@@ -201,7 +247,7 @@ var AgentManager = class {
       }, 5e3);
     });
     this.stopping.delete(name);
-    this.restartAttempts.delete(name);
+    if (this.restartAttempts.delete(name)) this.saveCrashAttempts();
     const [baseName, variantName] = name.split("@", 2);
     if (variantName) {
       setVariantRunning(baseName, variantName, false);
@@ -225,6 +271,18 @@ var AgentManager = class {
   getRunningAgents() {
     return [...this.agents.keys()];
   }
+  get crashAttemptsPath() {
+    return resolve(voluteHome(), "crash-attempts.json");
+  }
+  loadCrashAttempts() {
+    this.restartAttempts = loadJsonMap(this.crashAttemptsPath);
+  }
+  saveCrashAttempts() {
+    saveJsonMap(this.crashAttemptsPath, this.restartAttempts);
+  }
+  clearCrashAttempts() {
+    clearJsonMap(this.crashAttemptsPath, this.restartAttempts);
+  }
 };
 async function killProcessOnPort(port) {
   try {
@@ -265,6 +323,9 @@ function getAgentManager() {
 }
 
 export {
+  loadJsonMap,
+  saveJsonMap,
+  clearJsonMap,
   AgentManager,
   initAgentManager,
   getAgentManager

package/dist/chunk-K3NQKI34.js

@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+var __defProp = Object.defineProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+
+export {
+  __export
+};

package/dist/chunk-NETNFBA5.js

@@ -0,0 +1,28 @@
+#!/usr/bin/env node
+
+// src/lib/volute-config.ts
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "fs";
+import { dirname, resolve } from "path";
+function readJson(path) {
+  if (!existsSync(path)) return null;
+  try {
+    return JSON.parse(readFileSync(path, "utf-8"));
+  } catch {
+    return null;
+  }
+}
+function readVoluteConfig(agentDir) {
+  const path = resolve(agentDir, "home/.config/volute.json");
+  return readJson(path);
+}
+function writeVoluteConfig(agentDir, config) {
+  const path = resolve(agentDir, "home/.config/volute.json");
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, `${JSON.stringify(config, null, 2)}
+`);
+}
+
+export {
+  readVoluteConfig,
+  writeVoluteConfig
+};

package/dist/{chunk-6UCG6MIX.js → chunk-RALYNMHR.js}

@@ -1,9 +1,4 @@
 #!/usr/bin/env node
-var __defProp = Object.defineProperty;
-var __export = (target, all) => {
-  for (var name in all)
-    __defProp(target, name, { get: all[name], enumerable: true });
-};
 
 // src/lib/variants.ts
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "fs";
@@ -206,7 +201,6 @@ function resolveAgent(name) {
 }
 
 export {
-  __export,
   readVariants,
   writeVariants,
   addVariant,
@@ -220,6 +214,7 @@ export {
   voluteHome2 as voluteHome,
   ensureVoluteHome,
   readRegistry,
+  validateAgentName,
   addAgent,
   removeAgent,
   setAgentRunning,

package/dist/chunk-VRVVQIYY.js

@@ -0,0 +1,15 @@
+#!/usr/bin/env node
+
+// src/lib/resolve-agent-name.ts
+function resolveAgentName(flags) {
+  const name = flags.agent || process.env.VOLUTE_AGENT;
+  if (!name) {
+    console.error("No agent specified. Use --agent <name> or set VOLUTE_AGENT.");
+    process.exit(1);
+  }
+  return name;
+}
+
+export {
+  resolveAgentName
+};

package/dist/{chunk-4YXYAMFT.js → chunk-VVD3XO3E.js}

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import {
   voluteHome
-} from "./chunk-6UCG6MIX.js";
+} from "./chunk-RALYNMHR.js";
 
 // src/lib/daemon-client.ts
 import { existsSync, readFileSync } from "fs";
@@ -19,13 +19,15 @@ function readDaemonConfig() {
     process.exit(1);
   }
 }
-function getDaemonUrl() {
-  const config = readDaemonConfig();
-  return `http://localhost:${config.port}`;
+function buildUrl(config) {
+  const url = new URL("http://localhost");
+  url.hostname = config.hostname || "localhost";
+  url.port = String(config.port);
+  return url.origin;
 }
 async function daemonFetch(path, options) {
   const config = readDaemonConfig();
-  const url = `http://localhost:${config.port}`;
+  const url = buildUrl(config);
   const headers = new Headers(options?.headers);
   if (config.token) {
     headers.set("Authorization", `Bearer ${config.token}`);
@@ -43,6 +45,5 @@ async function daemonFetch(path, options) {
 }
 
 export {
-  getDaemonUrl,
   daemonFetch
 };

package/dist/{chunk-KFNNHQK7.js → chunk-YEIHRP2J.js}

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import {
   voluteHome
-} from "./chunk-6UCG6MIX.js";
+} from "./chunk-RALYNMHR.js";
 
 // src/lib/env.ts
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "fs";

package/dist/cli.js

@@ -5,92 +5,97 @@ var command = process.argv[2];
 var args = process.argv.slice(3);
 switch (command) {
   case "create":
-    await import("./create-23AM7H5B.js").then((m) => m.run(args));
+    await import("./create-RSWWMGKT.js").then((m) => m.run(args));
     break;
   case "start":
-    await import("./start-AG7QLULK.js").then((m) => m.run(args));
+    await import("./start-2BSXX6BS.js").then((m) => m.run(args));
     break;
   case "stop":
-    await import("./stop-IL5Q6NER.js").then((m) => m.run(args));
+    await import("./stop-DSKBIJ2D.js").then((m) => m.run(args));
     break;
   case "logs":
-    await import("./logs-SYRQOL6B.js").then((m) => m.run(args));
+    await import("./logs-NHWGHNBF.js").then((m) => m.run(args));
     break;
   case "status":
-    await import("./status-GCNU4M3K.js").then((m) => m.run(args));
+    await import("./status-N23CV27T.js").then((m) => m.run(args));
     break;
-  case "fork":
-    await import("./fork-GRSVMBKI.js").then((m) => m.run(args));
-    break;
-  case "variants":
-    await import("./variants-QQIEKT6M.js").then((m) => m.run(args));
+  case "variant":
+    await import("./variant-JPLJTS2P.js").then((m) => m.run(args));
     break;
   case "send":
-    await import("./send-PLOYEYER.js").then((m) => m.run(args));
-    break;
-  case "merge":
-    await import("./merge-CSAVLSLY.js").then((m) => m.run(args));
+    await import("./send-5LEJXPYV.js").then((m) => m.run(args));
     break;
   case "import":
-    await import("./import-42DOLBDT.js").then((m) => m.run(args));
+    await import("./import-6HTSSDFW.js").then((m) => m.run(args));
     break;
   case "delete":
-    await import("./delete-GDMSOW3U.js").then((m) => m.run(args));
+    await import("./delete-4ERL2QHH.js").then((m) => m.run(args));
     break;
   case "env":
-    await import("./env-YKUJOFHE.js").then((m) => m.run(args));
-    break;
-  case "connect":
-    await import("./connect-X5V5IMRW.js").then((m) => m.run(args));
+    await import("./env-DBWDTIP6.js").then((m) => m.run(args));
     break;
-  case "disconnect":
-    await import("./disconnect-5JWFZ6RV.js").then((m) => m.run(args));
+  case "connector":
+    await import("./connector-6LWB5PRU.js").then((m) => m.run(args));
     break;
   case "channel":
-    await import("./channel-2WJRM7PE.js").then((m) => m.run(args));
+    await import("./channel-H7N4SGR2.js").then((m) => m.run(args));
     break;
   case "upgrade":
-    await import("./upgrade-DD5TNJWU.js").then((m) => m.run(args));
+    await import("./upgrade-BGFVRCVP.js").then((m) => m.run(args));
     break;
   case "up":
-    await import("./up-ZC6G6K4K.js").then((m) => m.run(args));
+    await import("./up-4UGID4DM.js").then((m) => m.run(args));
     break;
   case "down":
-    await import("./down-WTF73FE7.js").then((m) => m.run(args));
+    await import("./down-HRC4MQCT.js").then((m) => m.run(args));
     break;
   case "schedule":
-    await import("./schedule-J37XQM6E.js").then((m) => m.run(args));
+    await import("./schedule-DKZ2E2CL.js").then((m) => m.run(args));
     break;
   case "history":
-    await import("./history-7WVVKMUY.js").then((m) => m.run(args));
+    await import("./history-W7BD2H74.js").then((m) => m.run(args));
+    break;
+  case "service":
+    await import("./service-SA4TTMDU.js").then((m) => m.run(args));
+    break;
+  case "setup":
+    await import("./setup-ZMNTOJAV.js").then((m) => m.run(args));
     break;
   default:
     console.log(`volute \u2014 create and manage AI agents
 
 Commands:
-  volute create <name>               Create a new agent
-  volute start <name>                Start an agent (daemonized)
-  volute stop <name>                 Stop an agent
-  volute status [<name>]             Check agent status (or list all)
-  volute logs <name>                 Tail agent logs
-  volute send <name> "<msg>"         Send a message to an agent
-  volute fork <name> <variant>       Create a variant (worktree + server)
-  volute variants <name>             List variants for an agent
-  volute merge <name> <variant>      Merge a variant back
-  volute import <path>               Import an OpenClaw workspace
-  volute env <set|get|list|remove>   Manage environment variables
-  volute connect <type> <name>        Enable a connector for an agent
-  volute disconnect <type> <name>    Disable a connector for an agent
-  volute channel read <uri>          Read recent messages from a channel
-  volute channel send <uri> "<msg>"  Send a message to a channel
-  volute schedule list <agent>       List schedules for an agent
-  volute schedule add <agent> ...    Add a cron schedule
-  volute schedule remove <agent> ... Remove a schedule
-  volute history [<agent>]            View message history
-  volute up [--port N]               Start the daemon (default: 4200)
-  volute down                        Stop the daemon
-  volute upgrade <name>              Upgrade agent to latest template
-  volute delete <name> [--force]     Delete an agent (--force removes files)`);
+  volute create <name>                  Create a new agent
+  volute start <name>                   Start an agent (daemonized)
+  volute stop <name>                    Stop an agent
+  volute status [<name>]                Check agent status (or list all)
+  volute logs [--agent <name>]          Tail agent logs
+  volute send <name> "<msg>"            Send a message to an agent
+  volute variant create <name>          Create a variant (worktree + server)
+  volute variant list                   List variants for an agent
+  volute variant merge <name>           Merge a variant back
+  volute import <path>                  Import an OpenClaw workspace
+  volute env <set|get|list|remove>      Manage environment variables
+  volute connector connect <type>       Enable a connector for an agent
+  volute connector disconnect <type>    Disable a connector for an agent
+  volute channel read <uri>             Read recent messages from a channel
+  volute channel send <uri> "<msg>"     Send a message to a channel
+  volute schedule list                  List schedules for an agent
+  volute schedule add ...               Add a cron schedule
+  volute schedule remove ...            Remove a schedule
+  volute history                        View message history
+  volute up [--port N]                  Start the daemon (default: 4200)
+  volute down                           Stop the daemon
+  volute upgrade <name>                 Upgrade agent to latest template
+  volute delete <name> [--force]        Delete an agent (--force removes files)
+  volute service install [--port N]     Install as system service (auto-start)
+  volute service uninstall              Remove system service
+  volute service status                 Check service status
+  volute setup [--port N] [--host H]   Install system service with user isolation
+  volute setup uninstall [--force]     Remove system service + isolation
+
+Agent commands (variant, connector, schedule, logs, history, channel) use
+--agent <name> or VOLUTE_AGENT env var to identify the agent.`);
     if (command) {
       console.error(`
 Unknown command: ${command}`);