@bivy/bivy 0.18.9-staging.3 → 0.18.9-staging.4

package/README.md

@@ -282,7 +282,7 @@ curl -fsSL https://bivy.sh/install.sh | bash
 
 Setup helps you choose an agent and configure remote access. Existing agents
 keep their command, login, and configuration. The installer may use `sudo` to
-install missing Node.js or Debian/Ubuntu build tools, but never for `npm install`. To inspect it first,
+install a missing Node.js, but never for `npm install`. To inspect it first,
 download it with `curl -fsSL https://bivy.sh/install.sh -o install.sh`.
 
 Already have Node.js and want to avoid sudo?

package/bin/bivy.mjs

@@ -160,6 +160,7 @@ const relaySetupEntry = path.join(repoRoot, packaged ? "dist/relay-setup.js" : "
 // artifact (src/ is not packaged), so resolve it the same packaged-aware way as
 // the runtime entries and import it dynamically at call time.
 const hostedEndpointsEntry = path.join(repoRoot, packaged ? "dist/hosted-endpoints.mjs" : "src/hosted-endpoints.mjs");
+const agentBridgesEntry = path.join(repoRoot, packaged ? "dist/agent-bridges.mjs" : "src/agent-bridges.mjs");
 const githubConnectEntry = path.join(repoRoot, packaged ? "dist/github-connect-repo.js" : "src/github-connect-repo.ts");
 const githubAppConnectEntry = path.join(repoRoot, packaged ? "dist/github-app-connect.js" : "src/github-app-connect.ts");
 const githubAppSyncEntry = path.join(repoRoot, packaged ? "dist/github-app-sync-cli.js" : "src/github-app-sync-cli.ts");
@@ -185,6 +186,27 @@ async function getHostedEndpoints() {
   return _hostedEndpoints();
 }
 
+// Agent SDK bridges (Claude, Pi) install on demand into the data dir, not with
+// Bivy — the daemon and this CLI share src/agent-bridges.mjs for it.
+function loadAgentBridges() {
+  return import(pathToFileURL(agentBridgesEntry).href);
+}
+
+/** Install any bridge packages the given agents need. True when all are present. */
+async function ensureAgentBridges(agentIds) {
+  const bridges = await loadAgentBridges();
+  const missing = [...new Set(agentIds.flatMap((id) => bridges.missingBridges(id)))];
+  if (!missing.length) return true;
+  console.log(c.dim(`Installing agent bridge ${missing.join(", ")} into ${bridges.bridgesDir()}…`));
+  try {
+    await bridges.installBridges(missing, { stdio: "inherit" });
+    return true;
+  } catch (error) {
+    console.error(c.red(error instanceof Error ? error.message : String(error)));
+    return false;
+  }
+}
+
 const SERVICE_LABEL = "dev.bivy";
 const SERVICE_UNIT = "bivy.service";
 
@@ -587,14 +609,10 @@ async function ensureDeps() {
     ));
     return false;
   }
-  if (process.platform === "linux" && (!commandExists("make") || !commandExists("g++") || !commandExists("python3"))) {
-    console.error(c.yellow("Build tools are missing. On Ubuntu/Debian run: sudo apt-get update && sudo apt-get install -y build-essential python3"));
-    console.error(c.dim("The node-pty terminal dependency needs these tools if no prebuilt binary matches this machine."));
-  }
   console.log(c.dim(`Installing dependencies (${cmd} ${args.join(" ")})…`));
   const code = await run(cmd, args, { cwd: repoRoot });
   if (code !== 0 || !fs.existsSync(dependencyMarker)) {
-    console.error(c.red(`${cmd} install failed. Install Node.js 20+ and, if native dependencies failed, build tools (make/g++/python3), then try again.`));
+    console.error(c.red(`${cmd} install failed. Install Node.js 20+, then try again.`));
     return false;
   }
   return true;
@@ -628,28 +646,6 @@ function nodePackageLoadable(packageName) {
   return runQuiet(nodeBin, ["-e", "require(require.resolve(process.argv[1], { paths: [process.argv[2]] }))", packageName, repoRoot]).code === 0;
 }
 
-async function ensureNodePackage(packageName) {
-  if (nodePackageInstalled(packageName)) {
-    console.log(c.green(`  ✓ Found Bivy bridge package ${packageName}`));
-    return true;
-  }
-  // Add with the package manager that owns this tree. Running `npm install` in a
-  // pnpm workspace would write a competing package-lock.json and a hoisted
-  // node_modules over pnpm's symlink layout, leaving the checkout in a state
-  // neither tool resolves correctly.
-  const usesPnpm = fs.existsSync(path.join(repoRoot, "pnpm-lock.yaml"));
-  const [cmd, baseArgs] = usesPnpm
-    ? [commandExists("pnpm") ? "pnpm" : "corepack", commandExists("pnpm") ? ["add"] : ["pnpm", "add"]]
-    : ["npm", ["install", "--no-audit", "--no-fund"]];
-  if (!commandExists(cmd)) {
-    console.error(c.red(`${cmd} is required to install ${packageName}.`));
-    return false;
-  }
-  console.log(c.dim(`Installing Bivy bridge package ${packageName}…`));
-  const code = await run(cmd, [...baseArgs, packageName], { cwd: repoRoot });
-  return code === 0 && nodePackageInstalled(packageName);
-}
-
 const userLocalPrefix = process.env.BIVY_NPM_GLOBAL_PREFIX || path.join(os.homedir(), ".local");
 
 async function ensureNpmCommand(command, packageName, label) {
@@ -689,10 +685,13 @@ const KNOWN_AGENT_INSTALLS = [
   { command: "gemini", npmPackage: "@google/gemini-cli", label: "Gemini CLI" },
 ];
 
-async function ensureKnownAgents() {
+async function ensureKnownAgents({ bridgesOnly = false } = {}) {
   if (process.env.BIVY_SKIP_AGENT_PREINSTALL === "1") return true;
+  const { AGENT_BRIDGES } = await loadAgentBridges();
+  const bridges = await ensureAgentBridges(Object.keys(AGENT_BRIDGES));
+  if (bridgesOnly) return bridges;
   console.log(c.dim("Ensuring known agent integrations are installed…"));
-  const results = [await ensureNodePackage("@anthropic-ai/claude-agent-sdk")];
+  const results = [bridges];
   for (const agent of KNOWN_AGENT_INSTALLS) {
     results.push(
       agent.pythonPackage
@@ -707,11 +706,15 @@ async function ensureKnownAgents() {
 
 async function ensureSetupAgent(choice) {
   if (!choice) return true;
-  if (choice.runtimeId === "pi") return ensureNpmCommand("pi", "@earendil-works/pi-coding-agent", "Pi");
+  if (choice.runtimeId === "pi") {
+    const bridge = await ensureAgentBridges(["pi"]);
+    const cli = await ensureNpmCommand("pi", "@earendil-works/pi-coding-agent", "Pi");
+    return bridge && cli;
+  }
   if (choice.runtimeId === "claude-code-sdk") {
-    const sdk = await ensureNodePackage("@anthropic-ai/claude-agent-sdk");
+    const bridge = await ensureAgentBridges(["claude-code-sdk"]);
     const cli = await ensureNpmCommand("claude", "@anthropic-ai/claude-code", "Claude Code");
-    return sdk && cli;
+    return bridge && cli;
   }
   if (choice.runtimeId === "codex-approvals") return ensureNpmCommand("codex", "@openai/codex", "Codex");
   if (choice.runtimeId === "opencode") return ensureNpmCommand("opencode", "opencode-ai/opencode", "OpenCode");
@@ -4462,12 +4465,13 @@ async function cmdDoctor(args = []) {
 
   console.log(c.bold("\n  Bivy doctor\n"));
   console.log(`  ${mark(hasSupportedNode())} Node ${process.version}${hasSupportedNode() ? "" : c.dim("  (needs >= 20.0.0)")}`);
-  const ptyInstalled = nodePackageInstalled("node-pty");
-  const ptyUsable = ptyInstalled && nodePackageLoadable("node-pty");
-  console.log(`  ${mark(ptyUsable, true)} terminal PTY ${ptyUsable ? c.green("available") : ptyInstalled ? c.yellow("installed but not loadable — reinstall after installing build tools") : c.yellow("dependency missing — reinstall Bivy; interactive terminals unavailable")}`);
-  const claudeBridge = nodePackageInstalled("@anthropic-ai/claude-agent-sdk");
+  const ptyInstalled = nodePackageInstalled("@lydell/node-pty");
+  const ptyUsable = ptyInstalled && nodePackageLoadable("@lydell/node-pty");
+  console.log(`  ${mark(ptyUsable, true)} terminal PTY ${ptyUsable ? c.green("available") : ptyInstalled ? c.yellow(`installed but not loadable — no prebuilt binary for ${process.platform}-${process.arch}, or npm ran with --omit=optional`) : c.yellow("dependency missing — reinstall Bivy; interactive terminals unavailable")}`);
+  const { bridgeInstalled } = await loadAgentBridges();
+  const claudeBridge = bridgeInstalled("@anthropic-ai/claude-agent-sdk");
   console.log(`  ${mark(claudeBridge, true)} Claude bridge ${claudeBridge ? c.green("installed") : c.dim("optional — installed on first Claude setup/use")}`);
-  const piBridge = nodePackageInstalled("@earendil-works/pi-coding-agent");
+  const piBridge = bridgeInstalled("@earendil-works/pi-coding-agent");
   const piNodeOk = nodeAtLeast(22, 19);
   console.log(`  ${mark(piBridge && piNodeOk, true)} Pi bridge ${piBridge ? (piNodeOk ? c.green("installed") : c.yellow("installed but needs Node >=22.19")) : c.dim("optional — installed only if you choose Pi")}`);
   console.log(`  ${mark(commandExists("git"), true)} git${commandExists("git") ? "" : c.dim("  (recommended for repo-backed sessions)")}`);
@@ -5549,11 +5553,11 @@ Unlike 'bivy run', these commands operate on governed background Runs with check
     case "agents:install":
     case "runtimes:install":
       if (args.includes("-h") || args.includes("--help")) {
-        console.log(`Usage: bivy agents:install\n\nInstall known agent integrations (${KNOWN_AGENT_INSTALLS.map((a) => a.label).join(", ")}).`);
+        console.log(`Usage: bivy agents:install [--bridges]\n\nInstall known agent integrations (${KNOWN_AGENT_INSTALLS.map((a) => a.label).join(", ")}).\n\n  --bridges   only install the SDK bridges Bivy loads for Claude Code and Pi\n              (they otherwise install on first use)`);
         break;
       }
       if (!(await ensureDeps())) process.exit(1);
-      await ensureKnownAgents();
+      if (!(await ensureKnownAgents({ bridgesOnly: args.includes("--bridges") })) && args.includes("--bridges")) process.exit(1);
       break;
     case "open": {
       if (args.includes("-h") || args.includes("--help")) {

package/dist/agent-bridges.d.mts

@@ -0,0 +1,26 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright (c) 2026 Petter André Sjulstad
+export interface AgentBridge {
+  command: string;
+  packages: string[];
+}
+
+export declare const AGENT_BRIDGES: Record<string, AgentBridge>;
+
+export interface ResolvedBridge {
+  dir: string;
+  version: string;
+  source: "bivy" | "bridges";
+}
+
+export declare function bridgeVersions(): Record<string, string>;
+export declare function bridgesDir(env?: Record<string, string | undefined>): string;
+export declare function resolveBridge(name: string, dir?: string): ResolvedBridge | undefined;
+export declare function bridgeInstalled(name: string, dir?: string): boolean;
+export declare function missingBridges(agentId: string, dir?: string): string[];
+export declare function bridgesToSync(options?: { dir?: string; commandExists?: (command: string) => boolean }): string[];
+export declare function installBridges(
+  names: string[],
+  options?: { dir?: string; stdio?: "inherit" | "pipe" },
+): Promise<{ installed: string[]; output: string }>;
+export declare function enableBridgeResolution(dir?: string): void;

package/dist/agent-bridges.mjs

@@ -0,0 +1,271 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright (c) 2026 Petter André Sjulstad
+// Agent bridges: the SDK packages Bivy loads in-process to drive an agent
+// (Claude's Agent SDK, Pi's coding-agent library).
+//
+// They are large (hundreds of MB together) and a node usually needs one, so
+// they are not installed with Bivy. They install on first use into a directory
+// next to the node's state, which survives `bivy update` replacing the package
+// directory, and resolve from there whenever Bivy's own node_modules lacks
+// them. In a dev checkout the workspace installs them as optionalDependencies,
+// so normal resolution finds them first and the bridge directory is unused.
+//
+// Plain JS (with a .d.mts) so the CLI in bin/ and the daemon share one copy.
+import fs from "node:fs";
+import module from "node:module";
+import path from "node:path";
+import { spawn } from "node:child_process";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+// src/ in a checkout, dist/ in a release: either way the parent is the package root.
+const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+
+/**
+ * Which bridge packages each agent loads, and the CLI whose presence means the
+ * agent is in use on this node. Adding a bridge is a row here plus a pinned
+ * entry in package.json's optionalDependencies (published as `agentBridges`).
+ */
+export const AGENT_BRIDGES = {
+  "claude-code-sdk": { command: "claude", packages: ["@anthropic-ai/claude-agent-sdk"] },
+  pi: { command: "pi", packages: ["@earendil-works/pi-coding-agent", "@earendil-works/pi-ai"] },
+};
+
+function readJson(file) {
+  try {
+    return JSON.parse(fs.readFileSync(file, "utf8"));
+  } catch {
+    return undefined;
+  }
+}
+
+function bivyManifest() {
+  return readJson(path.join(packageRoot, "package.json")) ?? {};
+}
+
+/** Pinned bridge versions: `agentBridges` in a release, optionalDependencies in a checkout. */
+export function bridgeVersions() {
+  const pkg = bivyManifest();
+  return { ...(pkg.agentBridges ?? pkg.optionalDependencies ?? {}) };
+}
+
+/** Where bridges install: $BIVY_BRIDGES_DIR, else `bridges/` in the node's data dir. */
+export function bridgesDir(env = process.env) {
+  if (env.BIVY_BRIDGES_DIR) return path.resolve(env.BIVY_BRIDGES_DIR);
+  const dataDir = env.BIVY_DATA_DIR ? path.resolve(env.BIVY_DATA_DIR) : path.join(packageRoot, ".bivy");
+  return path.join(dataDir, "bridges");
+}
+
+/** "@scope/name/sub" -> "@scope/name"; "name/sub" -> "name". */
+function packageNameOf(specifier) {
+  const parts = specifier.split("/");
+  return specifier.startsWith("@") ? parts.slice(0, 2).join("/") : parts[0];
+}
+
+function packageAt(dir) {
+  const manifest = readJson(path.join(dir, "package.json"));
+  return manifest ? { dir, version: manifest.version } : undefined;
+}
+
+/** Find `name` the way Node's resolver walks node_modules upward from `from`. */
+function findUpward(name, from) {
+  for (let dir = from; ; dir = path.dirname(dir)) {
+    const found = packageAt(path.join(dir, "node_modules", name));
+    if (found) return found;
+    if (path.dirname(dir) === dir) return undefined;
+  }
+}
+
+/**
+ * npm writes node_modules/.package-lock.json when an install finishes, and we
+ * write package.json just before starting one. An interrupted install (the
+ * daemon stopped mid-way) leaves half-extracted packages, so trust the
+ * directory only when that lockfile is newer than the manifest.
+ */
+function installComplete(dir) {
+  try {
+    return fs.statSync(path.join(dir, "node_modules", ".package-lock.json")).mtimeMs >= fs.statSync(path.join(dir, "package.json")).mtimeMs;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Where a bridge package resolves from, if anywhere: Bivy's own dependency
+ * tree first (a checkout), then the bridge directory.
+ */
+export function resolveBridge(name, dir = bridgesDir()) {
+  const own = findUpward(name, packageRoot);
+  if (own) return { ...own, source: "bivy" };
+  if (!installComplete(dir)) return undefined;
+  const bridged = packageAt(path.join(dir, "node_modules", name));
+  return bridged ? { ...bridged, source: "bridges" } : undefined;
+}
+
+export function bridgeInstalled(name, dir) {
+  return resolveBridge(name, dir) !== undefined;
+}
+
+/** Bridge packages `agentId` needs that are not resolvable yet (none for agents without a bridge). */
+export function missingBridges(agentId, dir) {
+  return (AGENT_BRIDGES[agentId]?.packages ?? []).filter((name) => !bridgeInstalled(name, dir));
+}
+
+function onPath(command, env = process.env) {
+  const exts = process.platform === "win32" ? (env.PATHEXT ?? ".EXE;.CMD").split(";") : [""];
+  for (const dir of (env.PATH ?? "").split(path.delimiter)) {
+    for (const ext of exts) {
+      try {
+        fs.accessSync(path.join(dir, command + ext), fs.constants.X_OK);
+        return true;
+      } catch {}
+    }
+  }
+  return false;
+}
+
+/**
+ * Bridge packages that should be (re)installed now: every package already in
+ * the bridge directory or belonging to an agent whose CLI is on PATH, that is
+ * either missing or not at Bivy's pinned version. Empty means nothing to do,
+ * and computing it touches no network.
+ */
+export function bridgesToSync({ dir = bridgesDir(), commandExists = onPath } = {}) {
+  const versions = bridgeVersions();
+  const wanted = new Set(Object.keys(readJson(path.join(dir, "package.json"))?.dependencies ?? {}));
+  for (const bridge of Object.values(AGENT_BRIDGES)) {
+    if (commandExists(bridge.command)) bridge.packages.forEach((name) => wanted.add(name));
+  }
+  return [...wanted].filter((name) => {
+    if (!versions[name]) return false;
+    const found = resolveBridge(name, dir);
+    return !found || (found.source === "bridges" && found.version !== versions[name]);
+  });
+}
+
+/**
+ * Replace nested copies that a bridge's own npm-shrinkwrap pins, which npm
+ * `overrides` cannot reach. Driven by the nested overrides in package.json
+ * (`"parent": { "child": "version" }`), so a new pin is data, not code.
+ */
+function applyNestedOverrides(dir) {
+  for (const [parent, pins] of Object.entries(bivyManifest().overrides ?? {})) {
+    if (!pins || typeof pins !== "object") continue;
+    const parentDir = path.join(dir, "node_modules", parent);
+    for (const [child, version] of Object.entries(pins)) {
+      const target = path.join(parentDir, "node_modules", child);
+      const nested = packageAt(target);
+      if (!nested || nested.version === version) continue;
+      const source = [packageAt(path.join(dir, "node_modules", child)), findUpward(child, packageRoot)]
+        .find((candidate) => candidate?.version === version);
+      if (!source) throw new Error(`Security patch source ${child}@${version} is missing`);
+      fs.rmSync(target, { recursive: true, force: true });
+      fs.cpSync(source.dir, target, { recursive: true });
+    }
+  }
+}
+
+/**
+ * Install `names` (at Bivy's pinned versions) into the bridge directory. The
+ * directory is an ordinary npm project that keeps earlier bridges and carries
+ * Bivy's security overrides. Optional dependencies are omitted: bridges run as
+ * libraries against the operator's own agent CLI, never their bundled binaries.
+ *
+ * `stdio: "inherit"` streams npm's output (CLI); otherwise it is captured.
+ * Installs in one process run one at a time, since they share a directory.
+ */
+let installQueue = Promise.resolve();
+export function installBridges(names, options = {}) {
+  const run = installQueue.then(() => installNow(names, options));
+  installQueue = run.catch(() => {});
+  return run;
+}
+
+function installNow(names, { dir = bridgesDir(), stdio = "pipe" } = {}) {
+  const versions = bridgeVersions();
+  const unknown = names.filter((name) => !versions[name]);
+  if (unknown.length) return Promise.reject(new Error(`Not an agent bridge: ${unknown.join(", ")}`));
+
+  fs.mkdirSync(dir, { recursive: true });
+  // npm does not repair half-extracted packages, so an interrupted earlier
+  // install is discarded rather than installed over.
+  if (!installComplete(dir)) fs.rmSync(path.join(dir, "node_modules"), { recursive: true, force: true });
+  const manifestPath = path.join(dir, "package.json");
+  const previous = readJson(manifestPath)?.dependencies ?? {};
+  const dependencies = { ...previous };
+  for (const name of names) dependencies[name] = versions[name];
+  const manifest = { name: "bivy-agent-bridges", private: true, dependencies, overrides: bivyManifest().overrides ?? {} };
+  fs.writeFileSync(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`);
+
+  return new Promise((resolve, reject) => {
+    const child = spawn("npm", ["install", "--omit=optional", "--no-audit", "--no-fund"], {
+      cwd: dir,
+      stdio: stdio === "inherit" ? "inherit" : ["ignore", "pipe", "pipe"],
+    });
+    let output = "";
+    const append = (chunk) => { output = (output + chunk.toString()).slice(-12000); };
+    child.stdout?.on("data", append);
+    child.stderr?.on("data", append);
+    child.on("error", reject);
+    child.on("close", (code) => {
+      if (code !== 0) {
+        reject(new Error(`npm could not install ${names.join(", ")} (exit ${code ?? "unknown"})${output ? `\n${output}` : ""}`));
+        return;
+      }
+      try {
+        applyNestedOverrides(dir);
+        resolve({ installed: names, output });
+      } catch (error) {
+        reject(error);
+      }
+    });
+  });
+}
+
+const NOT_FOUND = new Set(["ERR_MODULE_NOT_FOUND", "MODULE_NOT_FOUND"]);
+
+// Same fallback as the in-thread hook below, for Node versions that only have
+// module.register (off-thread, async hooks loaded from this data: URL).
+const ASYNC_HOOKS = `
+let parentURL, names;
+export function initialize(data) { parentURL = data.parentURL; names = new Set(data.names); }
+const nameOf = ${packageNameOf.toString()};
+export async function resolve(specifier, context, next) {
+  try { return await next(specifier, context); } catch (error) {
+    if (!${JSON.stringify([...NOT_FOUND])}.includes(error?.code) || !names.has(nameOf(specifier))) throw error;
+    try { return await next(specifier, { ...context, parentURL }); } catch { throw error; }
+  }
+}`;
+
+let resolutionEnabled = false;
+
+/**
+ * Let `import`/`require` of a bridge package fall back to the bridge directory
+ * when Bivy's own node_modules lacks it. Idempotent; call before loading a
+ * bridge. Only bridge package names are redirected, and only after normal
+ * resolution fails, so a checkout's workspace copies always win.
+ */
+export function enableBridgeResolution(dir = bridgesDir()) {
+  if (resolutionEnabled) return;
+  resolutionEnabled = true;
+  const parentURL = pathToFileURL(path.join(dir, "package.json")).href;
+  const names = Object.keys(bridgeVersions());
+  if (typeof module.registerHooks === "function") {
+    const bridges = new Set(names);
+    module.registerHooks({
+      resolve(specifier, context, next) {
+        try {
+          return next(specifier, context);
+        } catch (error) {
+          if (!NOT_FOUND.has(error?.code) || !bridges.has(packageNameOf(specifier))) throw error;
+          try {
+            return next(specifier, { ...context, parentURL });
+          } catch {
+            throw error;
+          }
+        }
+      },
+    });
+  } else if (typeof module.register === "function") {
+    module.register(`data:text/javascript,${encodeURIComponent(ASYNC_HOOKS)}`, { data: { parentURL, names } });
+  }
+}

package/dist/agents/claude-code/integration.js

@@ -55,7 +55,7 @@ export function claudeCodeIntegration(origin) {
                 notes: installed
                     ? "Uses the Claude Code executable already on this node, including its native auth, configuration, and sessions. Set BIVY_CLAUDE_MODEL to pick a default model."
                     : agentInstalled
-                        ? "The Claude Code agent is installed, but this Bivy distribution is missing its SDK bridge dependency."
+                        ? "The Claude Code agent is installed; Bivy installs its SDK bridge when you start the first Claude session (or run 'bivy agents:install --bridges')."
                         : "Install and sign in to Claude Code on this node; Bivy will connect to that existing agent.",
                 install: installed || agentInstalled ? undefined : {
                     label: "Install Claude Code",

package/dist/agents/claude-code/runtime.js

@@ -13,7 +13,6 @@
 //   * The SDK is loaded with a dynamic import so it stays an *optional*
 //     dependency: a Bivy install only needs it when this runtime is selected.
 import { withSessionCredentials, credentialEnvFallback } from "../../credentials/session.js";
-import { createRequire } from "node:module";
 import { randomUUID } from "node:crypto";
 import { EventEmitter } from "node:events";
 import { withExactCapabilitySurface } from "../../runtime/types.js";
@@ -30,6 +29,7 @@ import { anthropicCredentialPreflight, describeAnthropicError, isAnthropicAuthEr
 import { toModelInfo as sharedToModelInfo } from "../../runtime/normalize.js";
 import { hasLiveProcessForCwd } from "../../runtime/native-process-scan.js";
 import { bivySessionEnv } from "../../runtime/session-env.js";
+import { bridgeInstalled, enableBridgeResolution } from "../../agent-bridges.mjs";
 /** Binary names a live Claude Code process could be running under (see
  *  native-process-scan.ts's best-effort cwd match). */
 const CLAUDE_BIN_NAMES = ["claude"];
@@ -190,20 +190,15 @@ export function claudeRuntimeFromEnv() {
 }
 /** True when `@anthropic-ai/claude-agent-sdk` is resolvable in this install. */
 export function claudeSdkInstalled() {
-    try {
-        createRequire(import.meta.url).resolve(SDK_PACKAGE);
-        return true;
-    }
-    catch {
-        return false;
-    }
+    return bridgeInstalled(SDK_PACKAGE);
 }
 async function loadSdk() {
+    enableBridgeResolution();
     try {
         return await import(SDK_PACKAGE);
     }
     catch {
-        throw new Error(`The claude-code-sdk runtime requires the "${SDK_PACKAGE}" package. Install it with: npm install ${SDK_PACKAGE}`);
+        throw new Error(`The claude-code-sdk runtime requires the "${SDK_PACKAGE}" bridge. Install it with: bivy agents:install --bridges`);
     }
 }
 /**

package/dist/agents/pi/integration.js

@@ -5,6 +5,7 @@ import os from "node:os";
 import path from "node:path";
 import { defineAgentIntegration } from "../definition.js";
 import { PI_CAPABILITIES } from "./capabilities.js";
+import { bridgeInstalled, enableBridgeResolution } from "../../agent-bridges.mjs";
 export const PI_TESTED_VERSION = "0.87.1";
 export function piAgentDir() {
     return process.env.PI_CODING_AGENT_DIR?.trim() || path.join(os.homedir(), ".pi", "agent");
@@ -18,6 +19,7 @@ export function piCommand() {
  * PI_CODING_AGENT_DIR (normally ~/.pi/agent). Takeover discovery must inspect
  * that native store rather than only the governed one. */
 export async function listNativePiSessions() {
+    enableBridgeResolution();
     const { SessionManager } = await import("@earendil-works/pi-coding-agent");
     // Do not pass the sessions root here. Pi's default store is split into one
     // encoded subdirectory per cwd, and SessionManager.listAll(customDir) scans
@@ -40,13 +42,7 @@ export function piCommandAvailable() {
     return resolveExecutable(piCommand()) !== null;
 }
 export function piBridgeInstalled() {
-    try {
-        import.meta.resolve("@earendil-works/pi-coding-agent");
-        return true;
-    }
-    catch {
-        return false;
-    }
+    return bridgeInstalled("@earendil-works/pi-coding-agent");
 }
 function unsupportedNodeMessage() {
     return `Pi requires Node.js 22.19+ (found ${process.version}). Upgrade Node, or select another agent such as Claude Code/Codex/OpenCode.`;
@@ -67,6 +63,7 @@ export class LazyPiRuntime {
     async runtime() {
         if (!nodeSupportsPi())
             throw new Error(unsupportedNodeMessage());
+        enableBridgeResolution();
         this.inner ??= import("./runtime.js").then(({ PiRuntime }) => new PiRuntime(this.options));
         return this.inner;
     }

package/dist/runtime/model-namer.js

@@ -13,6 +13,7 @@
 // inference SDK, kept under src/runtime/ so the core daemon (src/server.ts) stays
 // free of any @earendil-works import.
 import { createPiModelRuntime } from "./pi-oauth.js";
+import { enableBridgeResolution } from "../agent-bridges.mjs";
 function cleanSessionName(value) {
     return value
         .replace(/[\r\n"'`]/g, " ")
@@ -54,6 +55,7 @@ export async function suggestNameFromSelectedModel(opts) {
     if (!prompt)
         return undefined;
     try {
+        enableBridgeResolution();
         const [{ completeSimple }, { ModelRegistry }] = await Promise.all([
             import("@earendil-works/pi-ai/compat"),
             import("@earendil-works/pi-coding-agent"),

package/dist/runtime/pi-oauth.js

@@ -12,6 +12,7 @@ import path from "node:path";
 import { createCredentialVault } from "./credential-store.js";
 import { isNativeOAuthProvider } from "./oauth/model-oauth-providers.js";
 import { selectedCredentialStore } from "../credentials/selected-store.js";
+import { enableBridgeResolution } from "../agent-bridges.mjs";
 /** Adapt Bivy's store to pi-ai's structurally-identical CredentialStore for injection. */
 export function piCredentialStore(store) {
     return store;
@@ -25,6 +26,7 @@ export function piCredentialStore(store) {
  */
 export async function createPiModelRuntime(opts) {
     const store = opts.store ?? createCredentialVault(opts.credsDir);
+    enableBridgeResolution();
     const { ModelRuntime } = await import("@earendil-works/pi-coding-agent");
     const selected = selectedCredentialStore(store, opts.credsDir, { workspace: opts.workspace, credentialLabels: opts.credentialLabels });
     for (const provider of Object.keys(opts.credentialLabels ?? {}))

package/dist/server.js

@@ -12,6 +12,8 @@ import { fileURLToPath } from "node:url";
 import express from "express";
 import { rateLimit } from "express-rate-limit";
 import { WebSocketServer, WebSocket } from "ws";
+import { bridgesToSync, installBridges, missingBridges } from "./agent-bridges.mjs";
+import { resolveExecutable } from "./executable.js";
 import { listRuntimes, catalogRuntimes, agentInstallSpec, canonicalAgentId, invalidateCliProbeCache, pluginAgentConflictDiagnostics } from "./runtime/index.js";
 import { createRunPolicy } from "./policy/run-policy.js";
 import { DEFAULT_BACKOFF } from "./policy/ruleset.js";
@@ -764,6 +766,35 @@ function runInstallCommand(spec) {
         });
     });
 }
+/**
+ * Install the SDK bridge packages `id` loads in-process, if any are missing
+ * (see src/agent-bridges.mjs). Bridges are not shipped with Bivy; the first
+ * session with an agent installs its bridge, announced like an agent install.
+ */
+async function ensureAgentBridges(id) {
+    const missing = missingBridges(id);
+    if (!missing.length)
+        return;
+    broadcast({ type: "runtime.install.start", id, command: `npm install ${missing.join(" ")}` });
+    await installBridges(missing);
+    invalidateCliProbeCache();
+}
+/**
+ * At startup, bring bridges up to Bivy's pinned versions, and install them for
+ * agents whose CLI is on PATH, so the first session doesn't wait on npm. This
+ * is also how a node updated from a release that bundled bridges gets them
+ * back. A no-op without network access when nothing changed.
+ */
+async function syncAgentBridges() {
+    const names = bridgesToSync({ commandExists: (command) => resolveExecutable(command) !== null });
+    if (!names.length)
+        return;
+    console.log(`[bridges] Installing agent bridges: ${names.join(", ")}`);
+    await installBridges(names);
+    invalidateCliProbeCache();
+    const runtimes = runtimeList(active?.runtimeId ?? defaultRuntimeId);
+    broadcast({ type: "runtime.updated", current: runtimeSummary(getRuntime(defaultRuntimeId)), runtimes });
+}
 /**
  * Return an available runtime, auto-installing allowlisted optional adapters when
  * a normal session/select path asks for them. The explicit /api/runtimes/install
@@ -771,6 +802,9 @@ function runInstallCommand(spec) {
  * to press it before starting a regular managed session.
  */
 async function ensureRuntimeAvailable(requested, sandbox) {
+    const bridgeAgent = canonicalAgentId(requested ?? defaultRuntimeId);
+    if (bridgeAgent)
+        await ensureAgentBridges(bridgeAgent);
     try {
         return getRuntime(requested, sandbox);
     }
@@ -2593,6 +2627,9 @@ const RELAY_COMMANDS = {
             return;
         }
         try {
+            // A missing bridge also reads as "not available"; install it first so an
+            // agent whose CLI is already here isn't reinstalled for nothing.
+            await ensureAgentBridges(spec.id);
             const before = runtimeList().find((runtime) => runtime.id === spec.id);
             if (before?.status !== "available")
                 await runInstallCommand(spec);
@@ -11413,6 +11450,7 @@ const server = app.listen(port, host, async () => {
     console.log(`Agent data dir: ${piDir}`);
     console.log(`Workspace: ${defaultWorkspace}`);
     startRelayIfConfigured();
+    void syncAgentBridges().catch((error) => console.warn("[bridges] Could not install agent bridges; they will install on first use:", error instanceof Error ? error.message : error));
     if (appGateway) {
         appGateway.server.on("error", (error) => { console.error("[apps] Preview gateway could not start:", error); shutdown("preview gateway failure"); });
         appGateway.server.listen(appPreviewPort, "127.0.0.1", () => console.log(`[apps] Preview gateway listening on 127.0.0.1:${appPreviewPort}`));

package/dist/terminal.js

@@ -1,26 +1,24 @@
 // SPDX-License-Identifier: AGPL-3.0-only
 // Copyright (c) 2026 Petter André Sjulstad
 import { randomUUID } from "node:crypto";
-import fs from "node:fs";
 import { resolveExecutable } from "./executable.js";
 import { createRequire } from "node:module";
-import path from "node:path";
 import { depCacheEnv } from "./harness/dep-cache.js";
 let ptyModule;
 export function loadPty() {
     if (ptyModule)
         return ptyModule;
     if (ptyModule === null) {
-        throw new Error("PTY support is unavailable because the node-pty dependency is not installed. Reinstall Bivy after installing build tools, or use governed chat/exec sessions instead of interactive terminals.");
+        throw new Error("PTY support is unavailable because the node-pty dependency is not installed. Reinstall Bivy, or use governed chat/exec sessions instead of interactive terminals.");
     }
     try {
-        ptyModule = createRequire(import.meta.url)("node-pty");
+        ptyModule = createRequire(import.meta.url)("@lydell/node-pty");
         return ptyModule;
     }
     catch (error) {
         ptyModule = null;
         const detail = error instanceof Error && error.message ? ` (${error.message.split("\n")[0]})` : "";
-        throw new Error(`PTY support is unavailable because the node-pty dependency could not be loaded${detail}. Reinstall Bivy after installing build tools, or use governed chat/exec sessions instead of interactive terminals.`);
+        throw new Error(`PTY support is unavailable because the node-pty dependency could not be loaded${detail}. Prebuilt terminals cover macOS, Windows and glibc Linux on x64/arm64; reinstall Bivy, or use governed chat/exec sessions instead of interactive terminals.`);
     }
 }
 /**
@@ -72,57 +70,6 @@ function defaultShell() {
  * PTY an unambiguous absolute path.
  */
 export { resolveExecutable } from "./executable.js";
-/**
- * Restore the execute bit on node-pty's bundled `spawn-helper` binary.
- *
- * On macOS/Linux, node-pty launches every PTY by exec'ing this helper. Its
- * prebuilds ship without the execute bit (mode 0664), and a fresh `npm install`
- * — exactly what `bivy update` runs — resets the bit. node-pty does not surface
- * this: its spawn prints the cryptic "posix_spawnp failed." into the terminal and
- * exits, so `bivy run <agent>` dies before the agent starts and keeps breaking
- * after every update until someone runs `chmod +x` by hand.
- *
- * Fix it once, up front, so runs survive updates and reinstalls automatically.
- * Best-effort and idempotent: if node-pty can't be resolved or the helper is
- * already executable, this is a no-op and node-pty reports its own errors.
- */
-let spawnHelperEnsured = false;
-function ensureSpawnHelperExecutable() {
-    if (spawnHelperEnsured)
-        return;
-    spawnHelperEnsured = true;
-    if (process.platform === "win32")
-        return; // Windows has no spawn-helper.
-    const makeExecutable = (file) => {
-        try {
-            const st = fs.statSync(file);
-            if (!st.isFile() || (st.mode & 0o111) !== 0)
-                return; // missing or already +x
-            fs.chmodSync(file, st.mode | 0o755);
-        }
-        catch {
-            // Missing candidate or read-only install — best-effort.
-        }
-    };
-    try {
-        const require = createRequire(import.meta.url);
-        const root = path.dirname(require.resolve("node-pty/package.json"));
-        // Cover both a from-source build and the prebuilt binaries node-pty ships.
-        makeExecutable(path.join(root, "build", "Release", "spawn-helper"));
-        const prebuilds = path.join(root, "prebuilds");
-        try {
-            for (const dir of fs.readdirSync(prebuilds)) {
-                makeExecutable(path.join(prebuilds, dir, "spawn-helper"));
-            }
-        }
-        catch {
-            // No prebuilds directory — fine.
-        }
-    }
-    catch {
-        // Couldn't resolve node-pty; leave it to node-pty to report.
-    }
-}
 export class TerminalManager {
     terminals = new Map();
     /** The number of live terminals (for tests / capacity reporting). */
@@ -158,10 +105,6 @@ export class TerminalManager {
                 ? `Cannot run "${shell}": command not found or not executable on the node's PATH. Install it, or check the command.`
                 : `Cannot start a terminal: no usable shell found (tried "${shell}"). Set the SHELL environment variable.`);
         }
-        // node-pty exec's a bundled `spawn-helper` whose execute bit a fresh install
-        // (e.g. `bivy update`) strips — restore it before spawning or this fails with
-        // "posix_spawnp failed." See ensureSpawnHelperExecutable().
-        ensureSpawnHelperExecutable();
         const pty = loadPty();
         const proc = pty.spawn(resolved, shellArgs, {
             name: "xterm-256color",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bivy/bivy",
-  "version": "0.18.9-staging.3",
+  "version": "0.18.9-staging.4",
   "type": "module",
   "license": "AGPL-3.0-only",
   "description": "Run coding agents on machines you own. Open-source, self-hostable agent workspace.",
@@ -34,16 +34,15 @@
     "bivy": "node bin/bivy.mjs",
     "start": "node dist/server.js",
     "dev": "node dist/server.js",
-    "relay:setup": "node bin/bivy.mjs relay:setup",
-    "postinstall": "node bin/repair-pty-permissions.mjs && node bin/patch-pi-dependencies.mjs"
+    "relay:setup": "node bin/bivy.mjs relay:setup"
   },
   "dependencies": {
+    "@lydell/node-pty": "1.2.0-beta.15",
     "@modelcontextprotocol/sdk": "1.30.0",
     "@novnc/novnc": "1.7.0",
     "brace-expansion": "5.0.12",
     "express": "^5.2.1",
     "express-rate-limit": "^8.7.0",
-    "node-pty": "^1.1.0",
     "semver": "^7.7.2",
     "typebox": "^1.3.34",
     "undici": "8.10.2",
@@ -51,11 +50,6 @@
     "yaml": "^2.9.1",
     "zod": "^4.6.5"
   },
-  "optionalDependencies": {
-    "@anthropic-ai/claude-agent-sdk": "0.3.281",
-    "@earendil-works/pi-ai": "0.87.1",
-    "@earendil-works/pi-coding-agent": "0.87.1"
-  },
   "overrides": {
     "fast-uri": "3.1.6",
     "hono": "4.13.5",
@@ -71,6 +65,11 @@
     "lodash-es": "4.18.1",
     "undici": "8.10.2"
   },
-  "readme": "# Bivy\n\n[![npm](https://img.shields.io/npm/v/@bivy/bivy?color=2b6cb0&label=%40bivy%2Fbivy)](https://www.npmjs.com/package/@bivy/bivy)\n[![license: AGPL-3.0-only](https://img.shields.io/badge/license-AGPL--3.0--only-2b6cb0)](LICENSE)\n[![node](https://img.shields.io/badge/node-%E2%89%A520-2b6cb0)](https://nodejs.org)\n\n**Build, try, and review apps from your phone. Your coding agent and dev\nenvironment stay on your own machines.**\n\nBivy is an open-source remote development environment built around coding\nagents. Ask for a change, try the running app, and point to or draw on what\nneeds fixing. Send that feedback to the agent and try again—all in the same\nsession, without going back to your computer.\n\nLive previews bring your app to your phone or browser without deploying it to\nRender, building a Docker image, or setting up a separate preview server.\nShare a preview link so someone else can try it and leave notes, too.\n\nKeep Claude Code, Codex, Pi, OpenCode, or another supported agent. Keep your\nrepos, tools, databases, and development environment. Bivy connects them to\nchat, a terminal, app previews, and code review wherever you are. Start work\nyourself, or let an issue, CI failure, message, schedule, or webhook start it.\n\n**[Start free on Bivy Cloud](https://app.bivy.sh)** ·\n**[Quickstart](docs/quickstart.md)** ·\n**[Documentation](docs/README.md)** ·\n**[Self-host](docs/deploy-images.md)** ·\n**[Website](https://bivy.sh)**\n\n**Recommended:** sign in at [app.bivy.sh](https://app.bivy.sh), then copy your\npersonalized **Connect a Machine** command into a terminal on your Mac or Linux\ncomputer. It installs and enrolls the machine without another Bivy login. The\nbrowser connects automatically; choose a repository and send your first task\nright there.\n\nPrefer starting from the terminal?\n\n```bash\ncurl -fsSL https://bivy.sh/install.sh | bash  # install + guided setup\ncd your-repo\nbivy run claude                            # or codex, pi, opencode\nbivy open                                  # continue in the web app (needs remote setup)\n```\n\nBivy Cloud hosts the app, control plane, and relay—not the machines running your\nagents. Connect a Mac, Linux computer, or existing server and bring your own\nagent subscription, model API key, or local model. You can also self-host the\nentire remote-access stack.\n\n> **Bivy is 0.x software.** Claude Code, Codex, Pi, and OpenCode are the\n> release-tested paths. Credential sync, resume, handoffs, approvals, and\n> sandboxing depend on the runtime. See the\n> [runtime support matrix](docs/runtime-support-matrix.md).\n\n## Build → preview → mark up → iterate\n\nRemote chat lets you ask an agent for a change. Bivy also lets you **use what\nit built and show it what to fix**, without a separate deployment step.\n\n1. **Ask for a change.** The agent works in your repo with your existing tools\n   and local services.\n2. **Try the app.** Open a live preview from the session. Use the running app,\n   not just a screenshot of what the agent says it finished. Bivy can discover\n   dev servers running in the session workspace; tap **Preview** to open one.\n3. **Mark up what needs work.** Point at an element or circle and draw on the\n   preview. Add a note, then send the draft to the agent with the element and\n   page context. Marked-up screenshots and before/after comparison are available\n   when agent screenshots are enabled.\n4. **Iterate and review.** Try the next version, inspect the diff, review checks,\n   and decide when the work is ready—not just when the agent stops.\n5. **Bring someone else into the review.** Copy a public preview link so they\n   can use the app without a Bivy account and leave notes on specific elements.\n   Bring their notes into the session when you're ready to act on them.\n\nOn Bivy Cloud, preview delivery is built in: no per-app domains, certificates,\npublic ports, or tunnels to configure. Self-hosters configure preview delivery\nonce for their Bivy deployment, not for every app. The app still needs its normal\nbuild or dev-server setup, and **the machine serving it must stay awake and\nonline**. These are development previews, not production hosting.\n\n**Share deliberately:** anyone with a preview link can use that app, including\nits live backend. Links expire after 24 hours and can be revoked sooner.\nReviewer notes aren't sent to the agent automatically; you send them or explicitly\nallow agent access. Preview traffic uses HTTPS through the preview relay, not\nsession end-to-end encryption; the relay operator can see it.\n\n[App previews, visual feedback, and sharing →](docs/apps.md)\n\n## Your agents and machines, one workspace\n\n| Capability | What it means for you |\n|---|---|\n| **One workspace, multiple agents** | Use different agents and models for different tasks without maintaining a separate workflow for each. |\n| **Your machines and environment** | Work beside your existing repos, dev servers, databases, private networks, toolchains, and GPUs. |\n| **Automations and triggers** | Let issues, failed CI, messages, schedules, and webhooks start work instead of copying requests into a chat. |\n| **Encrypted key and OAuth sync** | Reuse Bivy-managed provider credentials across enrolled machines and compatible runtimes, with less repeated setup. |\n| **Live sessions from anywhere** | Build and review from your phone, browser, or terminal; answer questions and approve supported actions in the same session. |\n| **Live app previews** | Try the running app without deploying it to a separate hosting service. |\n| **Visual feedback and sharing** | Point, draw, and send specific feedback to the agent; share a preview link for outside review. |\n| **Reviewable results** | Inspect the app, changes, declared checks, artifacts, and pull requests—not just an agent's claim that it finished. |\n| **Hosted convenience or self-hosting** | Use Bivy Cloud for managed remote access, or run the same open-source core yourself. |\n\n## One workflow, from trigger to review\n\n```text\nPrompt · GitHub issue · CI failure · Linear · Slack · Schedule · Webhook\n                                 │\n                                 ▼\n                   Choose machine + agent + model\n                     + supported credentials\n                                 │\n                                 ▼\n                         Live agent session\n                     Join · steer · approve · stop\n                                 │\n                                 ▼\n                  Try app · inspect changes · checks\n                                 │\n                                 ▼\n                  Mark up · send feedback · iterate\n                                 │\n                                 ▼\n                      Share preview · review PR\n```\n\nA **Machine** is a computer or server you connect. A **Session** is live agent\nwork on that machine. A **Run** is delegated background work that creates a\nsession and tracks its outcome. An **Automation** is a reusable definition that\ncreates runs when an event matches.\n\nManual and automated work use the same kind of live session. You can join a run\nwhen it needs help rather than wait for a black-box job to finish.\n\n### Work in the environment you already have\n\nA clean cloud sandbox isn't always enough. Your agent may need the database\nrunning on localhost, an uncommitted change, an internal API behind your VPN,\nor a model running on your GPU. Bivy runs the agent where those things already\nexist, subject to that machine's permissions and the runtime's protection.\n\nConnect several machines to the same account: a laptop for interactive work,\na Linux server for background jobs, or a GPU box for local inference. Choose\nthe machine for each session or pin it in an automation. Repository runs can\nuse isolated Git worktrees without rebuilding the whole development environment.\n\n**The execution machine must stay awake and online.** To close your laptop and\nleave work running, run the agent on a different, always-on machine.\n\n[Environment and multi-machine recipes →](docs/capability-recipes.md)\n\n### Use multiple agents, not multiple disconnected workflows\n\nRun Claude Code for one task, Codex for another, and Pi or OpenCode where they\nfit. Bivy supplies the shared session, remote-access, automation, and review\nsurfaces; your chosen agent still does the coding and uses your model provider.\n\n- Choose an agent and, where supported, a model for each session or run.\n- Import existing Claude Code and Codex sessions.\n- Fork or move work to another agent or machine when a different setup fits\n  better. Continuation fidelity varies: some paths preserve native history,\n  while others replay portable turns or seed the destination with context.\n- Use agent-native logins, Bivy-managed credentials, or local inference.\n  Bivy's custom OpenAI-compatible endpoint registry currently feeds Pi;\n  other agents may need their own provider configuration.\n- Register your own ACP or headless process agent with `bivy agent add`.\n\nBivy does not replace your agent, provide model inference, or make every agent's\nfeatures identical. Consult the [support matrix](docs/runtime-support-matrix.md)\nand [handoff recipes](docs/capability-recipes.md#fork-or-move-a-session).\n\n### Less signing in. Less copying secrets.\n\nBivy syncs **Bivy-managed API keys and supported OAuth credentials** across\nenrolled machines for compatible runtimes. Connect supported credentials once\nand reuse them where you run work, rather than manually distributing keys to\neach machine.\n\nFor ordinary account sync, credentials are encrypted on the node before upload.\nThe control plane stores ciphertext and wrapped-key metadata; enrolled nodes\nshare access by wrapping the vault key to one another. Bivy Cloud does not\nreceive plaintext credentials through this sync path.\n\nYou can also keep credentials local, use labeled keys and project presets, or\nreference environment variables and 1Password instead of embedding secrets in\nconfiguration:\n\n```bash\nbivy provider login\nbivy credentials add anthropic work\nbivy secrets ref github.repo-token op://Bivy/GitHub/repo-token\n```\n\n**Not every CLI login syncs.** Native agent logins may still be per-machine;\nGitHub App private-key sync is separately opt-in. If you lose every node and\ndevice able to unwrap a vault, you must sign in to providers again. Explicit\nhosted-provisioning custody grants are separate from ordinary encrypted sync.\n\n[Credential sync and runtime coverage →](docs/credential-sync.md) ·\n[Credentials guide →](docs/credentials-guide.md) ·\n[Key storage →](docs/key-management.md)\n\n### Let events start the work\n\nAutomations turn recurring or incoming work into sessions you can join,\nsupervise, and review. Choose the repository, machine, agent, model, approval\nmode, sandbox setting, and maximum attempts.\n\n| Trigger | Example workflow |\n|---|---|\n| **GitHub issues and mentions** | Label an issue `bivy` or `bivy/<machine>`, or mention your Bivy GitHub App, to work toward a pull request. |\n| **Failed CI** | Match a failed workflow, ask the agent to reproduce it, make a fix, and run the affected checks. |\n| **Linear** | Label an issue to start work without copying its description into an agent. |\n| **Slack** | Send a request from the conversation where the work came up. |\n| **Schedules** | Run a weekly dependency review, recurring maintenance, or a one-time task. |\n| **Signed webhooks** | Connect alerts, internal tools, or your own event sources. |\n\nConfigure automations in the app or version them with your repository in\n`.bivy/automations.yaml`:\n\n```bash\nbivy automation init\n# Edit the generated definition for your repository and workflow.\nbivy automation validate\nbivy automation test --event .bivy/events/failed-ci.yaml  # supply a local event fixture\nbivy automation apply\n```\n\nOr delegate a one-off job without creating an automation:\n\n```bash\nbivy runs start \"Review outdated dependencies and propose a small, tested update.\"\nbivy runs wait <id>\n```\n\nRuns keep routing and lifecycle evidence, check results, and output references\nin a reviewable Receipt. For unattended issue work, Bivy runs declared repository\nchecks after the agent's turn; failed required checks fail the run even if the\nagent reports success. A completed process alone is not proof that the task\nsucceeded.\n\n[Automation recipes →](docs/capability-recipes.md#let-events-start-runs) ·\n[Automations as code →](docs/automations-as-code.md) ·\n[Run outcomes and reliability limits →](docs/automation-runs.md)\n\n### Start at your desk. Continue anywhere.\n\nOpen the same session in the browser, phone PWA, or terminal. Watch work live,\nanswer questions, approve supported tool calls, or stop the agent.\n\n- Send screenshots, images, logs, and other files from your phone.\n- Download reports and artifacts the agent creates.\n- Open [session apps](docs/apps.md) from chat or the **Apps** menu: live web\n  previews, desktop app views, and CLI/TUI tools. Agents can publish views with\n  `bivy app publish bivy.app.json` and create share links with `bivy app share`.\n- Use voice input and read-aloud where supported; provider-backed voice may\n  send audio or text to the selected provider.\n- Keep a native terminal workflow or use structured chat, depending on the agent.\n\n```bash\nbivy run claude --no-follow  # start without attaching\nbivy open                    # open the web app\nbivy resume                  # return to the session in your terminal\nbivy link                    # pair a device directly via QR\n```\n\nNo phone app installation is required. Open [app.bivy.sh](https://app.bivy.sh)\nin your browser; adding it to your home screen is optional.\n\n[Remote access →](docs/remote-access.md) ·\n[Voice, files, and terminal recipes →](docs/capability-recipes.md)\n\n## Get started\n\n### Install\n\nBivy supports **macOS and Linux with Node.js 20+**. The installer installs the\n`@bivy/bivy` package, runs guided setup, and starts a launchd or systemd service:\n\n```bash\ncurl -fsSL https://bivy.sh/install.sh | bash\n```\n\nSetup helps you choose an agent and configure remote access. Existing agents\nkeep their command, login, and configuration. The installer may use `sudo` to\ninstall missing Node.js or Debian/Ubuntu build tools, but never for `npm install`. To inspect it first,\ndownload it with `curl -fsSL https://bivy.sh/install.sh -o install.sh`.\n\nAlready have Node.js and want to avoid sudo?\n\n```bash\nnpm install -g @bivy/bivy\nbivy setup\n```\n\nThen try one small task:\n\n```bash\ncd your-repo\nbivy run claude\n# Ask: \"Explain this repo and make one small, safe improvement. Run the relevant checks.\"\nbivy open\n```\n\nOpen that same session on your phone while it runs. For a web app, ask the agent\nto start its dev server, then open **Apps → Running in this workspace → Preview**.\nTry a page, point to something you'd change, and send the feedback back to the\nagent. No separate preview deployment needed.\n\nOnce that works, share a preview for review, connect another machine, or add\nyour first automation.\n\n**Local-only works too.** `bivy run`, `bivy resume`, and `bivy sessions` need no\naccount or server. Choose **local only for now** during setup; use `bivy login`\nlater. Browser and phone access need a hosted or self-hosted control plane;\nthe node itself does not serve a web UI.\n\n[Full quickstart →](docs/quickstart.md) ·\n[Installer options, service management, and uninstall →](docs/install.md)\n\n### Choose hosted or self-hosted\n\n| Option | What you get |\n|---|---|\n| **Free Cloud — $0** | Every launch feature, including automations; 10 new remote sessions per rolling seven days. No credit card required. |\n| **Cloud — $15/month** | The same features with unlimited remote sessions. |\n| **Self-hosted Core** | Operate the app, control plane, and relay yourself, with no Bivy usage limits. |\n\nManual and automated sessions share the Cloud allowance. Resuming existing\nsessions and viewing history do not consume it. Agent subscriptions and model\nprovider charges are separate. See [current pricing](https://bivy.sh#pricing).\n\n**Self-host anywhere:** deploy the public control-plane (including the web app)\nand relay images with Postgres and [a small set of environment variables](docs/deploy-images.md).\nYour server or container platform handles HTTPS. Set up owner access in the\nbrowser—no SSH, external authentication provider, or Bivy Cloud account required.\nFor a bare VPS, the [Compose installer](docs/self-host-quickstart.md) automates the\nsame stack. These onboarding features require a release containing them.\n\nStart on Cloud and self-host later if you prefer. Deploy the stack, reconnect\nmachines with `bivy relay:setup`, and pair devices to your server. This is not a\none-click migration of your Cloud account; your local repos and agent\nconfiguration stay in place.\n\n```bash\nbivy relay:setup \\\n  --control-plane https://bivy.example.com \\\n  --relay wss://relay.example.com\n```\n\nSelf-hosting is community-supported: you own TLS, backups, upgrades, and\nhardening. Public multi-architecture images are available as\n`ghcr.io/bivysh/bivy-control-plane` and `ghcr.io/bivysh/bivy-relay`; pin a release\nversion or full commit SHA.\n\n[Deploy the images anywhere →](docs/deploy-images.md) ·\n[Optional VPS installer →](docs/self-host-quickstart.md) ·\n[Operations reference →](docs/self-host.md)\n\n## Architecture\n\nYour environment, with clear security boundaries:\n\n```text\nYour machine                         Hosted or self-hosted\n┌──────────────────────┐             ┌──────────────────────┐\n│ Node daemon          │──outbound──▶│ Relay                │\n│ Agents, repos, tools │             │ Encrypted frames     │\n│ Local credentials    │             └──────────┬───────────┘\n└──────────────────────┘                        │\n                                    Browser / phone\n                                    + control plane\n                                    (app, accounts, metadata)\n```\n\n- **Execution stays on your machine.** Bivy Cloud does not run your agents.\n  Your model provider still sees whatever the agent sends it.\n- **Interactive session traffic is end-to-end encrypted** between the node and\n  paired devices. The relay forwards opaque session frames; your node dials out,\n  so no inbound public port is required.\n- **App previews have a separate security boundary.** Preview traffic uses HTTPS\n  and an outbound tunnel, not session E2E encryption. The preview ingress/relay\n  operator can see it. Public preview links grant anyone holding them access to\n  that view and its live backend until expiry or revocation. See\n  [preview security and sharing](docs/apps.md#runtime-and-security-boundaries).\n- **Ordinary credential sync uploads ciphertext, not plaintext keys.**\n  Supported credentials and recovery limits are documented separately.\n- **Encryption is not universal across integrations.** Slack commands and\n  generic webhook instructions reach the control plane in plaintext. Do not\n  put secrets in them. Routing and bounded run metadata are also visible there.\n- **Device authorization matters.** QR pairing authorizes a device directly\n  through the node. Hosted account pairing trusts the control plane to authorize\n  devices and serve the web app that holds client keys.\n- **Bivy is not an OS-level sandbox.** The default approval mode is\n  `autonomous`; protection depends on the runtime. Some agents enforce sandbox\n  tiers, while process agents may run with your full user permissions.\n  Heuristic tool checks help prevent accidents but are not isolation.\n\nReview the runtime's Protection label and configure approval/sandbox settings\nfor the task, especially before enabling unattended work.\n\n[Security model and known limitations →](docs/security-model.md) ·\n[Runtime protection matrix →](docs/runtime-support-matrix.md) ·\n[Configuration →](docs/configuration.md)\n\n## Agents and everyday commands\n\n**Claude Code, Codex, Pi, and OpenCode are release-tested.** Additional adapters\ninclude Gemini CLI, Qwen Code, Goose, Aider, Cline, Crush, Cursor, GitHub Copilot,\nGrok, Amp, Auggie, Droid, Continue, Kilo Code, and Rovo Dev. Installation,\nresume, model selection, and tool protection vary—see the\n[support matrix](docs/runtime-support-matrix.md) and [agent guides](docs/agents/README.md).\n\nRun an arbitrary command with `bivy run -- ./your-agent --flags`, register a\nreusable entry with `bivy agent add`, or package a declarative integration with\nexperimental [plugins](docs/plugins.md).\n\n```bash\nbivy run claude       # launch a durable session; also codex, pi, opencode\nbivy sessions         # list live and saved sessions\nbivy resume           # resume the most recent session\nbivy open             # open the web app (requires remote setup)\nbivy nodes            # list connected account machines\nbivy runs list        # inspect delegated work\nbivy automation init  # scaffold repo-owned automations\nbivy provider login   # connect supported model credentials\nbivy agent add        # register an ACP or process agent\nbivy doctor           # check installation and connectivity\nbivy logs -f          # follow node logs\nbivy update           # update and restart the service\n```\n\n`bivy update` uses your original installation method and waits for an active\nturn to finish before restarting. Use `--force` to skip that wait.\n\n[CLI reference →](docs/cli-reference.md) ·\n[Node and project configuration →](docs/config-as-code.md) ·\n[GitHub setup →](docs/github-setup.md) ·\n[Linear setup →](docs/linear-work-queue.md)\n\n## Development and contributions\n\n```bash\npnpm install\npnpm run dev          # node daemon on http://localhost:4317\npnpm run dev:web      # web client dev server\n```\n\n| Directory | Contents |\n|---|---|\n| `src/`, `bin/` | Node daemon, CLI, runtime adapters, sessions, approvals, secrets |\n| `packages/core/` | Shared protocol, pairing, and wire format |\n| `packages/web/`, `packages/ui/` | React PWA and shared design system |\n| `services/relay/` | Self-hostable encrypted relay |\n| `services/control-plane/` | Self-hostable control plane |\n| `deploy/` | Deployment examples |\n\n```bash\npnpm run typecheck\npnpm run typecheck:web\npnpm run lint\npnpm run test:unit\npnpm run test:core\npnpm run check:licenses\npnpm run check:secrets\n```\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for the development workflow. Releases\nare published from CI with provenance attestations; see\n[release verification](docs/releasing.md).\n\n**Found a security issue?** Use\n[GitHub private vulnerability reporting](https://github.com/bivysh/bivy/security/advisories/new),\nnot a public issue. See [SECURITY.md](SECURITY.md).\n\n### In development—not available at launch\n\nAutomatically provisioned, short-lived **ephemeral machines** are in development\nfor hosted and bring-your-own-cloud deployments. Neither path is ready or\nsupported for this launch. Use an existing computer or server you operate.\nExperimental provisioning has different credential-custody and encryption\nboundaries; see the [provisioning trust model](docs/hosted-provisioning-trust-model.md).\n\n## License\n\nEverything in this repository—node, CLI, web/PWA, relay, and control plane—is\nfree and open-source **AGPL-3.0-only Core**, with no Bivy usage limits. You may\nuse, modify, and self-host it under that license. If users interact with your\nmodified version over a network, section 13 requires you to offer its\ncorresponding source. See [LICENSE](LICENSE).\n\nBivy Cloud is the hosted operation of that stack plus billing and plans, in a\nseparate private repository. Contributions use the\n[DCO](CONTRIBUTING.md#certificate-of-origin); there is no CLA.\n",
-  "readmeFilename": "README.md"
+  "readme": "# Bivy\n\n[![npm](https://img.shields.io/npm/v/@bivy/bivy?color=2b6cb0&label=%40bivy%2Fbivy)](https://www.npmjs.com/package/@bivy/bivy)\n[![license: AGPL-3.0-only](https://img.shields.io/badge/license-AGPL--3.0--only-2b6cb0)](LICENSE)\n[![node](https://img.shields.io/badge/node-%E2%89%A520-2b6cb0)](https://nodejs.org)\n\n**Build, try, and review apps from your phone. Your coding agent and dev\nenvironment stay on your own machines.**\n\nBivy is an open-source remote development environment built around coding\nagents. Ask for a change, try the running app, and point to or draw on what\nneeds fixing. Send that feedback to the agent and try again—all in the same\nsession, without going back to your computer.\n\nLive previews bring your app to your phone or browser without deploying it to\nRender, building a Docker image, or setting up a separate preview server.\nShare a preview link so someone else can try it and leave notes, too.\n\nKeep Claude Code, Codex, Pi, OpenCode, or another supported agent. Keep your\nrepos, tools, databases, and development environment. Bivy connects them to\nchat, a terminal, app previews, and code review wherever you are. Start work\nyourself, or let an issue, CI failure, message, schedule, or webhook start it.\n\n**[Start free on Bivy Cloud](https://app.bivy.sh)** ·\n**[Quickstart](docs/quickstart.md)** ·\n**[Documentation](docs/README.md)** ·\n**[Self-host](docs/deploy-images.md)** ·\n**[Website](https://bivy.sh)**\n\n**Recommended:** sign in at [app.bivy.sh](https://app.bivy.sh), then copy your\npersonalized **Connect a Machine** command into a terminal on your Mac or Linux\ncomputer. It installs and enrolls the machine without another Bivy login. The\nbrowser connects automatically; choose a repository and send your first task\nright there.\n\nPrefer starting from the terminal?\n\n```bash\ncurl -fsSL https://bivy.sh/install.sh | bash  # install + guided setup\ncd your-repo\nbivy run claude                            # or codex, pi, opencode\nbivy open                                  # continue in the web app (needs remote setup)\n```\n\nBivy Cloud hosts the app, control plane, and relay—not the machines running your\nagents. Connect a Mac, Linux computer, or existing server and bring your own\nagent subscription, model API key, or local model. You can also self-host the\nentire remote-access stack.\n\n> **Bivy is 0.x software.** Claude Code, Codex, Pi, and OpenCode are the\n> release-tested paths. Credential sync, resume, handoffs, approvals, and\n> sandboxing depend on the runtime. See the\n> [runtime support matrix](docs/runtime-support-matrix.md).\n\n## Build → preview → mark up → iterate\n\nRemote chat lets you ask an agent for a change. Bivy also lets you **use what\nit built and show it what to fix**, without a separate deployment step.\n\n1. **Ask for a change.** The agent works in your repo with your existing tools\n   and local services.\n2. **Try the app.** Open a live preview from the session. Use the running app,\n   not just a screenshot of what the agent says it finished. Bivy can discover\n   dev servers running in the session workspace; tap **Preview** to open one.\n3. **Mark up what needs work.** Point at an element or circle and draw on the\n   preview. Add a note, then send the draft to the agent with the element and\n   page context. Marked-up screenshots and before/after comparison are available\n   when agent screenshots are enabled.\n4. **Iterate and review.** Try the next version, inspect the diff, review checks,\n   and decide when the work is ready—not just when the agent stops.\n5. **Bring someone else into the review.** Copy a public preview link so they\n   can use the app without a Bivy account and leave notes on specific elements.\n   Bring their notes into the session when you're ready to act on them.\n\nOn Bivy Cloud, preview delivery is built in: no per-app domains, certificates,\npublic ports, or tunnels to configure. Self-hosters configure preview delivery\nonce for their Bivy deployment, not for every app. The app still needs its normal\nbuild or dev-server setup, and **the machine serving it must stay awake and\nonline**. These are development previews, not production hosting.\n\n**Share deliberately:** anyone with a preview link can use that app, including\nits live backend. Links expire after 24 hours and can be revoked sooner.\nReviewer notes aren't sent to the agent automatically; you send them or explicitly\nallow agent access. Preview traffic uses HTTPS through the preview relay, not\nsession end-to-end encryption; the relay operator can see it.\n\n[App previews, visual feedback, and sharing →](docs/apps.md)\n\n## Your agents and machines, one workspace\n\n| Capability | What it means for you |\n|---|---|\n| **One workspace, multiple agents** | Use different agents and models for different tasks without maintaining a separate workflow for each. |\n| **Your machines and environment** | Work beside your existing repos, dev servers, databases, private networks, toolchains, and GPUs. |\n| **Automations and triggers** | Let issues, failed CI, messages, schedules, and webhooks start work instead of copying requests into a chat. |\n| **Encrypted key and OAuth sync** | Reuse Bivy-managed provider credentials across enrolled machines and compatible runtimes, with less repeated setup. |\n| **Live sessions from anywhere** | Build and review from your phone, browser, or terminal; answer questions and approve supported actions in the same session. |\n| **Live app previews** | Try the running app without deploying it to a separate hosting service. |\n| **Visual feedback and sharing** | Point, draw, and send specific feedback to the agent; share a preview link for outside review. |\n| **Reviewable results** | Inspect the app, changes, declared checks, artifacts, and pull requests—not just an agent's claim that it finished. |\n| **Hosted convenience or self-hosting** | Use Bivy Cloud for managed remote access, or run the same open-source core yourself. |\n\n## One workflow, from trigger to review\n\n```text\nPrompt · GitHub issue · CI failure · Linear · Slack · Schedule · Webhook\n                                 │\n                                 ▼\n                   Choose machine + agent + model\n                     + supported credentials\n                                 │\n                                 ▼\n                         Live agent session\n                     Join · steer · approve · stop\n                                 │\n                                 ▼\n                  Try app · inspect changes · checks\n                                 │\n                                 ▼\n                  Mark up · send feedback · iterate\n                                 │\n                                 ▼\n                      Share preview · review PR\n```\n\nA **Machine** is a computer or server you connect. A **Session** is live agent\nwork on that machine. A **Run** is delegated background work that creates a\nsession and tracks its outcome. An **Automation** is a reusable definition that\ncreates runs when an event matches.\n\nManual and automated work use the same kind of live session. You can join a run\nwhen it needs help rather than wait for a black-box job to finish.\n\n### Work in the environment you already have\n\nA clean cloud sandbox isn't always enough. Your agent may need the database\nrunning on localhost, an uncommitted change, an internal API behind your VPN,\nor a model running on your GPU. Bivy runs the agent where those things already\nexist, subject to that machine's permissions and the runtime's protection.\n\nConnect several machines to the same account: a laptop for interactive work,\na Linux server for background jobs, or a GPU box for local inference. Choose\nthe machine for each session or pin it in an automation. Repository runs can\nuse isolated Git worktrees without rebuilding the whole development environment.\n\n**The execution machine must stay awake and online.** To close your laptop and\nleave work running, run the agent on a different, always-on machine.\n\n[Environment and multi-machine recipes →](docs/capability-recipes.md)\n\n### Use multiple agents, not multiple disconnected workflows\n\nRun Claude Code for one task, Codex for another, and Pi or OpenCode where they\nfit. Bivy supplies the shared session, remote-access, automation, and review\nsurfaces; your chosen agent still does the coding and uses your model provider.\n\n- Choose an agent and, where supported, a model for each session or run.\n- Import existing Claude Code and Codex sessions.\n- Fork or move work to another agent or machine when a different setup fits\n  better. Continuation fidelity varies: some paths preserve native history,\n  while others replay portable turns or seed the destination with context.\n- Use agent-native logins, Bivy-managed credentials, or local inference.\n  Bivy's custom OpenAI-compatible endpoint registry currently feeds Pi;\n  other agents may need their own provider configuration.\n- Register your own ACP or headless process agent with `bivy agent add`.\n\nBivy does not replace your agent, provide model inference, or make every agent's\nfeatures identical. Consult the [support matrix](docs/runtime-support-matrix.md)\nand [handoff recipes](docs/capability-recipes.md#fork-or-move-a-session).\n\n### Less signing in. Less copying secrets.\n\nBivy syncs **Bivy-managed API keys and supported OAuth credentials** across\nenrolled machines for compatible runtimes. Connect supported credentials once\nand reuse them where you run work, rather than manually distributing keys to\neach machine.\n\nFor ordinary account sync, credentials are encrypted on the node before upload.\nThe control plane stores ciphertext and wrapped-key metadata; enrolled nodes\nshare access by wrapping the vault key to one another. Bivy Cloud does not\nreceive plaintext credentials through this sync path.\n\nYou can also keep credentials local, use labeled keys and project presets, or\nreference environment variables and 1Password instead of embedding secrets in\nconfiguration:\n\n```bash\nbivy provider login\nbivy credentials add anthropic work\nbivy secrets ref github.repo-token op://Bivy/GitHub/repo-token\n```\n\n**Not every CLI login syncs.** Native agent logins may still be per-machine;\nGitHub App private-key sync is separately opt-in. If you lose every node and\ndevice able to unwrap a vault, you must sign in to providers again. Explicit\nhosted-provisioning custody grants are separate from ordinary encrypted sync.\n\n[Credential sync and runtime coverage →](docs/credential-sync.md) ·\n[Credentials guide →](docs/credentials-guide.md) ·\n[Key storage →](docs/key-management.md)\n\n### Let events start the work\n\nAutomations turn recurring or incoming work into sessions you can join,\nsupervise, and review. Choose the repository, machine, agent, model, approval\nmode, sandbox setting, and maximum attempts.\n\n| Trigger | Example workflow |\n|---|---|\n| **GitHub issues and mentions** | Label an issue `bivy` or `bivy/<machine>`, or mention your Bivy GitHub App, to work toward a pull request. |\n| **Failed CI** | Match a failed workflow, ask the agent to reproduce it, make a fix, and run the affected checks. |\n| **Linear** | Label an issue to start work without copying its description into an agent. |\n| **Slack** | Send a request from the conversation where the work came up. |\n| **Schedules** | Run a weekly dependency review, recurring maintenance, or a one-time task. |\n| **Signed webhooks** | Connect alerts, internal tools, or your own event sources. |\n\nConfigure automations in the app or version them with your repository in\n`.bivy/automations.yaml`:\n\n```bash\nbivy automation init\n# Edit the generated definition for your repository and workflow.\nbivy automation validate\nbivy automation test --event .bivy/events/failed-ci.yaml  # supply a local event fixture\nbivy automation apply\n```\n\nOr delegate a one-off job without creating an automation:\n\n```bash\nbivy runs start \"Review outdated dependencies and propose a small, tested update.\"\nbivy runs wait <id>\n```\n\nRuns keep routing and lifecycle evidence, check results, and output references\nin a reviewable Receipt. For unattended issue work, Bivy runs declared repository\nchecks after the agent's turn; failed required checks fail the run even if the\nagent reports success. A completed process alone is not proof that the task\nsucceeded.\n\n[Automation recipes →](docs/capability-recipes.md#let-events-start-runs) ·\n[Automations as code →](docs/automations-as-code.md) ·\n[Run outcomes and reliability limits →](docs/automation-runs.md)\n\n### Start at your desk. Continue anywhere.\n\nOpen the same session in the browser, phone PWA, or terminal. Watch work live,\nanswer questions, approve supported tool calls, or stop the agent.\n\n- Send screenshots, images, logs, and other files from your phone.\n- Download reports and artifacts the agent creates.\n- Open [session apps](docs/apps.md) from chat or the **Apps** menu: live web\n  previews, desktop app views, and CLI/TUI tools. Agents can publish views with\n  `bivy app publish bivy.app.json` and create share links with `bivy app share`.\n- Use voice input and read-aloud where supported; provider-backed voice may\n  send audio or text to the selected provider.\n- Keep a native terminal workflow or use structured chat, depending on the agent.\n\n```bash\nbivy run claude --no-follow  # start without attaching\nbivy open                    # open the web app\nbivy resume                  # return to the session in your terminal\nbivy link                    # pair a device directly via QR\n```\n\nNo phone app installation is required. Open [app.bivy.sh](https://app.bivy.sh)\nin your browser; adding it to your home screen is optional.\n\n[Remote access →](docs/remote-access.md) ·\n[Voice, files, and terminal recipes →](docs/capability-recipes.md)\n\n## Get started\n\n### Install\n\nBivy supports **macOS and Linux with Node.js 20+**. The installer installs the\n`@bivy/bivy` package, runs guided setup, and starts a launchd or systemd service:\n\n```bash\ncurl -fsSL https://bivy.sh/install.sh | bash\n```\n\nSetup helps you choose an agent and configure remote access. Existing agents\nkeep their command, login, and configuration. The installer may use `sudo` to\ninstall a missing Node.js, but never for `npm install`. To inspect it first,\ndownload it with `curl -fsSL https://bivy.sh/install.sh -o install.sh`.\n\nAlready have Node.js and want to avoid sudo?\n\n```bash\nnpm install -g @bivy/bivy\nbivy setup\n```\n\nThen try one small task:\n\n```bash\ncd your-repo\nbivy run claude\n# Ask: \"Explain this repo and make one small, safe improvement. Run the relevant checks.\"\nbivy open\n```\n\nOpen that same session on your phone while it runs. For a web app, ask the agent\nto start its dev server, then open **Apps → Running in this workspace → Preview**.\nTry a page, point to something you'd change, and send the feedback back to the\nagent. No separate preview deployment needed.\n\nOnce that works, share a preview for review, connect another machine, or add\nyour first automation.\n\n**Local-only works too.** `bivy run`, `bivy resume`, and `bivy sessions` need no\naccount or server. Choose **local only for now** during setup; use `bivy login`\nlater. Browser and phone access need a hosted or self-hosted control plane;\nthe node itself does not serve a web UI.\n\n[Full quickstart →](docs/quickstart.md) ·\n[Installer options, service management, and uninstall →](docs/install.md)\n\n### Choose hosted or self-hosted\n\n| Option | What you get |\n|---|---|\n| **Free Cloud — $0** | Every launch feature, including automations; 10 new remote sessions per rolling seven days. No credit card required. |\n| **Cloud — $15/month** | The same features with unlimited remote sessions. |\n| **Self-hosted Core** | Operate the app, control plane, and relay yourself, with no Bivy usage limits. |\n\nManual and automated sessions share the Cloud allowance. Resuming existing\nsessions and viewing history do not consume it. Agent subscriptions and model\nprovider charges are separate. See [current pricing](https://bivy.sh#pricing).\n\n**Self-host anywhere:** deploy the public control-plane (including the web app)\nand relay images with Postgres and [a small set of environment variables](docs/deploy-images.md).\nYour server or container platform handles HTTPS. Set up owner access in the\nbrowser—no SSH, external authentication provider, or Bivy Cloud account required.\nFor a bare VPS, the [Compose installer](docs/self-host-quickstart.md) automates the\nsame stack. These onboarding features require a release containing them.\n\nStart on Cloud and self-host later if you prefer. Deploy the stack, reconnect\nmachines with `bivy relay:setup`, and pair devices to your server. This is not a\none-click migration of your Cloud account; your local repos and agent\nconfiguration stay in place.\n\n```bash\nbivy relay:setup \\\n  --control-plane https://bivy.example.com \\\n  --relay wss://relay.example.com\n```\n\nSelf-hosting is community-supported: you own TLS, backups, upgrades, and\nhardening. Public multi-architecture images are available as\n`ghcr.io/bivysh/bivy-control-plane` and `ghcr.io/bivysh/bivy-relay`; pin a release\nversion or full commit SHA.\n\n[Deploy the images anywhere →](docs/deploy-images.md) ·\n[Optional VPS installer →](docs/self-host-quickstart.md) ·\n[Operations reference →](docs/self-host.md)\n\n## Architecture\n\nYour environment, with clear security boundaries:\n\n```text\nYour machine                         Hosted or self-hosted\n┌──────────────────────┐             ┌──────────────────────┐\n│ Node daemon          │──outbound──▶│ Relay                │\n│ Agents, repos, tools │             │ Encrypted frames     │\n│ Local credentials    │             └──────────┬───────────┘\n└──────────────────────┘                        │\n                                    Browser / phone\n                                    + control plane\n                                    (app, accounts, metadata)\n```\n\n- **Execution stays on your machine.** Bivy Cloud does not run your agents.\n  Your model provider still sees whatever the agent sends it.\n- **Interactive session traffic is end-to-end encrypted** between the node and\n  paired devices. The relay forwards opaque session frames; your node dials out,\n  so no inbound public port is required.\n- **App previews have a separate security boundary.** Preview traffic uses HTTPS\n  and an outbound tunnel, not session E2E encryption. The preview ingress/relay\n  operator can see it. Public preview links grant anyone holding them access to\n  that view and its live backend until expiry or revocation. See\n  [preview security and sharing](docs/apps.md#runtime-and-security-boundaries).\n- **Ordinary credential sync uploads ciphertext, not plaintext keys.**\n  Supported credentials and recovery limits are documented separately.\n- **Encryption is not universal across integrations.** Slack commands and\n  generic webhook instructions reach the control plane in plaintext. Do not\n  put secrets in them. Routing and bounded run metadata are also visible there.\n- **Device authorization matters.** QR pairing authorizes a device directly\n  through the node. Hosted account pairing trusts the control plane to authorize\n  devices and serve the web app that holds client keys.\n- **Bivy is not an OS-level sandbox.** The default approval mode is\n  `autonomous`; protection depends on the runtime. Some agents enforce sandbox\n  tiers, while process agents may run with your full user permissions.\n  Heuristic tool checks help prevent accidents but are not isolation.\n\nReview the runtime's Protection label and configure approval/sandbox settings\nfor the task, especially before enabling unattended work.\n\n[Security model and known limitations →](docs/security-model.md) ·\n[Runtime protection matrix →](docs/runtime-support-matrix.md) ·\n[Configuration →](docs/configuration.md)\n\n## Agents and everyday commands\n\n**Claude Code, Codex, Pi, and OpenCode are release-tested.** Additional adapters\ninclude Gemini CLI, Qwen Code, Goose, Aider, Cline, Crush, Cursor, GitHub Copilot,\nGrok, Amp, Auggie, Droid, Continue, Kilo Code, and Rovo Dev. Installation,\nresume, model selection, and tool protection vary—see the\n[support matrix](docs/runtime-support-matrix.md) and [agent guides](docs/agents/README.md).\n\nRun an arbitrary command with `bivy run -- ./your-agent --flags`, register a\nreusable entry with `bivy agent add`, or package a declarative integration with\nexperimental [plugins](docs/plugins.md).\n\n```bash\nbivy run claude       # launch a durable session; also codex, pi, opencode\nbivy sessions         # list live and saved sessions\nbivy resume           # resume the most recent session\nbivy open             # open the web app (requires remote setup)\nbivy nodes            # list connected account machines\nbivy runs list        # inspect delegated work\nbivy automation init  # scaffold repo-owned automations\nbivy provider login   # connect supported model credentials\nbivy agent add        # register an ACP or process agent\nbivy doctor           # check installation and connectivity\nbivy logs -f          # follow node logs\nbivy update           # update and restart the service\n```\n\n`bivy update` uses your original installation method and waits for an active\nturn to finish before restarting. Use `--force` to skip that wait.\n\n[CLI reference →](docs/cli-reference.md) ·\n[Node and project configuration →](docs/config-as-code.md) ·\n[GitHub setup →](docs/github-setup.md) ·\n[Linear setup →](docs/linear-work-queue.md)\n\n## Development and contributions\n\n```bash\npnpm install\npnpm run dev          # node daemon on http://localhost:4317\npnpm run dev:web      # web client dev server\n```\n\n| Directory | Contents |\n|---|---|\n| `src/`, `bin/` | Node daemon, CLI, runtime adapters, sessions, approvals, secrets |\n| `packages/core/` | Shared protocol, pairing, and wire format |\n| `packages/web/`, `packages/ui/` | React PWA and shared design system |\n| `services/relay/` | Self-hostable encrypted relay |\n| `services/control-plane/` | Self-hostable control plane |\n| `deploy/` | Deployment examples |\n\n```bash\npnpm run typecheck\npnpm run typecheck:web\npnpm run lint\npnpm run test:unit\npnpm run test:core\npnpm run check:licenses\npnpm run check:secrets\n```\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for the development workflow. Releases\nare published from CI with provenance attestations; see\n[release verification](docs/releasing.md).\n\n**Found a security issue?** Use\n[GitHub private vulnerability reporting](https://github.com/bivysh/bivy/security/advisories/new),\nnot a public issue. See [SECURITY.md](SECURITY.md).\n\n### In development—not available at launch\n\nAutomatically provisioned, short-lived **ephemeral machines** are in development\nfor hosted and bring-your-own-cloud deployments. Neither path is ready or\nsupported for this launch. Use an existing computer or server you operate.\nExperimental provisioning has different credential-custody and encryption\nboundaries; see the [provisioning trust model](docs/hosted-provisioning-trust-model.md).\n\n## License\n\nEverything in this repository—node, CLI, web/PWA, relay, and control plane—is\nfree and open-source **AGPL-3.0-only Core**, with no Bivy usage limits. You may\nuse, modify, and self-host it under that license. If users interact with your\nmodified version over a network, section 13 requires you to offer its\ncorresponding source. See [LICENSE](LICENSE).\n\nBivy Cloud is the hosted operation of that stack plus billing and plans, in a\nseparate private repository. Contributions use the\n[DCO](CONTRIBUTING.md#certificate-of-origin); there is no CLA.\n",
+  "readmeFilename": "README.md",
+  "agentBridges": {
+    "@anthropic-ai/claude-agent-sdk": "0.3.281",
+    "@earendil-works/pi-ai": "0.87.1",
+    "@earendil-works/pi-coding-agent": "0.87.1"
+  }
 }

package/bin/patch-pi-dependencies.mjs

@@ -1,56 +0,0 @@
-#!/usr/bin/env node
-// SPDX-License-Identifier: AGPL-3.0-only
-// Copyright (c) 2026 Petter André Sjulstad
-/**
- * pi-coding-agent 0.82.1 publishes an npm-shrinkwrap that pins vulnerable
- * transitive packages below its own node_modules. npm overrides update the outer
- * lockfile/audit result but do not replace those shrinkwrapped files during
- * installation. Replace the affected nested packages with direct, exact patched
- * dependencies until pi publishes a corrected shrinkwrap.
- *
- * This matters for the PUBLISHED package, which users install with npm. It is a
- * no-op in this repo's own dev install: pnpm ignores a dependency's shrinkwrap
- * and resolves everything through pnpm-lock.yaml, so the vulnerable nested
- * copies are never created and the loop below finds nothing to replace. Either
- * way scripts/check-security-pins.mjs asserts the end state.
- */
-import fs from "node:fs";
-import path from "node:path";
-import { fileURLToPath } from "node:url";
-
-const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
-
-// npm-global installs usually nest dependencies under bivy, while npm/npx may
-// hoist them to an ancestor node_modules. Support both layouts.
-function findDependency(relativePath) {
-  let dir = root;
-  while (true) {
-    const candidate = path.join(dir, "node_modules", relativePath);
-    if (fs.existsSync(candidate)) return candidate;
-    const parent = path.dirname(dir);
-    if (parent === dir) return undefined;
-    dir = parent;
-  }
-}
-
-const piPackage = findDependency(path.join("@earendil-works", "pi-coding-agent"));
-if (!piPackage) process.exit(0);
-
-const patches = [
-  { name: "brace-expansion", version: "5.0.12" },
-  { name: "undici", version: "8.10.2" },
-];
-
-for (const patch of patches) {
-  const source = findDependency(patch.name);
-  const target = path.join(piPackage, "node_modules", patch.name);
-  if (!fs.existsSync(target)) continue;
-  if (!source) throw new Error(`Security patch source ${patch.name}@${patch.version} is missing`);
-  const sourcePackage = JSON.parse(fs.readFileSync(path.join(source, "package.json"), "utf8"));
-  if (sourcePackage.version !== patch.version) {
-    throw new Error(`Refusing dependency patch from unexpected ${patch.name} ${sourcePackage.version}`);
-  }
-  fs.rmSync(target, { recursive: true, force: true });
-  fs.cpSync(source, target, { recursive: true });
-  console.log(`Patched pi-coding-agent's nested ${patch.name} to ${patch.version}`);
-}

package/bin/repair-pty-permissions.mjs

@@ -1,35 +0,0 @@
-#!/usr/bin/env node
-// SPDX-License-Identifier: AGPL-3.0-only
-// Copyright (c) 2026 Petter André Sjulstad
-// node-pty 1.1.0's npm tarball ships the Darwin spawn-helper with mode 0644.
-// Loading pty.node succeeds, but opening any terminal fails with posix_spawnp.
-// Restore executable bits at install time, until upstream fixes the archive.
-import fs from "node:fs";
-import path from "node:path";
-import { createRequire } from "node:module";
-import { fileURLToPath } from "node:url";
-
-export function repairPtyPermissions(root, platform = process.platform, arch = process.arch) {
-  if (platform !== "darwin") return;
-  // resolve() handles both nested global installs and npm's hoisted layout.
-  const require = createRequire(path.join(root, "package.json"));
-  const ptyRoot = path.dirname(require.resolve("node-pty/package.json"));
-  // node-pty can load a source build or a shipped prebuild. Only change its
-  // known helper files, never recurse through arbitrary dependency executables.
-  for (const dir of ["build/Release", "build/Debug", `prebuilds/${platform}-${arch}`]) {
-    const helper = path.join(ptyRoot, dir, "spawn-helper");
-    let stat;
-    try { stat = fs.lstatSync(helper); }
-    catch (error) {
-      if (error.code === "ENOENT") continue;
-      throw error;
-    }
-    if (!stat.isFile() || (stat.mode & 0o111) === 0o111) continue;
-    fs.chmodSync(helper, (stat.mode & 0o777) | 0o111);
-    console.log(`Restored executable permissions on node-pty/${dir}/spawn-helper`);
-  }
-}
-
-if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
-  repairPtyPermissions(path.resolve(path.dirname(fileURLToPath(import.meta.url)), ".."));
-}