@bivy/bivy 0.16.7-staging.1 → 0.16.7-staging.2

package/README.md

@@ -125,8 +125,8 @@ configuration. Re-running the installer updates Bivy and restarts the service.
 without an account or server. During setup, choose **local only for now** to skip
 remote access. The browser and phone apps need a control plane: use
 [app.bivy.sh](https://app.bivy.sh) or
-[self-host one](docs/self-host-quickstart.md). You can switch later with
-`bivy relay:setup`.
+[self-host one](docs/self-host-quickstart.md). You can sign in later with
+`bivy login` (or use `bivy relay:setup` for self-hosted endpoint options).
 
 Self-hosted Bivy Core is open source and has no usage limits. Bivy Cloud offers
 a managed app, relay, and hosted Machines; see

package/bin/bivy.mjs

@@ -13,7 +13,9 @@
  *   bivy stop      stop the background service
  *   bivy restart   restart the background service (waits for active sessions to finish; --force to skip)
  *   bivy status    show config + whether the node is reachable
- *   bivy login     sign into a model provider (native Pi /login)
+ *   bivy login     sign this machine into a Bivy account
+ *   bivy logout    sign this machine out of its Bivy account
+ *   bivy provider login  sign into a model provider
  *   bivy update    update Bivy + install deps + restart service (waits for active sessions to finish; --force to skip)
  *   bivy update:log  show output of the last (or in-progress) update
  *   bivy open      open the browser UI
@@ -1802,7 +1804,7 @@ function cmdCompletions(args = []) {
   const shell = (args[0] || "").toLowerCase();
   const commands = [
     "run", "runs", "sessions", "ls", "resume", "promote", "rename", "nodes", "agent", "agents", "agents:install", "shim", "takeover", "token", "exec",
-    "send", "attach", "kill", "setup", "start", "stop", "restart", "status", "doctor", "diagnostics", "capabilities", "logs", "login",
+    "send", "attach", "kill", "setup", "start", "stop", "restart", "status", "doctor", "diagnostics", "capabilities", "logs", "login", "logout", "signout", "provider", "model",
     "update", "update:log", "audit", "automation", "config", "plugin", "open", "service", "secrets", "voice", "link", "relay:setup",
     "github:connect", "github:app-create", "github:app-connect", "github:app-sync", "prune", "uninstall", "help", "version",
   ];
@@ -1820,6 +1822,7 @@ _bivy_completions() {
   fi
   case "$prev" in
     run) COMPREPLY=( $(compgen -W "${agents.join(" ")}" -- "$cur") );;
+    provider|model) COMPREPLY=( $(compgen -W "login" -- "$cur") );;
   esac
 }
 complete -F _bivy_completions bivy`);
@@ -1835,6 +1838,8 @@ _bivy() {
     compadd -- $cmds
   elif [[ \${words[2]} == run ]]; then
     compadd -- $agents
+  elif [[ \${words[2]} == provider || \${words[2]} == model ]]; then
+    compadd -- login
   fi
 }
 compdef _bivy bivy`);
@@ -1844,7 +1849,8 @@ compdef _bivy bivy`);
     console.log(`# bivy fish completion — save to ~/.config/fish/completions/bivy.fish
 complete -c bivy -f
 complete -c bivy -n '__fish_use_subcommand' -a '${commands.join(" ")}'
-complete -c bivy -n '__fish_seen_subcommand_from run' -a '${agents.join(" ")}'`);
+complete -c bivy -n '__fish_seen_subcommand_from run' -a '${agents.join(" ")}'
+complete -c bivy -n '__fish_seen_subcommand_from provider model' -a 'login'`);
     return;
   }
   console.error(c.red("Usage: bivy completions <bash|zsh|fish>"));
@@ -3785,7 +3791,7 @@ async function cmdSetup(args = []) {
       const loginCode = await runSetupModelLogin(config);
       rl.resume();
       if (loginCode !== 0 || !hasModelConfig(loadConfig())) {
-        console.log(c.yellow("Model sign-in did not complete. The node can start, but an agent reply still requires 'bivy login'."));
+        console.log(c.yellow("Model sign-in did not complete. The node can start, but an agent reply still requires 'bivy provider login'."));
       }
       agentAuthReady = hasModelConfig(loadConfig());
     }
@@ -3848,7 +3854,7 @@ async function cmdSetup(args = []) {
   console.log(c.bold(c.green("\n  ✓ Node running. Check first-task readiness below.\n")));
   console.log(`  ${c.green("✓")} node reachable at ${url(finalConfig)}`);
   console.log(`  ${agentReady ? c.green("✓") : c.yellow("!")} runtime ${agentReady ? `${setupAgent?.label || "Pi"} available` : "not installed — run 'bivy agents:install'"}`);
-  console.log(`  ${modelReady ? c.green("✓") : c.yellow("!")} model ${modelReady ? (setupAgent?.needsBivyModel ? "credential configured" : "native agent login ready") : (setupAgent?.needsBivyModel ? "not configured — run 'bivy login'" : `${setupAgent?.loginHint || "sign in through the selected agent"}`)}`);
+  console.log(`  ${modelReady ? c.green("✓") : c.yellow("!")} model ${modelReady ? (setupAgent?.needsBivyModel ? "credential configured" : "native agent login ready") : (setupAgent?.needsBivyModel ? "not configured — run 'bivy provider login'" : `${setupAgent?.loginHint || "sign in through the selected agent"}`)}`);
   console.log(`  ${repoReady ? c.green("✓") : c.dim("○")} repository ${repoReady ? "accessible" : "choose one from the directory where you start Bivy or in the app"}`);
   const ghReady = githubConnected(finalConfig);
   console.log(`  ${ghReady ? c.green("✓") : c.dim("○")} GitHub ${ghReady ? "connected — your repos will list in the app" : c.dim("optional — connect later in the app under Settings → GitHub App")}`);
@@ -3951,7 +3957,7 @@ function printFirstRunSteps(modelReady = false, setupAgent = null) {
   console.log("  Start your first session:");
   if (!modelReady) {
     const login = setupAgent?.needsBivyModel
-      ? `${c.cyan("bivy login")}  ${c.dim("(stored in Bivy's encrypted vault)")}`
+      ? `${c.cyan("bivy provider login")}  ${c.dim("(stored in Bivy's encrypted vault)")}`
       : c.cyan(setupAgent?.command || "the selected agent's native CLI");
     console.log(`    Model access: ${login}`);
   }
@@ -4225,7 +4231,7 @@ async function cmdDoctor(args = []) {
   console.log(`  ${mark(agentAvailable, true)} agent ${runtimeInfo?.displayName || defaultAgent}${agentAvailable ? "" : c.dim(" not available — install it or run 'bivy setup'")}`);
   const credentialReady = readiness?.credential?.ok ?? hasModelConfig(config);
   const credentialKnown = readiness?.credential?.probed || readiness?.credential?.configured;
-  console.log(`  ${mark(credentialReady, authOwner !== "bivy" || !credentialKnown)} model ${credentialReady ? (readiness?.credential?.probed ? "access verified" : "configured") : authOwner === "bivy" ? c.dim("not ready — run 'bivy login'") : c.dim("agent-native auth — use the agent's CLI login if needed")}`);
+  console.log(`  ${mark(credentialReady, authOwner !== "bivy" || !credentialKnown)} model ${credentialReady ? (readiness?.credential?.probed ? "access verified" : "configured") : authOwner === "bivy" ? c.dim("not ready — run 'bivy provider login'") : c.dim("agent-native auth — use the agent's CLI login if needed")}`);
   const repositoryReady = Boolean(readiness?.repository?.ok);
   console.log(`  ${mark(repositoryReady, true)} repository ${repositoryReady ? "accessible" : c.dim("not selected or access could not be verified")}`);
   const firstTaskReady = reachable && agentAvailable && credentialReady && repositoryReady;
@@ -4642,9 +4648,9 @@ function cmdUpdateLog(args) {
   });
 }
 
-async function cmdLogin(args) {
+async function cmdProviderLogin(args) {
   if (args.includes("-h") || args.includes("--help")) {
-    console.log("Usage: bivy login [provider]\n\nSign into a model provider (Pi's native /login). With no provider, prompts interactively for the auth method and provider.");
+    console.log("Usage: bivy provider login [provider]\n       bivy model login [provider]\n\nSign into a model provider. With no provider, prompts interactively for the authentication method and provider.");
     return;
   }
   if (!(await ensureDeps())) process.exit(1);
@@ -4656,6 +4662,85 @@ async function cmdLogin(args) {
   process.exit(code);
 }
 
+async function cmdAccountLogin(args) {
+  if (args.includes("-h") || args.includes("--help")) {
+    console.log("Usage: bivy login [--github|--email <email>]\n\nSign this machine into a Bivy account and enable remote access. With no flags, choose GitHub or an emailed magic link interactively.");
+    return;
+  }
+  if (args[0] && !args[0].startsWith("-")) {
+    console.error(c.red(`'bivy login ${args[0]}' is no longer a model-provider command. Use 'bivy provider login ${args[0]}'.`));
+    process.exitCode = 1;
+    return;
+  }
+  await cmdRelaySetup(args);
+}
+
+async function cmdAccountLogout(args = []) {
+  if (args.includes("-h") || args.includes("--help")) {
+    console.log("Usage: bivy logout\n       bivy signout\n\nSign this machine out of its Bivy account. Local sessions and model-provider credentials are kept.");
+    return;
+  }
+  if (args.length) {
+    console.error(c.red(`Unknown logout option: ${args[0]}`));
+    process.exitCode = 1;
+    return;
+  }
+  if (!fs.existsSync(relayConfigPath)) {
+    console.log(c.dim("This machine is not signed into a Bivy account."));
+    return;
+  }
+
+  let relayConfig;
+  try {
+    relayConfig = JSON.parse(fs.readFileSync(relayConfigPath, "utf8"));
+  } catch (error) {
+    console.log(c.yellow(`Could not read the existing account configuration: ${error instanceof Error ? error.message : String(error)}`));
+  }
+
+  if (relayConfig?.controlPlaneUrl && relayConfig?.enrollmentToken) {
+    try {
+      const res = await fetch(`${String(relayConfig.controlPlaneUrl).replace(/\/$/, "")}/node`, {
+        method: "DELETE",
+        headers: { authorization: `Bearer ${relayConfig.enrollmentToken}` },
+      });
+      if (!res.ok && res.status !== 401 && res.status !== 404) {
+        console.log(c.yellow(`Could not remove the account's machine registration (${res.status}); signing out locally anyway.`));
+      }
+    } catch (error) {
+      console.log(c.yellow(`Could not reach the account service; signing out locally anyway (${error instanceof Error ? error.message : String(error)}).`));
+    }
+  } else if (relayConfig?.room && relayConfig?.roomToken) {
+    console.log(c.dim("This machine used account-free relay access; removing that local relay configuration."));
+  }
+
+  fs.rmSync(relayConfigPath, { force: true });
+  fs.rmSync(setupSessionPath, { force: true });
+  // This key wraps the account-level model credential vault. It must not cross
+  // an account boundary; the local provider credential store itself is kept.
+  fs.rmSync(path.join(appDir, "model-auth-vault.json"), { force: true });
+
+  const config = loadConfig();
+  if (restartService()) {
+    console.log(c.green("Signed out. Service restarted with remote account access disabled."));
+    return;
+  }
+  if (await isReachable(config)) {
+    try {
+      const token = await localDeviceToken(config);
+      await localApi(config, "/api/relay/reload", {
+        method: "POST",
+        headers: { authorization: `Bearer ${token}` },
+        body: "{}",
+      });
+      console.log(c.green("Signed out. The running node disconnected from the remote account."));
+      return;
+    } catch (error) {
+      console.log(c.yellow(`Signed out locally, but could not disconnect the running node immediately: ${error instanceof Error ? error.message : String(error)}`));
+    }
+  }
+  console.log(c.green("Signed out of Bivy on this machine."));
+}
+
 async function cmdLinkPhone(args = []) {
   if (args.includes("-h") || args.includes("--help")) {
     console.log("Usage: bivy link\n\nShow a remote web/PWA link (and QR) in the terminal, single-use and short-lived (5 minutes). Requires 'bivy relay:setup' first.");
@@ -4937,7 +5022,9 @@ ${c.bold("bivy")} — Bivy node CLI
   ${c.cyan("bivy doctor")}     Health check: deps, node, model, remote, agents
   ${c.cyan("bivy capabilities")} [--json]  What this Machine unlocks: OS, agents, providers, Docker/GPU, plugins, workspaces
   ${c.cyan("bivy logs")} [-f]   Tail the node logs (systemd journal, launchd, or background log)
-  ${c.cyan("bivy login")}      Sign into a model provider (Pi /login)
+  ${c.cyan("bivy login")}      Sign this machine into a Bivy account (GitHub or email)
+  ${c.cyan("bivy logout")}     Sign this machine out (alias: signout)
+  ${c.cyan("bivy provider login")}  Sign into a model provider (alias: model login)
   ${c.cyan("bivy update")}     Update Bivy + install deps + restart service (waits for active sessions to finish a turn; --force to skip)
   ${c.cyan("bivy update:log")} Show output of the last (or in-progress) update
   ${c.cyan("bivy agent add")}        Connect an existing user-owned agent
@@ -5144,8 +5231,25 @@ Unlike 'bivy run', these commands operate on governed background Runs with check
       await cmdLogs(args);
       break;
     case "login":
-      await cmdLogin(args);
+      await cmdAccountLogin(args);
       break;
+    case "logout":
+    case "signout":
+      await cmdAccountLogout(args);
+      break;
+    case "provider":
+    case "model": {
+      const [action, ...providerArgs] = args;
+      if (action === "login") {
+        await cmdProviderLogin(providerArgs);
+      } else if (!action || ["-h", "--help", "help"].includes(action)) {
+        console.log(`Usage: bivy ${command} login [provider]\n\nSign into a model provider. Both 'bivy provider login' and 'bivy model login' are equivalent.`);
+      } else {
+        console.error(c.red(`Unknown ${command} action: ${action}. Usage: bivy ${command} login [provider]`));
+        process.exitCode = 1;
+      }
+      break;
+    }
     case "update":
       await cmdUpdate(args);
       break;

package/dist/bivy-login.js

@@ -102,7 +102,7 @@ async function loginApiKey(provider) {
     if (provider.id === "anthropic") {
         const probe = await probeAnthropicAccess(apiKey);
         if (probe.probed && !probe.ok) {
-            console.log(`⚠ ${probe.reason || "The key was saved but Anthropic rejected it."} Double-check the key; re-run 'bivy login' to replace it.`);
+            console.log(`⚠ ${probe.reason || "The key was saved but Anthropic rejected it."} Double-check the key; re-run 'bivy provider login' to replace it.`);
         }
         else if (probe.probed) {
             console.log("✓ Verified: the key can reach the Anthropic API.");

package/dist/credentials/store.js

@@ -11,7 +11,7 @@
 // At rest the vault is encrypted (AES-256-GCM via the repo's own seal/open — no
 // third crypto implementation) under a 0600 key minted once. Writes are
 // serialized twice over: an in-process per-provider promise chain, and a
-// cross-process mkdir lock (the `bivy login` CLI writes the same file as the
+// cross-process mkdir lock (the `bivy provider login` CLI writes the same file as the
 // running daemon). `modify()` is the only write path, so every mutation is a
 // read-modify-write under the lock — the ordering OAuth refresh depends on
 // (rotated refresh tokens are single-use; a read-then-write loses that race).

package/dist/credentials-cli.js

@@ -40,7 +40,7 @@ Agent-native logins:
 Config file (${path.relative(process.cwd(), configPath) || configPath}):
   bivy credentials config path|show|edit             Print path, show, or open in $EDITOR
 
-Note: run 'bivy login' to add a provider's default OAuth/API-key login.`);
+Note: run 'bivy provider login' to add a provider's default OAuth/API-key login.`);
 }
 async function askHidden(question) {
     if (!input.isTTY) {
@@ -89,7 +89,7 @@ function kindLabel(r) {
 async function cmdList() {
     const records = [...(await listCredentialRecords(credsDir))].sort((a, b) => `${a.provider}:${a.label}`.localeCompare(`${b.provider}:${b.label}`));
     if (records.length === 0) {
-        console.log("No credentials. Add one with 'bivy credentials add', or 'bivy login'.");
+        console.log("No credentials. Add one with 'bivy credentials add', or 'bivy provider login'.");
         return;
     }
     const presets = getCredentialPresets(credsDir);

package/dist/server.js

@@ -2976,14 +2976,27 @@ async function handleRelayMessage(msg) {
         console.warn("[relay] failed to handle client message:", error);
     }
 }
+function stopRelayConnection() {
+    relay?.stop();
+    relay = undefined;
+    // Disconnecting drops any remote clients the old tunnel carried; release the
+    // shared relay size slot so local PTYs it may have shrunk grow back.
+    terminals.dropClient(RELAY_CLIENT_ID);
+    sessionAdvertiseTarget = undefined;
+    if (advertiseResyncTimer)
+        clearInterval(advertiseResyncTimer);
+    advertiseResyncTimer = undefined;
+    if (nodeHeartbeatTimer)
+        clearInterval(nodeHeartbeatTimer);
+    nodeHeartbeatTimer = undefined;
+    controlPlanePoller?.stop();
+    controlPlanePoller = undefined;
+}
 function startRelayIfConfigured() {
+    stopRelayConnection();
     const config = loadRelayConfig(appDir);
     if (!config)
         return false;
-    relay?.stop();
-    // Reconnecting drops any remote clients the old tunnel carried; release the
-    // shared relay size slot so local PTYs it may have shrunk grow back.
-    terminals.dropClient(RELAY_CLIENT_ID);
     relay = new RelayConnector(config, (msg) => void handleRelayMessage(msg), {
         pairing: pairingStore,
         onWorkAvailable: (hint) => {
@@ -7231,7 +7244,7 @@ function actionableAgentError(runtimeId, error) {
         if (id.startsWith("codex"))
             return "Codex is not signed in. Run `codex login`, then retry; the same login works from Bivy and the PWA.";
         if (id === "pi" || id === "aider")
-            return "No model credential is configured. Run `bivy login`, then retry. This is only required once and compatible credentials sync E2E-encrypted to your other Bivy nodes.";
+            return "No model credential is configured. Run `bivy provider login`, then retry. This is only required once and compatible credentials sync E2E-encrypted to your other Bivy nodes.";
         return "The selected agent needs model authentication. Sign in through its native CLI, then retry.";
     }
     return raw;
@@ -8742,8 +8755,12 @@ app.use("/api", authMiddleware(identity));
 // Reload relay.json without forcing the user to restart the whole node. This is
 // used by `bivy relay:setup` after it enrolls the node.
 app.post("/api/relay/reload", (_req, res) => {
-    const ok = startRelayIfConfigured();
-    res.status(ok ? 200 : 400).json(ok ? { ok: true } : { error: "Relay not configured" });
+    const enabled = startRelayIfConfigured();
+    if (enabled)
+        startControlPlaneTasksIfConfigured();
+    // A missing relay.json is a valid reload state: `bivy logout` removes it and
+    // calls this endpoint to disconnect a foreground node without restarting it.
+    res.json({ ok: true, enabled });
 });
 // Link a remote web/PWA device through the relay. Mints a short-lived,
 // node-scoped client grant from the control plane and packages it with the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bivy/bivy",
-  "version": "0.16.7-staging.1",
+  "version": "0.16.7-staging.2",
   "type": "module",
   "license": "AGPL-3.0-only",
   "description": "Run coding agents on machines you own. Open-source, self-hostable agent workspace.",
@@ -66,6 +66,6 @@
     "nanoid": "3.3.18",
     "undici": "8.10.0"
   },
-  "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**Run coding agents on your machines and use them from anywhere — from a phone,\nbrowser, terminal, GitHub issue, Slack message, schedule, or webhook.**\n\nStart Claude Code on your workstation, next to the repo, dev server, and\ndatabase you already use. Walk away. From your phone, you can see what it did,\nanswer a question, or approve a migration. CI or a webhook can start the next\njob on the right Machine without waiting for you to return.\n\n```bash\ncurl -fsSL https://bivy.sh/install.sh | bash  # install + guided setup\ncd your-repo\nbivy run claude                                # start an agent in this repo\nbivy open                                      # open it in a browser or on your phone\n```\n\nBivy does not replace Claude Code, Codex, or the other agents you use. It keeps\ntheir Sessions running, routes work to the right Machine, and gives you one place\nto start, join, approve, and review work.\n\nFirst thing to try: ask the agent to explain the repository, make one small safe\nchange, then open the same Session in the web app or on your phone while it runs.\n\n**[Quickstart](docs/quickstart.md)** ·\n**[Docs](docs/README.md)** ·\n**[Why Bivy](docs/why-bivy.md)** ·\n**[Security model](docs/security-model.md)** ·\n**[bivy.sh](https://bivy.sh)**\n\n> **Bivy is 0.x software.** Claude Code, Codex, Pi, and OpenCode are the\n> release-tested paths. Support for other agents varies; check the\n> [runtime support matrix](docs/runtime-support-matrix.md) before relying on a\n> specific feature.\n\n## Why not just a cloud sandbox?\n\nA hosted sandbox clones your repo into a clean environment. Bivy runs in the\nenvironment you already use: the current working tree, running services, and\nwarm caches.\n\n|  | Cloud sandbox | Bivy Machine |\n|---|---|---|\n| Your repository | a cloned copy | the real working tree, uncommitted changes and all |\n| Dev server & database | mocked, or absent | already running, right beside the agent |\n| Private networks & internal APIs | out of reach | reachable |\n| Toolchains, package caches | cold, reinstalled each time | warm, already installed |\n| GPUs / local inference | rented separately | the ones on your box |\n| Where your code sits | someone else's infrastructure | the machine you already trust |\n\nBivy lets you leave that environment running and reach it from anywhere.\n\n## What you can do\n\nEvery task in Bivy becomes a Session on a Machine you choose. Start it from the\nterminal, browser, phone, or an external trigger. Join it while it runs, or let\nit finish in the background.\n\n### Sessions\n\nStart an agent, watch it work, steer it, stop it, or approve a tool call. You can\nleave your desk and keep the Session open:\n\n```bash\nbivy run claude              # or codex, pi, gemini, and a dozen more\nbivy open                    # continue the same session in the browser or PWA\nbivy resume                  # pick it back up in the terminal\nbivy run claude --no-follow  # start it in the background instead of attaching\nbivy run claude --chat       # start a chat session and open it in the browser\n```\n\n- Reconnect to the same Session from a phone, browser, or terminal.\n- Upload files and images from your phone, or download files the agent creates.\n- Import existing Claude Code and Codex Sessions.\n- Fork or move a Session to another agent, model, or Machine.\n- Connect several Machines, such as a workstation, server, or GPU box.\n\n### Runs\n\nA Run is a Session started as a background job. Start one yourself or trigger it\nfrom another service; Bivy queues it and returns immediately:\n\n```bash\nbivy runs start \"...\"    # queue a one-off unattended Run, then `bivy runs wait <id>`\nbivy automation init     # define jobs in .bivy/automations.yaml\n```\n\n- Trigger Runs from GitHub, Linear, Slack, a schedule, CI, or a signed webhook.\n- Choose the Machine, agent, model, sandbox, approval mode, and retry limit.\n- Review the changed files, checks, and final result in a Receipt.\n\nSee the [capability recipes](docs/capability-recipes.md) for examples and the\n[runtime support matrix](docs/runtime-support-matrix.md) for per-agent support.\n\n## Bring your own agents and models\n\nUse your existing agent login, an API key in Bivy's vault, or a local\nOpenAI-compatible server. Claude Code, Codex, Pi, and OpenCode have release-tested\nintegrations. Other agents run through ACP or a headless process adapter. Add\nyour own with:\n\n```bash\nbivy agent add       # register an existing ACP or process agent\n```\n\n## Install\n\n```bash\ncurl -fsSL https://bivy.sh/install.sh | bash\n```\n\nBivy supports macOS and Linux and requires Node.js 20 or newer. The installer\nadds the [`@bivy/bivy`](https://www.npmjs.com/package/@bivy/bivy) package and\n`bivy` command, then runs `bivy setup`. Setup asks which agent to use, installs\nit if needed, configures remote access, and starts a launchd or systemd service.\n\nIf an agent is already installed, Bivy uses its existing command, login, and\nconfiguration. Re-running the installer updates Bivy and restarts the service.\n\n**Local and remote use.** `bivy run`, `bivy resume`, and `bivy sessions` work\nwithout an account or server. During setup, choose **local only for now** to skip\nremote access. The browser and phone apps need a control plane: use\n[app.bivy.sh](https://app.bivy.sh) or\n[self-host one](docs/self-host-quickstart.md). You can switch later with\n`bivy relay:setup`.\n\nSelf-hosted Bivy Core is open source and has no usage limits. Bivy Cloud offers\na managed app, relay, and hosted Machines; see\n[bivy.sh#pricing](https://bivy.sh#pricing) for details.\n\nPrefer to inspect the installer first?\n\n```bash\ncurl -fsSL https://bivy.sh/install.sh -o install.sh\nless install.sh\nbash install.sh\n```\n\n**When the installer uses sudo:**\n\n- Debian/Ubuntu without a suitable Node.js: `sudo apt-get install curl\n  ca-certificates`, then NodeSource's Node 22 setup script via `sudo`.\n- Other Linux, or macOS, without a suitable Node.js: downloads the official\n  Node 22 tarball from nodejs.org (sha256-checked) and installs it under\n  `/usr/local` with `sudo`.\n- If npm's global prefix isn't writable it falls back to `~/.local` — it never\n  runs `npm install` under `sudo`.\n- It appends a marked PATH block to `~/.bashrc` or `~/.zshrc`\n  (`BIVY_NO_RC_UPDATE=1` to opt out).\n\nWant no sudo at all? Bring your own Node.js 20+ and skip the script:\n\n```bash\nnpm install -g @bivy/bivy && bivy setup     # install globally\nnpx @bivy/bivy setup                         # or try it once, no install\n```\n\nReleases are published from CI with provenance attestations; verify a build's\norigin with `npm audit signatures`. See [`docs/releasing.md`](docs/releasing.md).\n\n### Your first session\n\nAfter setup, start Bivy inside an existing repo:\n\n```bash\ncd your-repo\nbivy run claude    # start an agent as a durable session in the current repo\n# Try: \"Explain this repo and suggest one small, safe improvement.\"\nbivy open          # open that same session in the web app (needs relay setup)\nbivy resume        # or pick it back up here in the terminal\n```\n\nFrom here the [quickstart](docs/quickstart.md) walks through Runs, multiple\nMachines, and automations.\n\n### Install options\n\nEnvironment variables passed to the one-line installer change what it does:\n\n| Goal | Variable |\n|---|---|\n| Track the dev channel (new build on every merge to `main`) | `BIVY_CHANNEL=staging` |\n| Pin an exact version | `BIVY_VERSION=0.1.0` |\n| Install the npm package into a user-owned prefix | `BIVY_NPM_PREFIX=~/.local` |\n| Preinstall every known upstream agent | `BIVY_INSTALL_ALL_AGENTS=1` |\n| Install optional Bivy bridges/native terminal dependency up front | `BIVY_INSTALL_OPTIONAL_DEPS=1` |\n| Don't touch `~/.bashrc` / `~/.zshrc`; print the PATH line instead | `BIVY_NO_RC_UPDATE=1` |\n\nFor example: `BIVY_CHANNEL=staging curl -fsSL https://bivy.sh/install.sh | bash`.\n\nWorking from a checkout of this repository instead:\n\n```bash\npnpm install\npnpm run setup\n```\n\nSee [`docs/install.md`](docs/install.md) for where data lives, service\nmanagement, and uninstall.\n\n## Updating\n\n```bash\nbivy update\n```\n\n`bivy update` uses the same install method you used originally. It waits for an\nactive turn to finish, updates Bivy, and restarts the background service:\n\n| Install kind | What `bivy update` does |\n|---|---|\n| npm global (`npm i -g`) | `npm install -g @bivy/bivy@<channel>`, then restart the service |\n| installer / packaged | re-runs `install.sh` (migrating to npm if needed), then restart |\n| git checkout | `git pull --ff-only` + `pnpm install --frozen-lockfile`, then restart |\n| `npx` run | nothing to update — each run already fetches the latest |\n\nUpdates follow the release **channel** recorded at install time — `latest`\n(production) by default, or `staging` if you installed with\n`BIVY_CHANNEL=staging`. Switch channels (the choice is remembered for next\ntime), or skip the wait for a busy session:\n\n```bash\nbivy update --staging   # move to the dev channel\nbivy update --stable    # move back to production (latest)\nbivy update --force     # don't wait for an in-flight turn to finish\n```\n\nThe daemon checks for new releases and posts an update notice in the Session.\n\n## Architecture\n\nBivy has three parts. For normal interactive Sessions, code, credentials, and\ntranscripts stay on the node.\n\n```text\n  your machine                     hosted or self-hosted\n\n  ┌──────────────┐               ┌─────────┐        ┌───────────────┐\n  │ node daemon  │  ──dials──▶   │  relay  │ ◀────▶ │ control plane │\n  │ agents, keys │    outbound   │ opaque  │        │ accounts, web │\n  │ repo, tools  │               │ frames  │        │ app, metadata │\n  └──────────────┘               └─────────┘        └───────────────┘\n         ▲                                                  ▲\n         └────────── end-to-end encrypted session ───────────┘\n                     phone · browser · another terminal\n```\n\n- **Node** — a daemon on your machine. Owns the workspace, credentials, and agent\n  processes. Serves an API and WebSocket on `http://localhost:4317` plus a\n  `/healthz` probe. **It hosts no web UI.**\n- **Relay** — forwards encrypted frames between your node and your devices. Your\n  node dials out, so no inbound port is opened. The relay cannot read the frames.\n- **Control plane** — holds your account, node registry, and session index, and\n  serves the web/PWA client. Use the hosted one or run your own.\n\nThe node has no web UI. The browser and phone apps come from `app.bivy.sh` or\nyour own control plane; the terminal CLI needs neither. Session traffic is\nend-to-end encrypted between the node and paired devices, so the relay cannot\nread it.\n\nQR pairing with `bivy link` lets the node authorize the device directly. Hosted\naccount pairing trusts the control plane to authorize devices and serve the web\napp that holds the keys. Read the\n[known limitations](docs/security-model.md#known-limitations-for-0x) before using\nBivy with sensitive work.\n\nSee [`docs/remote-access.md`](docs/remote-access.md) and\n[`docs/security-model.md`](docs/security-model.md).\n\n## Supported agents\n\n**Claude Code, Codex, Pi, and OpenCode are the release-tested paths.** The other\nadapters are maintained, but their features vary. Check the\n[runtime support matrix](docs/runtime-support-matrix.md) for resume, models,\napprovals, sandboxing, and test status.\n\n| Agent | Command | Notes |\n|---|---|---|\n| Claude Code | `bivy run claude` | Uses the operator-installed `claude` command through an SDK bridge |\n| Codex | `bivy run codex` | Installs `@openai/codex` |\n| Pi | `bivy run pi` | Uses the operator-installed `pi` command and Pi auth/config |\n| OpenCode | `bivy run opencode` | Installs `opencode-ai` |\n| Gemini CLI | `bivy run gemini` | Installs `@google/gemini-cli` |\n| Qwen Code | `bivy run qwen` | Installs `@qwen-code/qwen-code` |\n| Goose | `bivy run goose` | Requires `goose` on PATH |\n| Aider | `bivy run aider` | No session resume (upstream gap) |\n| Cline | `bivy run cline` | Installs `cline` |\n| Crush | `bivy run crush` | No session resume (upstream gap) |\n| Cursor | `bivy run cursor` | ACP-capable |\n| GitHub Copilot | `bivy run copilot` | ACP-capable |\n| Grok | `bivy run grok` | Model selection |\n| Amp | `bivy run amp` | Native thread resume |\n| Auggie | `bivy run auggie` | Headless CLI |\n| Droid | `bivy run droid` | Model selection |\n| Continue | `bivy run continue` | Headless CLI |\n| Kilo Code | `bivy run kilocode` | ACP-capable |\n| Rovo Dev | `bivy run rovodev` | Installed out of band |\n\nCodebuff, Hermes, and OpenClaw are experimental and hidden from the picker.\nRun them with `BIVY_RUNTIME=<id>`.\n\nRun any command with `bivy run -- ./your-agent --flags`. For a reusable entry in\nthe CLI and web picker, use `bivy agent add`. You can also create an experimental\n`v1alpha1` [plugin manifest](docs/plugins.md) with `bivy plugin init`.\n\nSee the [runtime support matrix](docs/runtime-support-matrix.md) for details.\n\n## Common commands\n\n```bash\nbivy                  # show the command overview\nbivy run claude       # launch Claude Code as a durable session\nbivy run codex        # run a different agent\nbivy sessions         # list live and saved sessions\nbivy resume           # resume the most recent session\nbivy open             # open the web app (requires relay setup)\nbivy automation init  # create .bivy/automations.yaml\nbivy agent add        # connect an existing ACP or process agent\nbivy plugin list      # installed declarative integration packages\nbivy status           # config summary and node reachability\nbivy doctor           # health check\nbivy logs -f          # tail node logs\nbivy update           # update Bivy and restart the service\n```\n\nFull command list, flags, and examples: [`docs/cli-reference.md`](docs/cli-reference.md).\n\n## Configuration\n\nThe common knobs:\n\n```bash\nBIVY_WORKSPACE=/path/to/repo    # default workspace\nBIVY_SANDBOX=read-only          # read-only | workspace-write (default) | danger-full-access\nBIVY_APPROVAL_MODE=risky        # never | risky | always | autonomous (default)\n```\n\nManage node settings or add repo-specific checks and safety rules:\n\n```bash\nbivy config init\nbivy config set defaults.agent codex\nbivy config explain defaults.sandbox\nbivy config init --project       # .bivy/policy.yaml\n```\n\nSee [`docs/config-as-code.md`](docs/config-as-code.md). Every environment\nvariable and precedence rule lives in\n[`docs/configuration.md`](docs/configuration.md).\n\n## Approvals and sandboxing\n\nThe default approval mode is **`autonomous`**, so most actions do not prompt.\nProtection depends on the agent. Some agents enforce Bivy's sandbox setting;\nothers expose tool calls that Bivy can approve or deny. A process agent that\nBivy cannot intercept runs with your user permissions. The picker shows which\ncase applies and asks for confirmation on unprotected paths.\n\nFor tool calls it can see, Bivy blocks destructive system commands and writes\noutside the workspace. It asks before force pushes, publishing, deployments,\nand `sudo`. These checks help prevent accidents. **They are not a security\nsandbox.**\n\nTo see more prompts, change the approval mode:\n\n```bash\nBIVY_APPROVAL_MODE=risky    # prompt on risky shell commands and file edits\nBIVY_APPROVAL_MODE=always   # prompt on all shell commands and file edits\nBIVY_APPROVAL_MODE=never    # no prompts; structured-tool heuristic blocks still apply where available\n```\n\nApprove from the terminal, browser, or phone.\n\nCodex, Claude Code, Gemini CLI, and Qwen Code enforce the `read-only`,\n`workspace-write`, and `danger-full-access` tiers themselves. Other agents may\nrun with your full user permissions even when Bivy can inspect some tool calls.\nCheck the Protection label in the picker. **Bivy does not provide an OS-level\nsandbox.**\n\n## Credentials\n\nInteractive prompts, transcripts, and workspace files stay encrypted across the\nrelay. Credentials can remain on a Machine or in a vault you control:\n\n```bash\nbivy secrets list\nbivy secrets set github.repo-token\nbivy secrets ref github.repo-token op://Bivy/GitHub/repo-token\nbivy secrets doctor\n```\n\n`secret://`, `env://`, and `op://` (1Password) references are resolved only when\nan agent needs them, so the raw values do not appear in config files.\n\nHosted unattended provisioning is different from normal interactive Sessions.\nIf you enable it, Bivy Cloud may hold encrypted cloud, repository, model, or\nkey-escrow data that the service can access. See the\n[security model](docs/security-model.md#what-the-control-plane-sees) and\n[key-management guide](docs/key-management.md).\n\n## Automations as code\n\nDefine jobs in `.bivy/automations.yaml`, validate them, and test trigger events\nlocally:\n\n```bash\nbivy automation init\nbivy automation validate\nbivy automation test --event .bivy/events/failed-ci.yaml\nbivy automation apply\n```\n\nBivy encrypts instructions on the node before upload. Each job records its\nsandbox, approval mode, and maximum number of attempts. See\n[`docs/automations-as-code.md`](docs/automations-as-code.md).\n\n## GitHub Runs\n\nLabel an issue `bivy` (or `bivy/<machine>` to target a Machine), or mention the\nBivy GitHub App in a comment. Bivy creates a Run on the selected Machine, uses an\nisolated worktree, runs the configured checks, and posts the result.\n\nCore has no usage limits. Hosted pricing is managed in the separate Cloud\nrepository.\n\nA private GitHub App only installs on the account that owns it, so connect one\napp per GitHub account — one for your personal repos, one per organization\n(`bivy github:app-create --org <org>`). A node can serve several at once, each\nwith its own key and `@`-mention handle.\n\nSee [`docs/github-work-queue.md`](docs/github-work-queue.md).\n\n## Linear Runs\n\nApply `bivy` or `bivy/<machine>` to a Linear issue to create a Run on the selected\nMachine. The Machine fetches issue content directly from Linear, works in an\nisolated GitHub worktree, and asks the agent to open a pull request. See\n[`docs/linear-work-queue.md`](docs/linear-work-queue.md).\n\n## Development\n\n```bash\npnpm install\npnpm run dev          # node daemon on http://localhost:4317\npnpm run dev:web      # web client dev server (proxies /api and /ws to the node)\n```\n\nChecks — all of these run in CI:\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\nRepository layout:\n\n- `src/` — node daemon, runtime adapters, approvals, secrets, sessions\n- `bin/` — the `bivy` CLI\n- `packages/core` — shared protocol, pairing, wire format\n- `packages/web` — the React/Vite PWA client (`@bivy/web`)\n- `services/relay` — self-hostable relay\n- `services/control-plane` — self-hostable control plane\n- `deploy/` — self-host deployment examples\n\nSee [`CONTRIBUTING.md`](CONTRIBUTING.md).\n\n## Self-hosting\n\nNode, relay, and control plane are all in this repository. Point a node at your\nown deployment by passing URLs to `bivy relay:setup` — re-running it switches an\nexisting node over to the new endpoints:\n\n```bash\nbivy relay:setup \\\n  --control-plane https://bivy.example.com \\\n  --relay wss://relay.example.com\n```\n\nEach URL has a flag and an environment-variable equivalent (the flag wins):\n\n| Flag | Environment variable | Points at | Default |\n|---|---|---|---|\n| `--control-plane <url>` | `BIVY_CONTROL_PLANE_URL` | accounts, node registry, and the web-app API | hosted (`app.bivy.sh`) |\n| `--relay <wss-url>` | `BIVY_RELAY_URL` | the encrypted-frame relay your node dials out to | hosted |\n| `--client <url>` | `BIVY_CLIENT_BASE_URL` | base URL used when building app/PWA links | the `--control-plane` URL |\n\nSign-in defaults to GitHub device login (`--github`); pass\n`--email you@example.com` for an email magic-link, or `--session-token <token>`\nto skip interactive sign-in. `relay:setup` checks the control plane is reachable,\nenrolls this node, and writes the endpoints to `.bivy/relay.json`, so `bivy open`,\n`bivy link`, and `bivy update` all keep using your deployment afterwards.\n\n**Self-hosting is community-supported** — no SLA, best-effort help via GitHub\nissues. You own TLS, backups, upgrades, and hardening. Start with the\none-command VPS path in\n[`docs/self-host-quickstart.md`](docs/self-host-quickstart.md); the ops\nreference (backups, rotation, security boundary) is\n[`docs/self-host.md`](docs/self-host.md).\n\n## Security\n\nReport vulnerabilities through [GitHub private vulnerability reporting](https://github.com/bivysh/bivy/security/advisories/new).\nPlease don't open a public issue. See [`SECURITY.md`](SECURITY.md) for scope,\nresponse times, and safe harbour, and [`docs/security-model.md`](docs/security-model.md)\nfor the trust model and known limitations.\n\n## License\n\nBivy Core is free and open-source software under the GNU Affero General Public\nLicense, version 3.0 only (AGPL-3.0-only). You may use, study, modify, and\nself-host it under that license. If you modify Bivy and let users interact with\nit over a network, section 13 requires you to offer them the corresponding\nsource code. See [`LICENSE`](LICENSE).\n\n**Where the open-core line is.** Everything in this repository — node, CLI,\nrelay, control plane, and the web/PWA client — is AGPL Core, with no usage\nlimits. **Bivy Cloud** is the hosted operation of that stack plus billing and\nplans, and lives in a separate private repository. Contributions are accepted\nunder the [DCO](CONTRIBUTING.md#certificate-of-origin); there is no CLA.\n",
+  "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**Run coding agents on your machines and use them from anywhere — from a phone,\nbrowser, terminal, GitHub issue, Slack message, schedule, or webhook.**\n\nStart Claude Code on your workstation, next to the repo, dev server, and\ndatabase you already use. Walk away. From your phone, you can see what it did,\nanswer a question, or approve a migration. CI or a webhook can start the next\njob on the right Machine without waiting for you to return.\n\n```bash\ncurl -fsSL https://bivy.sh/install.sh | bash  # install + guided setup\ncd your-repo\nbivy run claude                                # start an agent in this repo\nbivy open                                      # open it in a browser or on your phone\n```\n\nBivy does not replace Claude Code, Codex, or the other agents you use. It keeps\ntheir Sessions running, routes work to the right Machine, and gives you one place\nto start, join, approve, and review work.\n\nFirst thing to try: ask the agent to explain the repository, make one small safe\nchange, then open the same Session in the web app or on your phone while it runs.\n\n**[Quickstart](docs/quickstart.md)** ·\n**[Docs](docs/README.md)** ·\n**[Why Bivy](docs/why-bivy.md)** ·\n**[Security model](docs/security-model.md)** ·\n**[bivy.sh](https://bivy.sh)**\n\n> **Bivy is 0.x software.** Claude Code, Codex, Pi, and OpenCode are the\n> release-tested paths. Support for other agents varies; check the\n> [runtime support matrix](docs/runtime-support-matrix.md) before relying on a\n> specific feature.\n\n## Why not just a cloud sandbox?\n\nA hosted sandbox clones your repo into a clean environment. Bivy runs in the\nenvironment you already use: the current working tree, running services, and\nwarm caches.\n\n|  | Cloud sandbox | Bivy Machine |\n|---|---|---|\n| Your repository | a cloned copy | the real working tree, uncommitted changes and all |\n| Dev server & database | mocked, or absent | already running, right beside the agent |\n| Private networks & internal APIs | out of reach | reachable |\n| Toolchains, package caches | cold, reinstalled each time | warm, already installed |\n| GPUs / local inference | rented separately | the ones on your box |\n| Where your code sits | someone else's infrastructure | the machine you already trust |\n\nBivy lets you leave that environment running and reach it from anywhere.\n\n## What you can do\n\nEvery task in Bivy becomes a Session on a Machine you choose. Start it from the\nterminal, browser, phone, or an external trigger. Join it while it runs, or let\nit finish in the background.\n\n### Sessions\n\nStart an agent, watch it work, steer it, stop it, or approve a tool call. You can\nleave your desk and keep the Session open:\n\n```bash\nbivy run claude              # or codex, pi, gemini, and a dozen more\nbivy open                    # continue the same session in the browser or PWA\nbivy resume                  # pick it back up in the terminal\nbivy run claude --no-follow  # start it in the background instead of attaching\nbivy run claude --chat       # start a chat session and open it in the browser\n```\n\n- Reconnect to the same Session from a phone, browser, or terminal.\n- Upload files and images from your phone, or download files the agent creates.\n- Import existing Claude Code and Codex Sessions.\n- Fork or move a Session to another agent, model, or Machine.\n- Connect several Machines, such as a workstation, server, or GPU box.\n\n### Runs\n\nA Run is a Session started as a background job. Start one yourself or trigger it\nfrom another service; Bivy queues it and returns immediately:\n\n```bash\nbivy runs start \"...\"    # queue a one-off unattended Run, then `bivy runs wait <id>`\nbivy automation init     # define jobs in .bivy/automations.yaml\n```\n\n- Trigger Runs from GitHub, Linear, Slack, a schedule, CI, or a signed webhook.\n- Choose the Machine, agent, model, sandbox, approval mode, and retry limit.\n- Review the changed files, checks, and final result in a Receipt.\n\nSee the [capability recipes](docs/capability-recipes.md) for examples and the\n[runtime support matrix](docs/runtime-support-matrix.md) for per-agent support.\n\n## Bring your own agents and models\n\nUse your existing agent login, an API key in Bivy's vault, or a local\nOpenAI-compatible server. Claude Code, Codex, Pi, and OpenCode have release-tested\nintegrations. Other agents run through ACP or a headless process adapter. Add\nyour own with:\n\n```bash\nbivy agent add       # register an existing ACP or process agent\n```\n\n## Install\n\n```bash\ncurl -fsSL https://bivy.sh/install.sh | bash\n```\n\nBivy supports macOS and Linux and requires Node.js 20 or newer. The installer\nadds the [`@bivy/bivy`](https://www.npmjs.com/package/@bivy/bivy) package and\n`bivy` command, then runs `bivy setup`. Setup asks which agent to use, installs\nit if needed, configures remote access, and starts a launchd or systemd service.\n\nIf an agent is already installed, Bivy uses its existing command, login, and\nconfiguration. Re-running the installer updates Bivy and restarts the service.\n\n**Local and remote use.** `bivy run`, `bivy resume`, and `bivy sessions` work\nwithout an account or server. During setup, choose **local only for now** to skip\nremote access. The browser and phone apps need a control plane: use\n[app.bivy.sh](https://app.bivy.sh) or\n[self-host one](docs/self-host-quickstart.md). You can sign in later with\n`bivy login` (or use `bivy relay:setup` for self-hosted endpoint options).\n\nSelf-hosted Bivy Core is open source and has no usage limits. Bivy Cloud offers\na managed app, relay, and hosted Machines; see\n[bivy.sh#pricing](https://bivy.sh#pricing) for details.\n\nPrefer to inspect the installer first?\n\n```bash\ncurl -fsSL https://bivy.sh/install.sh -o install.sh\nless install.sh\nbash install.sh\n```\n\n**When the installer uses sudo:**\n\n- Debian/Ubuntu without a suitable Node.js: `sudo apt-get install curl\n  ca-certificates`, then NodeSource's Node 22 setup script via `sudo`.\n- Other Linux, or macOS, without a suitable Node.js: downloads the official\n  Node 22 tarball from nodejs.org (sha256-checked) and installs it under\n  `/usr/local` with `sudo`.\n- If npm's global prefix isn't writable it falls back to `~/.local` — it never\n  runs `npm install` under `sudo`.\n- It appends a marked PATH block to `~/.bashrc` or `~/.zshrc`\n  (`BIVY_NO_RC_UPDATE=1` to opt out).\n\nWant no sudo at all? Bring your own Node.js 20+ and skip the script:\n\n```bash\nnpm install -g @bivy/bivy && bivy setup     # install globally\nnpx @bivy/bivy setup                         # or try it once, no install\n```\n\nReleases are published from CI with provenance attestations; verify a build's\norigin with `npm audit signatures`. See [`docs/releasing.md`](docs/releasing.md).\n\n### Your first session\n\nAfter setup, start Bivy inside an existing repo:\n\n```bash\ncd your-repo\nbivy run claude    # start an agent as a durable session in the current repo\n# Try: \"Explain this repo and suggest one small, safe improvement.\"\nbivy open          # open that same session in the web app (needs relay setup)\nbivy resume        # or pick it back up here in the terminal\n```\n\nFrom here the [quickstart](docs/quickstart.md) walks through Runs, multiple\nMachines, and automations.\n\n### Install options\n\nEnvironment variables passed to the one-line installer change what it does:\n\n| Goal | Variable |\n|---|---|\n| Track the dev channel (new build on every merge to `main`) | `BIVY_CHANNEL=staging` |\n| Pin an exact version | `BIVY_VERSION=0.1.0` |\n| Install the npm package into a user-owned prefix | `BIVY_NPM_PREFIX=~/.local` |\n| Preinstall every known upstream agent | `BIVY_INSTALL_ALL_AGENTS=1` |\n| Install optional Bivy bridges/native terminal dependency up front | `BIVY_INSTALL_OPTIONAL_DEPS=1` |\n| Don't touch `~/.bashrc` / `~/.zshrc`; print the PATH line instead | `BIVY_NO_RC_UPDATE=1` |\n\nFor example: `BIVY_CHANNEL=staging curl -fsSL https://bivy.sh/install.sh | bash`.\n\nWorking from a checkout of this repository instead:\n\n```bash\npnpm install\npnpm run setup\n```\n\nSee [`docs/install.md`](docs/install.md) for where data lives, service\nmanagement, and uninstall.\n\n## Updating\n\n```bash\nbivy update\n```\n\n`bivy update` uses the same install method you used originally. It waits for an\nactive turn to finish, updates Bivy, and restarts the background service:\n\n| Install kind | What `bivy update` does |\n|---|---|\n| npm global (`npm i -g`) | `npm install -g @bivy/bivy@<channel>`, then restart the service |\n| installer / packaged | re-runs `install.sh` (migrating to npm if needed), then restart |\n| git checkout | `git pull --ff-only` + `pnpm install --frozen-lockfile`, then restart |\n| `npx` run | nothing to update — each run already fetches the latest |\n\nUpdates follow the release **channel** recorded at install time — `latest`\n(production) by default, or `staging` if you installed with\n`BIVY_CHANNEL=staging`. Switch channels (the choice is remembered for next\ntime), or skip the wait for a busy session:\n\n```bash\nbivy update --staging   # move to the dev channel\nbivy update --stable    # move back to production (latest)\nbivy update --force     # don't wait for an in-flight turn to finish\n```\n\nThe daemon checks for new releases and posts an update notice in the Session.\n\n## Architecture\n\nBivy has three parts. For normal interactive Sessions, code, credentials, and\ntranscripts stay on the node.\n\n```text\n  your machine                     hosted or self-hosted\n\n  ┌──────────────┐               ┌─────────┐        ┌───────────────┐\n  │ node daemon  │  ──dials──▶   │  relay  │ ◀────▶ │ control plane │\n  │ agents, keys │    outbound   │ opaque  │        │ accounts, web │\n  │ repo, tools  │               │ frames  │        │ app, metadata │\n  └──────────────┘               └─────────┘        └───────────────┘\n         ▲                                                  ▲\n         └────────── end-to-end encrypted session ───────────┘\n                     phone · browser · another terminal\n```\n\n- **Node** — a daemon on your machine. Owns the workspace, credentials, and agent\n  processes. Serves an API and WebSocket on `http://localhost:4317` plus a\n  `/healthz` probe. **It hosts no web UI.**\n- **Relay** — forwards encrypted frames between your node and your devices. Your\n  node dials out, so no inbound port is opened. The relay cannot read the frames.\n- **Control plane** — holds your account, node registry, and session index, and\n  serves the web/PWA client. Use the hosted one or run your own.\n\nThe node has no web UI. The browser and phone apps come from `app.bivy.sh` or\nyour own control plane; the terminal CLI needs neither. Session traffic is\nend-to-end encrypted between the node and paired devices, so the relay cannot\nread it.\n\nQR pairing with `bivy link` lets the node authorize the device directly. Hosted\naccount pairing trusts the control plane to authorize devices and serve the web\napp that holds the keys. Read the\n[known limitations](docs/security-model.md#known-limitations-for-0x) before using\nBivy with sensitive work.\n\nSee [`docs/remote-access.md`](docs/remote-access.md) and\n[`docs/security-model.md`](docs/security-model.md).\n\n## Supported agents\n\n**Claude Code, Codex, Pi, and OpenCode are the release-tested paths.** The other\nadapters are maintained, but their features vary. Check the\n[runtime support matrix](docs/runtime-support-matrix.md) for resume, models,\napprovals, sandboxing, and test status.\n\n| Agent | Command | Notes |\n|---|---|---|\n| Claude Code | `bivy run claude` | Uses the operator-installed `claude` command through an SDK bridge |\n| Codex | `bivy run codex` | Installs `@openai/codex` |\n| Pi | `bivy run pi` | Uses the operator-installed `pi` command and Pi auth/config |\n| OpenCode | `bivy run opencode` | Installs `opencode-ai` |\n| Gemini CLI | `bivy run gemini` | Installs `@google/gemini-cli` |\n| Qwen Code | `bivy run qwen` | Installs `@qwen-code/qwen-code` |\n| Goose | `bivy run goose` | Requires `goose` on PATH |\n| Aider | `bivy run aider` | No session resume (upstream gap) |\n| Cline | `bivy run cline` | Installs `cline` |\n| Crush | `bivy run crush` | No session resume (upstream gap) |\n| Cursor | `bivy run cursor` | ACP-capable |\n| GitHub Copilot | `bivy run copilot` | ACP-capable |\n| Grok | `bivy run grok` | Model selection |\n| Amp | `bivy run amp` | Native thread resume |\n| Auggie | `bivy run auggie` | Headless CLI |\n| Droid | `bivy run droid` | Model selection |\n| Continue | `bivy run continue` | Headless CLI |\n| Kilo Code | `bivy run kilocode` | ACP-capable |\n| Rovo Dev | `bivy run rovodev` | Installed out of band |\n\nCodebuff, Hermes, and OpenClaw are experimental and hidden from the picker.\nRun them with `BIVY_RUNTIME=<id>`.\n\nRun any command with `bivy run -- ./your-agent --flags`. For a reusable entry in\nthe CLI and web picker, use `bivy agent add`. You can also create an experimental\n`v1alpha1` [plugin manifest](docs/plugins.md) with `bivy plugin init`.\n\nSee the [runtime support matrix](docs/runtime-support-matrix.md) for details.\n\n## Common commands\n\n```bash\nbivy                  # show the command overview\nbivy run claude       # launch Claude Code as a durable session\nbivy run codex        # run a different agent\nbivy sessions         # list live and saved sessions\nbivy resume           # resume the most recent session\nbivy open             # open the web app (requires relay setup)\nbivy automation init  # create .bivy/automations.yaml\nbivy agent add        # connect an existing ACP or process agent\nbivy plugin list      # installed declarative integration packages\nbivy status           # config summary and node reachability\nbivy doctor           # health check\nbivy logs -f          # tail node logs\nbivy update           # update Bivy and restart the service\n```\n\nFull command list, flags, and examples: [`docs/cli-reference.md`](docs/cli-reference.md).\n\n## Configuration\n\nThe common knobs:\n\n```bash\nBIVY_WORKSPACE=/path/to/repo    # default workspace\nBIVY_SANDBOX=read-only          # read-only | workspace-write (default) | danger-full-access\nBIVY_APPROVAL_MODE=risky        # never | risky | always | autonomous (default)\n```\n\nManage node settings or add repo-specific checks and safety rules:\n\n```bash\nbivy config init\nbivy config set defaults.agent codex\nbivy config explain defaults.sandbox\nbivy config init --project       # .bivy/policy.yaml\n```\n\nSee [`docs/config-as-code.md`](docs/config-as-code.md). Every environment\nvariable and precedence rule lives in\n[`docs/configuration.md`](docs/configuration.md).\n\n## Approvals and sandboxing\n\nThe default approval mode is **`autonomous`**, so most actions do not prompt.\nProtection depends on the agent. Some agents enforce Bivy's sandbox setting;\nothers expose tool calls that Bivy can approve or deny. A process agent that\nBivy cannot intercept runs with your user permissions. The picker shows which\ncase applies and asks for confirmation on unprotected paths.\n\nFor tool calls it can see, Bivy blocks destructive system commands and writes\noutside the workspace. It asks before force pushes, publishing, deployments,\nand `sudo`. These checks help prevent accidents. **They are not a security\nsandbox.**\n\nTo see more prompts, change the approval mode:\n\n```bash\nBIVY_APPROVAL_MODE=risky    # prompt on risky shell commands and file edits\nBIVY_APPROVAL_MODE=always   # prompt on all shell commands and file edits\nBIVY_APPROVAL_MODE=never    # no prompts; structured-tool heuristic blocks still apply where available\n```\n\nApprove from the terminal, browser, or phone.\n\nCodex, Claude Code, Gemini CLI, and Qwen Code enforce the `read-only`,\n`workspace-write`, and `danger-full-access` tiers themselves. Other agents may\nrun with your full user permissions even when Bivy can inspect some tool calls.\nCheck the Protection label in the picker. **Bivy does not provide an OS-level\nsandbox.**\n\n## Credentials\n\nInteractive prompts, transcripts, and workspace files stay encrypted across the\nrelay. Credentials can remain on a Machine or in a vault you control:\n\n```bash\nbivy secrets list\nbivy secrets set github.repo-token\nbivy secrets ref github.repo-token op://Bivy/GitHub/repo-token\nbivy secrets doctor\n```\n\n`secret://`, `env://`, and `op://` (1Password) references are resolved only when\nan agent needs them, so the raw values do not appear in config files.\n\nHosted unattended provisioning is different from normal interactive Sessions.\nIf you enable it, Bivy Cloud may hold encrypted cloud, repository, model, or\nkey-escrow data that the service can access. See the\n[security model](docs/security-model.md#what-the-control-plane-sees) and\n[key-management guide](docs/key-management.md).\n\n## Automations as code\n\nDefine jobs in `.bivy/automations.yaml`, validate them, and test trigger events\nlocally:\n\n```bash\nbivy automation init\nbivy automation validate\nbivy automation test --event .bivy/events/failed-ci.yaml\nbivy automation apply\n```\n\nBivy encrypts instructions on the node before upload. Each job records its\nsandbox, approval mode, and maximum number of attempts. See\n[`docs/automations-as-code.md`](docs/automations-as-code.md).\n\n## GitHub Runs\n\nLabel an issue `bivy` (or `bivy/<machine>` to target a Machine), or mention the\nBivy GitHub App in a comment. Bivy creates a Run on the selected Machine, uses an\nisolated worktree, runs the configured checks, and posts the result.\n\nCore has no usage limits. Hosted pricing is managed in the separate Cloud\nrepository.\n\nA private GitHub App only installs on the account that owns it, so connect one\napp per GitHub account — one for your personal repos, one per organization\n(`bivy github:app-create --org <org>`). A node can serve several at once, each\nwith its own key and `@`-mention handle.\n\nSee [`docs/github-work-queue.md`](docs/github-work-queue.md).\n\n## Linear Runs\n\nApply `bivy` or `bivy/<machine>` to a Linear issue to create a Run on the selected\nMachine. The Machine fetches issue content directly from Linear, works in an\nisolated GitHub worktree, and asks the agent to open a pull request. See\n[`docs/linear-work-queue.md`](docs/linear-work-queue.md).\n\n## Development\n\n```bash\npnpm install\npnpm run dev          # node daemon on http://localhost:4317\npnpm run dev:web      # web client dev server (proxies /api and /ws to the node)\n```\n\nChecks — all of these run in CI:\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\nRepository layout:\n\n- `src/` — node daemon, runtime adapters, approvals, secrets, sessions\n- `bin/` — the `bivy` CLI\n- `packages/core` — shared protocol, pairing, wire format\n- `packages/web` — the React/Vite PWA client (`@bivy/web`)\n- `services/relay` — self-hostable relay\n- `services/control-plane` — self-hostable control plane\n- `deploy/` — self-host deployment examples\n\nSee [`CONTRIBUTING.md`](CONTRIBUTING.md).\n\n## Self-hosting\n\nNode, relay, and control plane are all in this repository. Point a node at your\nown deployment by passing URLs to `bivy relay:setup` — re-running it switches an\nexisting node over to the new endpoints:\n\n```bash\nbivy relay:setup \\\n  --control-plane https://bivy.example.com \\\n  --relay wss://relay.example.com\n```\n\nEach URL has a flag and an environment-variable equivalent (the flag wins):\n\n| Flag | Environment variable | Points at | Default |\n|---|---|---|---|\n| `--control-plane <url>` | `BIVY_CONTROL_PLANE_URL` | accounts, node registry, and the web-app API | hosted (`app.bivy.sh`) |\n| `--relay <wss-url>` | `BIVY_RELAY_URL` | the encrypted-frame relay your node dials out to | hosted |\n| `--client <url>` | `BIVY_CLIENT_BASE_URL` | base URL used when building app/PWA links | the `--control-plane` URL |\n\nSign-in defaults to GitHub device login (`--github`); pass\n`--email you@example.com` for an email magic-link, or `--session-token <token>`\nto skip interactive sign-in. `relay:setup` checks the control plane is reachable,\nenrolls this node, and writes the endpoints to `.bivy/relay.json`, so `bivy open`,\n`bivy link`, and `bivy update` all keep using your deployment afterwards.\n\n**Self-hosting is community-supported** — no SLA, best-effort help via GitHub\nissues. You own TLS, backups, upgrades, and hardening. Start with the\none-command VPS path in\n[`docs/self-host-quickstart.md`](docs/self-host-quickstart.md); the ops\nreference (backups, rotation, security boundary) is\n[`docs/self-host.md`](docs/self-host.md).\n\n## Security\n\nReport vulnerabilities through [GitHub private vulnerability reporting](https://github.com/bivysh/bivy/security/advisories/new).\nPlease don't open a public issue. See [`SECURITY.md`](SECURITY.md) for scope,\nresponse times, and safe harbour, and [`docs/security-model.md`](docs/security-model.md)\nfor the trust model and known limitations.\n\n## License\n\nBivy Core is free and open-source software under the GNU Affero General Public\nLicense, version 3.0 only (AGPL-3.0-only). You may use, study, modify, and\nself-host it under that license. If you modify Bivy and let users interact with\nit over a network, section 13 requires you to offer them the corresponding\nsource code. See [`LICENSE`](LICENSE).\n\n**Where the open-core line is.** Everything in this repository — node, CLI,\nrelay, control plane, and the web/PWA client — is AGPL Core, with no usage\nlimits. **Bivy Cloud** is the hosted operation of that stack plus billing and\nplans, and lives in a separate private repository. Contributions are accepted\nunder the [DCO](CONTRIBUTING.md#certificate-of-origin); there is no CLA.\n",
   "readmeFilename": "README.md"
 }