@bivy/bivy 0.10.1-staging.364 → 0.10.1-staging.366

package/README.md

@@ -328,12 +328,8 @@ Label an issue `bivy` (or `bivy/<machine>` to target a Machine), or mention the
 Bivy GitHub App in a comment. Bivy creates a Run on the selected Machine, uses an
 isolated worktree, executes configured checks, and reports an explicit outcome.
 
-Available on every plan. On Bivy Cloud, the free trial shows the first 25
-distinct sessions in the hosted app and includes 10 unattended automations per
-rolling 7-day window across GitHub, Slack, webhooks, and schedules. Sessions keep
-running on your machines after the hosted trial is exhausted, but new ones are
-hidden from the hosted app until you subscribe. Pro removes both limits.
-Self-hosted stacks are unlimited.
+Core applies no commercial usage limits. Bivy Cloud billing and commercial
+policy live in the separate Cloud repository.
 
 A private GitHub App only installs on the account that owns it, so connect one
 app per GitHub account — one for your personal repos, one per organization

package/bin/bivy.mjs

@@ -3897,13 +3897,9 @@ async function cmdStatus(args = []) {
   if (relay?.controlPlaneUrl && relay?.enrollmentToken) {
     try {
       const acct = await controlPlaneNodeApi(relay, "/node/account");
-      const planName = { free: "Free", pro: "Pro", individual: "Pro", team: "Team" }[acct?.plan] || acct?.plan || "Free";
-      const cap = acct?.entitlements?.maxNodes ?? "∞";
-      const nodeLine = `${acct?.counts?.nodes ?? "?"} / ${cap} nodes`;
-      const extras = acct?.entitlements?.workQueueEnabled ? "" : c.dim("  (Pro: unlimited nodes, push, GitHub queue)");
-      console.log(`  plan:      ${planName}  ·  ${nodeLine}${extras}`);
+      console.log(`  account:   ${acct?.counts?.nodes ?? "?"} node(s)`);
     } catch {
-      // Offline or unenrolled — plan line is best-effort, never blocks status.
+      // Offline or unenrolled — account usage is best-effort, never blocks status.
     }
   }
   if (status) {

package/dist/automation/preflight.js

@@ -70,17 +70,6 @@ export function runPreflightChecks(signals) {
     }
     else
         results.push(check("sandbox_policy", "ok", "Sandbox & policy", sandbox.detail ?? "Requested sandbox and approval are within policy."));
-    const quota = signals.quota;
-    if (!quota)
-        results.push(skipped("quota", "Automation quota"));
-    else if (typeof quota.limit !== "number")
-        results.push(check("quota", "ok", "Automation quota", quota.detail ?? "No quota limit applies to this plan."));
-    else if (quota.exhausted)
-        results.push(check("quota", "block", "Automation quota", quota.detail ?? `The account is over its automation quota (${quota.used}/${quota.limit} this window).`));
-    else if (quota.warn)
-        results.push(check("quota", "warn", "Automation quota", quota.detail ?? `The account is at its automation quota (${quota.used}/${quota.limit} this window); this run is in the grace band.`));
-    else
-        results.push(check("quota", "ok", "Automation quota", quota.detail ?? `${quota.used ?? 0}/${quota.limit} used this window.`));
     return results;
 }
 /** Reduce a checklist to a save decision: hard failures block, everything

package/dist/automation/types.js

@@ -16,5 +16,4 @@ export const PREFLIGHT_CHECK_IDS = [
     "assigned_machine",
     "agent_model_credentials",
     "sandbox_policy",
-    "quota",
 ];

package/dist/remote/relay-client.js

@@ -59,7 +59,7 @@ export class RelayConnector {
     heartbeatTimer;
     stableTimer;
     lastPongAt = 0;
-    // True only between the relay's `ready` message (auth + entitlement passed)
+    // True only between the relay's `ready` message (admission passed)
     // and the socket closing. This — not "a connector object exists" — is what
     // "connected" means to the control plane, so it's what `bivy status` reports.
     ready = false;
@@ -89,7 +89,7 @@ export class RelayConnector {
     }
     /**
      * True only while the relay link is live AND the relay has sent `ready`
-     * (auth/entitlement checks passed) — i.e. the node is actually reachable from
+     * (admission checks passed) — i.e. the node is actually reachable from
      * the control plane. A socket that opened but was rejected, or one still
      * reconnecting, reads false.
      */
@@ -300,7 +300,7 @@ export class RelayConnector {
         const ws = new WebSocket(target);
         this.ws = ws;
         ws.on("open", () => {
-            // The TCP/WebSocket handshake succeeded, but relay auth/entitlement
+            // The TCP/WebSocket handshake succeeded, but relay admission
             // checks happen after upgrade. Wait for the relay's `ready` message
             // before declaring the connector usable or resetting reconnect backoff.
         });

package/dist/server.js

@@ -8797,7 +8797,7 @@ app.get("/api/status", (_req, res) => {
         updatedAt: new Date().toISOString(),
     });
 });
-app.get("/api/billing/config", (_req, res) => {
+app.get("/api/account/config", (_req, res) => {
     const config = loadRelayConfig(appDir);
     const base = config?.clientBaseUrl ?? config?.controlPlaneUrl;
     res.json({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bivy/bivy",
-  "version": "0.10.1-staging.364",
+  "version": "0.10.1-staging.366",
   "type": "module",
   "license": "AGPL-3.0-only",
   "description": "Run coding agents on machines you own. Open-source, self-hostable agent workspace.",
@@ -63,6 +63,6 @@
     "brace-expansion": "5.0.9",
     "undici": "8.10.0"
   },
-  "readme": "# Bivy\n\n**Give coding agents your real environment, then reach them from anywhere.**\n\nA provider sandbox starts from an approximation. A Bivy Machine can use the\nrepository, local services and databases, private networks, existing tools and\ncaches, and GPUs or local inference already available on your workstation or\nserver. Bivy turns that local capability into Sessions you can continue remotely\nand Runs you can leave working unattended.\n\n## What Bivy lets you do\n\n- **Work where the full environment lives.** Run Claude Code, Codex, Pi, or\n  another agent beside real repos, dev servers, databases, internal APIs,\n  toolchains, package caches, and specialized compute.\n- **Continue from a phone, browser, or terminal.** Reconnect to the same Session,\n  steer or stop it, answer questions, and approve supported tool calls. The PWA\n  supports voice input and read-aloud, phone-to-agent file/image uploads, and\n  agent-to-phone attachments. Native terminal Sessions can stay remote-visible;\n  supported runtimes can hand work between terminal and structured chat.\n- **Move work without starting over.** Import existing Claude Code and Codex\n  Sessions, or fork/copy/move a Bivy Session to another agent, model, or Machine.\n  Fidelity is runtime-dependent: a fork may use a native transcript, replayed\n  history, or a bounded seeded continuation, and cross-Machine moves require the\n  destination's repo access, agent, and credentials.\n- **Operate more than one Machine.** Keep a workstation, private-network server,\n  and GPU box on one account; select the environment a Session or Run needs.\n  Optional warm Session replication is Beta, off by default, and manually\n  promoted rather than automatic failover.\n- **Let events start checked work.** Create Runs manually or from failed CI,\n  GitHub/Linear issues, Slack, schedules, and signed webhooks. Automations can\n  pin a Machine, agent, model, sandbox, approval mode, and attempt ceiling, then\n  report bounded check and outcome evidence in a Receipt.\n- **Bring your own stack.** Use provider subscriptions through supported native\n  agent logins, API keys in Bivy's vault, or local/OpenAI-compatible inference.\n  Add an existing ACP or headless process agent with `bivy agent add`; declarative\n  agent plugins are Experimental (`v1alpha1`) and run out of process.\n\nStart with the [five-minute quickstart](docs/quickstart.md), then try the\n[capability recipes](docs/capability-recipes.md) or check the exact\n[runtime support matrix](docs/runtime-support-matrix.md).\n\nInteractive Session traffic is end-to-end encrypted between a Machine and its\npaired devices, so the relay cannot decrypt it. The seatbelt has a precise edge:\nexplicitly enabled hosted provisioning may give the control plane technical\naccess to encrypted cloud, repository, or key-escrow material, while Slack and\ngeneric webhook instructions reach it in plaintext. See [Why Bivy](docs/why-bivy.md)\nand the [security model](docs/security-model.md) for the complete trust model.\n\n- **Website:** [bivy.sh](https://bivy.sh)\n- **Documentation:** [`docs/`](docs/README.md)\n- **License:** [AGPL-3.0-only](LICENSE)\n\n> Bivy is 0.x software. The core loop is solid and used daily, but interfaces,\n> cross-runtime fidelity, and behaviour can change between releases. Check the\n> support matrix before depending on a particular agent capability.\n\n## Install\n\n```bash\ncurl -fsSL https://bivy.sh/install.sh | bash\n```\n\nmacOS and Linux. Requires Node.js 22.19 or newer; the installer installs it for\nyou on Debian/Ubuntu and otherwise points you at nodejs.org. It installs the\n[`@bivy/bivy`](https://www.npmjs.com/package/@bivy/bivy) package from npm, puts\nthe `bivy` command on your `PATH`, then runs the guided `bivy setup` wizard —\nagent choice, relay/control-plane sign-in, and an auto-start background service\n(launchd on macOS, systemd on Linux). Re-running it on a machine that already\nhas Bivy just applies the latest build and restarts the service.\n\nAlready have Node.js 22.19+? The installer is optional:\n\n```bash\nnpm install -g @bivy/bivy\nbivy setup\n```\n\nOr try it once without installing anything (`npx` always fetches the latest):\n\n```bash\nnpx @bivy/bivy setup\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### 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 without sudo, into a user-owned prefix | `BIVY_NPM_PREFIX=~/.local` |\n| Preinstall every known upstream agent | `BIVY_INSTALL_ALL_AGENTS=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` detects how Bivy was installed and does the right thing, then\nwaits for any active session to finish its current turn and restarts the\nbackground service so the node reconnects on the new build:\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 also checks the registry periodically and posts an in-session notice\nwhen a newer build is available.\n\n## Architecture\n\nBivy has three parts. Only the first one holds your data.\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\nBecause the node serves no UI, a browser or phone needs a control plane — hosted\nat `app.bivy.sh`, or one you deploy yourself. The terminal CLI needs neither.\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 and Codex are the recommended, release-certified paths.** The\nbroader catalog remains available under **More agents** for users who need it;\ncapabilities and fidelity vary by runtime:\n\n| Agent | Command | Notes |\n|---|---|---|\n| Pi | `bivy run pi` | Uses the operator-installed `pi` command and Pi auth/config |\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| 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\nAny other command works via `bivy run -- ./your-agent --flags`. ACP-capable\nagents can be promoted to Bivy's governed protocol path for per-tool approvals\nand native resume. To add a reusable process or ACP agent to both the CLI and web\npicker without changing Bivy, run `bivy agent add`, or scaffold and install a\ndeclarative [plugin manifest](docs/plugins.md) with `bivy plugin init`. Both use\nthe same schema/store; the plugin SDK, diagnostics, and ACP conformance fixtures\nsupport distributable or custom protocol bridges.\n\n[`docs/runtime-support-matrix.md`](docs/runtime-support-matrix.md) lists exactly\nwhat each agent supports — resume, model selection, approvals, sandboxing.\n\n## Common commands\n\n```bash\nbivy                  # show the command overview\nbivy run pi           # launch Pi as a durable session\nbivy run claude       # 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\nCreate and inspect the typed node configuration, or add repository-owned\nsafety/check/retry policy:\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 remains in\n[`docs/configuration.md`](docs/configuration.md).\n\n## Approvals and sandboxing\n\nThe default approval mode is **`autonomous`**: agents act without per-action\nprompts. The actual protection depends on the selected runtime. Native-sandbox\nagents enforce the chosen access tier; structured runtimes also pass tool calls\nthrough Bivy's policy and approval layer. Process agents that Bivy cannot\nintercept run with your OS user permissions. The picker shows this distinction\nand requires confirmation before selecting that limited path.\n\nWhere Bivy receives structured shell/file calls, a heuristic floor blocks known\ncatastrophic commands and structured writes outside the workspace, and a\nbackstop set (force-push, publish, deploy, sudo) pauses for a human. This catches\naccidents; it is not an adversarial isolation boundary.\n\nIf you want to be asked about more, set the mode explicitly:\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\nSandbox tiers (`read-only`, `workspace-write`, `danger-full-access`) are enforced\nnatively by agents that support them — Codex, Claude Code, Gemini CLI, Qwen Code.\nAgents without a native sandbox may expose structured tool or MCP controls, but\nthose controls do not cover activity the agent performs outside those channels;\nsome process adapters run entirely with your user permissions. Check the\npicker's Protection label. **Bivy does not currently ship its own OS-level jail.**\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. If you\nexplicitly enable hosted unattended provisioning, Bivy Cloud may instead store\nencrypted cloud, repository, model, or key-escrow material that the service can\ntechnically access. Treat this as an explicit hosted-custody mode, not as relay\nblindness. See the\n[security model](docs/security-model.md#what-the-control-plane-sees).\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 on demand\nwhen the daemon provisions an agent run, so the raw values never sit in your\nconfig. See [`docs/key-management.md`](docs/key-management.md).\n\n## Automations as code\n\nDefine governed jobs in `.bivy/automations.yaml`, validate them, and simulate\ntrigger events locally before applying anything:\n\n```bash\nbivy automation init\nbivy automation validate\nbivy automation test --event .bivy/events/failed-ci.yaml\nbivy automation apply\n```\n\nInstructions are encrypted on the applying node before upload. Safety policy\nlives beside the job—sandbox, approval mode, and a hard attempt ceiling that\nretry/fallback rules cannot exceed. 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, executes configured checks, and reports an explicit outcome.\n\nAvailable on every plan. On Bivy Cloud, the free trial shows the first 25\ndistinct sessions in the hosted app and includes 10 unattended automations per\nrolling 7-day window across GitHub, Slack, webhooks, and schedules. Sessions keep\nrunning on your machines after the hosted trial is exhausted, but new ones are\nhidden from the hosted app until you subscribe. Pro removes both limits.\nSelf-hosted stacks are unlimited.\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, enrolls\nthis 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 unsupported** — no SLA, community best-effort via GitHub\nissues. You own TLS, backups, upgrades, and hardening. See\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 do not 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 licensed under the GNU Affero General\nPublic License, 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 those users the corresponding\nsource code.\n\nSee [`LICENSE`](LICENSE), [`CORE.md`](CORE.md), and [`CLOUD.md`](CLOUD.md).\n",
+  "readme": "# Bivy\n\n**Give coding agents your real environment, then reach them from anywhere.**\n\nA provider sandbox starts from an approximation. A Bivy Machine can use the\nrepository, local services and databases, private networks, existing tools and\ncaches, and GPUs or local inference already available on your workstation or\nserver. Bivy turns that local capability into Sessions you can continue remotely\nand Runs you can leave working unattended.\n\n## What Bivy lets you do\n\n- **Work where the full environment lives.** Run Claude Code, Codex, Pi, or\n  another agent beside real repos, dev servers, databases, internal APIs,\n  toolchains, package caches, and specialized compute.\n- **Continue from a phone, browser, or terminal.** Reconnect to the same Session,\n  steer or stop it, answer questions, and approve supported tool calls. The PWA\n  supports voice input and read-aloud, phone-to-agent file/image uploads, and\n  agent-to-phone attachments. Native terminal Sessions can stay remote-visible;\n  supported runtimes can hand work between terminal and structured chat.\n- **Move work without starting over.** Import existing Claude Code and Codex\n  Sessions, or fork/copy/move a Bivy Session to another agent, model, or Machine.\n  Fidelity is runtime-dependent: a fork may use a native transcript, replayed\n  history, or a bounded seeded continuation, and cross-Machine moves require the\n  destination's repo access, agent, and credentials.\n- **Operate more than one Machine.** Keep a workstation, private-network server,\n  and GPU box on one account; select the environment a Session or Run needs.\n  Optional warm Session replication is Beta, off by default, and manually\n  promoted rather than automatic failover.\n- **Let events start checked work.** Create Runs manually or from failed CI,\n  GitHub/Linear issues, Slack, schedules, and signed webhooks. Automations can\n  pin a Machine, agent, model, sandbox, approval mode, and attempt ceiling, then\n  report bounded check and outcome evidence in a Receipt.\n- **Bring your own stack.** Use provider subscriptions through supported native\n  agent logins, API keys in Bivy's vault, or local/OpenAI-compatible inference.\n  Add an existing ACP or headless process agent with `bivy agent add`; declarative\n  agent plugins are Experimental (`v1alpha1`) and run out of process.\n\nStart with the [five-minute quickstart](docs/quickstart.md), then try the\n[capability recipes](docs/capability-recipes.md) or check the exact\n[runtime support matrix](docs/runtime-support-matrix.md).\n\nInteractive Session traffic is end-to-end encrypted between a Machine and its\npaired devices, so the relay cannot decrypt it. The seatbelt has a precise edge:\nexplicitly enabled hosted provisioning may give the control plane technical\naccess to encrypted cloud, repository, or key-escrow material, while Slack and\ngeneric webhook instructions reach it in plaintext. See [Why Bivy](docs/why-bivy.md)\nand the [security model](docs/security-model.md) for the complete trust model.\n\n- **Website:** [bivy.sh](https://bivy.sh)\n- **Documentation:** [`docs/`](docs/README.md)\n- **License:** [AGPL-3.0-only](LICENSE)\n\n> Bivy is 0.x software. The core loop is solid and used daily, but interfaces,\n> cross-runtime fidelity, and behaviour can change between releases. Check the\n> support matrix before depending on a particular agent capability.\n\n## Install\n\n```bash\ncurl -fsSL https://bivy.sh/install.sh | bash\n```\n\nmacOS and Linux. Requires Node.js 22.19 or newer; the installer installs it for\nyou on Debian/Ubuntu and otherwise points you at nodejs.org. It installs the\n[`@bivy/bivy`](https://www.npmjs.com/package/@bivy/bivy) package from npm, puts\nthe `bivy` command on your `PATH`, then runs the guided `bivy setup` wizard —\nagent choice, relay/control-plane sign-in, and an auto-start background service\n(launchd on macOS, systemd on Linux). Re-running it on a machine that already\nhas Bivy just applies the latest build and restarts the service.\n\nAlready have Node.js 22.19+? The installer is optional:\n\n```bash\nnpm install -g @bivy/bivy\nbivy setup\n```\n\nOr try it once without installing anything (`npx` always fetches the latest):\n\n```bash\nnpx @bivy/bivy setup\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### 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 without sudo, into a user-owned prefix | `BIVY_NPM_PREFIX=~/.local` |\n| Preinstall every known upstream agent | `BIVY_INSTALL_ALL_AGENTS=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` detects how Bivy was installed and does the right thing, then\nwaits for any active session to finish its current turn and restarts the\nbackground service so the node reconnects on the new build:\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 also checks the registry periodically and posts an in-session notice\nwhen a newer build is available.\n\n## Architecture\n\nBivy has three parts. Only the first one holds your data.\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\nBecause the node serves no UI, a browser or phone needs a control plane — hosted\nat `app.bivy.sh`, or one you deploy yourself. The terminal CLI needs neither.\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 and Codex are the recommended, release-certified paths.** The\nbroader catalog remains available under **More agents** for users who need it;\ncapabilities and fidelity vary by runtime:\n\n| Agent | Command | Notes |\n|---|---|---|\n| Pi | `bivy run pi` | Uses the operator-installed `pi` command and Pi auth/config |\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| 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\nAny other command works via `bivy run -- ./your-agent --flags`. ACP-capable\nagents can be promoted to Bivy's governed protocol path for per-tool approvals\nand native resume. To add a reusable process or ACP agent to both the CLI and web\npicker without changing Bivy, run `bivy agent add`, or scaffold and install a\ndeclarative [plugin manifest](docs/plugins.md) with `bivy plugin init`. Both use\nthe same schema/store; the plugin SDK, diagnostics, and ACP conformance fixtures\nsupport distributable or custom protocol bridges.\n\n[`docs/runtime-support-matrix.md`](docs/runtime-support-matrix.md) lists exactly\nwhat each agent supports — resume, model selection, approvals, sandboxing.\n\n## Common commands\n\n```bash\nbivy                  # show the command overview\nbivy run pi           # launch Pi as a durable session\nbivy run claude       # 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\nCreate and inspect the typed node configuration, or add repository-owned\nsafety/check/retry policy:\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 remains in\n[`docs/configuration.md`](docs/configuration.md).\n\n## Approvals and sandboxing\n\nThe default approval mode is **`autonomous`**: agents act without per-action\nprompts. The actual protection depends on the selected runtime. Native-sandbox\nagents enforce the chosen access tier; structured runtimes also pass tool calls\nthrough Bivy's policy and approval layer. Process agents that Bivy cannot\nintercept run with your OS user permissions. The picker shows this distinction\nand requires confirmation before selecting that limited path.\n\nWhere Bivy receives structured shell/file calls, a heuristic floor blocks known\ncatastrophic commands and structured writes outside the workspace, and a\nbackstop set (force-push, publish, deploy, sudo) pauses for a human. This catches\naccidents; it is not an adversarial isolation boundary.\n\nIf you want to be asked about more, set the mode explicitly:\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\nSandbox tiers (`read-only`, `workspace-write`, `danger-full-access`) are enforced\nnatively by agents that support them — Codex, Claude Code, Gemini CLI, Qwen Code.\nAgents without a native sandbox may expose structured tool or MCP controls, but\nthose controls do not cover activity the agent performs outside those channels;\nsome process adapters run entirely with your user permissions. Check the\npicker's Protection label. **Bivy does not currently ship its own OS-level jail.**\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. If you\nexplicitly enable hosted unattended provisioning, Bivy Cloud may instead store\nencrypted cloud, repository, model, or key-escrow material that the service can\ntechnically access. Treat this as an explicit hosted-custody mode, not as relay\nblindness. See the\n[security model](docs/security-model.md#what-the-control-plane-sees).\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 on demand\nwhen the daemon provisions an agent run, so the raw values never sit in your\nconfig. See [`docs/key-management.md`](docs/key-management.md).\n\n## Automations as code\n\nDefine governed jobs in `.bivy/automations.yaml`, validate them, and simulate\ntrigger events locally before applying anything:\n\n```bash\nbivy automation init\nbivy automation validate\nbivy automation test --event .bivy/events/failed-ci.yaml\nbivy automation apply\n```\n\nInstructions are encrypted on the applying node before upload. Safety policy\nlives beside the job—sandbox, approval mode, and a hard attempt ceiling that\nretry/fallback rules cannot exceed. 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, executes configured checks, and reports an explicit outcome.\n\nCore applies no commercial usage limits. Bivy Cloud billing and commercial\npolicy live in the separate Cloud repository.\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, enrolls\nthis 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 unsupported** — no SLA, community best-effort via GitHub\nissues. You own TLS, backups, upgrades, and hardening. See\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 do not 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 licensed under the GNU Affero General\nPublic License, 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 those users the corresponding\nsource code.\n\nSee [`LICENSE`](LICENSE), [`CORE.md`](CORE.md), and [`CLOUD.md`](CLOUD.md).\n",
   "readmeFilename": "README.md"
 }