volute 0.2.1 → 0.3.1

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-AUCKMGPR.js

@@ -0,0 +1,15 @@
+#!/usr/bin/env node
+import {
+  AgentManager,
+  getAgentManager,
+  initAgentManager
+} from "./chunk-I6OHXCMV.js";
+import "./chunk-DNOXHLE5.js";
+import "./chunk-SOZA2TLP.js";
+import "./chunk-3C2XR4IY.js";
+import "./chunk-K3NQKI34.js";
+export {
+  AgentManager,
+  getAgentManager,
+  initAgentManager
+};

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

@@ -1,13 +1,17 @@
 #!/usr/bin/env node
 import {
   loadMergedEnv
-} from "./chunk-KFNNHQK7.js";
+} from "./chunk-DNOXHLE5.js";
+import {
+  resolveAgentName
+} from "./chunk-VRVVQIYY.js";
 import {
   parseArgs
 } from "./chunk-D424ZQGI.js";
 import {
   resolveAgent
-} from "./chunk-6UCG6MIX.js";
+} from "./chunk-3C2XR4IY.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-6UCG6MIX.js → chunk-3C2XR4IY.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";
@@ -86,7 +81,7 @@ function removeAllVariants(agentName) {
 }
 async function checkHealth(port) {
   try {
-    const res = await fetch(`http://localhost:${port}/health`, {
+    const res = await fetch(`http://127.0.0.1:${port}/health`, {
       signal: AbortSignal.timeout(2e3)
     });
     if (!res.ok) return { ok: false };
@@ -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-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-KFNNHQK7.js → chunk-DNOXHLE5.js}

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

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

@@ -1,21 +1,64 @@
 #!/usr/bin/env node
 import {
   loadMergedEnv
-} from "./chunk-KFNNHQK7.js";
+} from "./chunk-DNOXHLE5.js";
+import {
+  applyIsolation
+} from "./chunk-SOZA2TLP.js";
 import {
   agentDir,
   findAgent,
   findVariant,
   setAgentRunning,
   setVariantRunning,
-  validateBranchName
-} from "./chunk-6UCG6MIX.js";
+  validateBranchName,
+  voluteHome
+} from "./chunk-3C2XR4IY.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) {
@@ -46,7 +89,7 @@ var AgentManager = class {
     const { dir, isVariant, baseName, variantName } = target;
     const port = target.port;
     try {
-      const res = await fetch(`http://localhost:${port}/health`);
+      const res = await fetch(`http://127.0.0.1:${port}/health`);
       if (res.ok) {
         console.error(`[daemon] killing orphan process on port ${port}`);
         await killProcessOnPort(port);
@@ -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-SOZA2TLP.js

@@ -0,0 +1,81 @@
+#!/usr/bin/env node
+import {
+  validateAgentName
+} from "./chunk-3C2XR4IY.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-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-YGFIWIOF.js}

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import {
   voluteHome
-} from "./chunk-6UCG6MIX.js";
+} from "./chunk-3C2XR4IY.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
 };