@bivy/bivy 0.16.11 → 0.16.12-staging.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +297 -443
  2. package/package.json +2 -2
package/README.md CHANGED
@@ -7,460 +7,380 @@
7
7
  **Run coding agents on your machines and use them from anywhere — from a phone,
8
8
  browser, terminal, GitHub issue, Slack message, schedule, or webhook.**
9
9
 
10
- Start Claude Code or Codex in the development environment you already use —
11
- with your repo, running services, tools, and credentials. Leave your desk,
12
- open the session on your phone, and answer a question, approve an action, or
13
- review the diff. GitHub issues, CI, schedules, and webhooks can start work on
14
- those same machines.
10
+ Bivy is an open-source workspace for coding-agent work. Turn prompts, GitHub
11
+ issues, CI failures, Slack messages, and schedules into live sessions on your
12
+ machines. Choose the agent and model, sync supported API keys and OAuth logins,
13
+ and steer and review the work from your browser, phone, or terminal.
14
+
15
+ Keep Claude Code, Codex, Pi, OpenCode, or another supported agent. Keep your
16
+ repos, tools, and development environment. Bivy connects them into a workflow
17
+ that doesn't end when you leave your desk.
18
+
19
+ **[Start free on Bivy Cloud](https://app.bivy.sh)** ·
20
+ **[Quickstart](docs/quickstart.md)** ·
21
+ **[Documentation](docs/README.md)** ·
22
+ **[Self-host](docs/self-host-quickstart.md)** ·
23
+ **[Website](https://bivy.sh)**
15
24
 
16
25
  ```bash
17
26
  curl -fsSL https://bivy.sh/install.sh | bash # install + guided setup
18
27
  cd your-repo
19
- bivy run claude # start an agent in this repo
20
- bivy open # open the web app (requires remote setup)
28
+ bivy run claude # or codex, pi, opencode
29
+ bivy open # continue in the web app (needs remote setup)
21
30
  ```
22
31
 
23
- Bivy does not replace your coding agent or provide model inference. It keeps
24
- Sessions running, routes work to connected Machines, and gives you one place to
25
- start, join, approve, and review work. A **Machine** is a Mac, Linux computer,
26
- or existing server you operate; a **Session** is the agent work running there.
27
- Your machine must stay awake and online for remote access.
28
-
29
- First thing to try: ask the agent to explain the repository, make one small safe
30
- change, then open the same Session in the web app or on your phone while it runs.
31
-
32
- **[Quickstart](docs/quickstart.md)** ·
33
- **[Docs](docs/README.md)** ·
34
- **[Why Bivy](docs/why-bivy.md)** ·
35
- **[Security model](docs/security-model.md)** ·
36
- **[bivy.sh](https://bivy.sh)**
32
+ Bivy Cloud hosts the app, control plane, and relay—not the machines running your
33
+ agents. Connect a Mac, Linux computer, or existing server and bring your own
34
+ agent subscription, model API key, or local model. You can also self-host the
35
+ entire remote-access stack.
37
36
 
38
37
  > **Bivy is 0.x software.** Claude Code, Codex, Pi, and OpenCode are the
39
- > release-tested paths. Support for other agents varies; check the
40
- > [runtime support matrix](docs/runtime-support-matrix.md) before relying on a
41
- > specific feature.
42
-
43
- ## Why run on your own machines?
38
+ > release-tested paths. Credential sync, resume, handoffs, approvals, and
39
+ > sandboxing depend on the runtime. See the
40
+ > [runtime support matrix](docs/runtime-support-matrix.md).
44
41
 
45
- A fresh cloud sandbox can be useful, but it is not always the environment your
46
- work needs. Bivy connects to the machines you already operate, so your agent can
47
- use:
42
+ ## More than remote access
48
43
 
49
- - Your existing working tree, including uncommitted changes.
50
- - Running dev servers, databases, installed toolchains, and warm caches.
51
- - Private networks and internal APIs that machine can reach.
52
- - Your GPUs and local model servers.
44
+ Remote access lets you reach an agent. Bivy also connects **what starts the
45
+ work, where it runs, which agent and credentials it uses, and how you review
46
+ what happened**.
53
47
 
54
- You bring the environment; Bivy makes the work accessible from anywhere.
55
- Background Runs can use isolated worktrees without rebuilding the whole machine.
56
-
57
- ## What you can do
58
-
59
- Every task in Bivy becomes a Session on a Machine you choose. Start it from the
60
- terminal, browser, phone, or an external trigger. Join it while it runs, or let
61
- it finish in the background.
62
-
63
- ### Sessions
64
-
65
- Start an agent, watch it work, steer it, stop it, or approve a tool call. You can
66
- leave your desk and keep the Session open:
67
-
68
- ```bash
69
- bivy run claude # or codex, pi, opencode
70
- bivy open # continue the same session in the browser or PWA
71
- bivy resume # pick it back up in the terminal
72
- bivy run claude --no-follow # start it in the background instead of attaching
73
- bivy run claude --chat # start a chat session and open it in the browser
74
- ```
75
-
76
- - Reconnect to the same Session from a phone, browser, or terminal.
77
- - Upload files and images from your phone, or download files the agent creates.
78
- - Import existing Claude Code and Codex Sessions.
79
- - Fork or move a Session to another agent, model, or Machine.
80
- - Connect several Machines, such as a workstation, server, or GPU box.
81
-
82
- ### Runs
48
+ | Capability | What it means for you |
49
+ |---|---|
50
+ | **One workspace, multiple agents** | Use different agents and models for different tasks without maintaining a separate workflow for each. |
51
+ | **Your machines and environment** | Work beside your existing repos, dev servers, databases, private networks, toolchains, and GPUs. |
52
+ | **Automations and triggers** | Let issues, failed CI, messages, schedules, and webhooks start work instead of copying requests into a chat. |
53
+ | **Encrypted key and OAuth sync** | Reuse Bivy-managed provider credentials across enrolled machines and compatible runtimes, with less repeated setup. |
54
+ | **Live sessions from anywhere** | Start at your desk, answer a question or approve an action from your phone, then return to the terminal. |
55
+ | **Reviewable results** | See changes, declared checks, artifacts, and pull requests—not just an agent's claim that it finished. |
56
+ | **Hosted convenience or self-hosting** | Use Bivy Cloud for managed remote access, or run the same open-source core yourself. |
83
57
 
84
- A Run is a Session started as a background job. Start one yourself or trigger it
85
- from another service; Bivy queues it and returns immediately:
58
+ ## One workflow, from trigger to review
86
59
 
87
- ```bash
88
- bivy runs start "..." # queue a one-off unattended Run, then `bivy runs wait <id>`
89
- bivy automation init # define jobs in .bivy/automations.yaml
60
+ ```text
61
+ Prompt · GitHub issue · CI failure · Linear · Slack · Schedule · Webhook
62
+ │
63
+ ▼
64
+ Choose machine + agent + model
65
+ + supported credentials
66
+ │
67
+ ▼
68
+ Live agent session
69
+ Join · steer · approve · stop
70
+ │
71
+ ▼
72
+ Changes · checks · artifacts · PR
90
73
  ```
91
74
 
92
- - Trigger Runs from GitHub, Linear, Slack, a schedule, CI, or a signed webhook.
93
- - Choose the Machine, agent, model, sandbox, approval mode, and retry limit.
94
- - Review the changed files, checks, and final result in a Receipt.
75
+ A **Machine** is a computer or server you connect. A **Session** is live agent
76
+ work on that machine. A **Run** is delegated background work that creates a
77
+ session and tracks its outcome. An **Automation** is a reusable definition that
78
+ creates runs when an event matches.
95
79
 
96
- See the [capability recipes](docs/capability-recipes.md) for examples and the
97
- [runtime support matrix](docs/runtime-support-matrix.md) for per-agent support.
80
+ Manual and automated work use the same kind of live session. You can join a run
81
+ when it needs help rather than wait for a black-box job to finish.
98
82
 
99
- ## Bring your own agents and models
83
+ ### Work in the environment you already have
100
84
 
101
- Use your existing agent login, an API key in Bivy's vault, or a local
102
- OpenAI-compatible server. Claude Code, Codex, Pi, and OpenCode have release-tested
103
- integrations. Other agents run through ACP or a headless process adapter. Add
104
- your own with:
105
-
106
- ```bash
107
- bivy agent add # register an existing ACP or process agent
108
- ```
109
-
110
- ## Install
111
-
112
- ```bash
113
- curl -fsSL https://bivy.sh/install.sh | bash
114
- ```
85
+ A clean cloud sandbox isn't always enough. Your agent may need the database
86
+ running on localhost, an uncommitted change, an internal API behind your VPN,
87
+ or a model running on your GPU. Bivy runs the agent where those things already
88
+ exist, subject to that machine's permissions and the runtime's protection.
115
89
 
116
- Bivy supports macOS and Linux and requires Node.js 20 or newer. The installer
117
- adds the [`@bivy/bivy`](https://www.npmjs.com/package/@bivy/bivy) package and
118
- `bivy` command, then runs `bivy setup`. Setup asks which agent to use, installs
119
- it if needed, configures remote access, and starts a launchd or systemd service.
90
+ Connect several machines to the same account: a laptop for interactive work,
91
+ a Linux server for background jobs, or a GPU box for local inference. Choose
92
+ the machine for each session or pin it in an automation. Repository runs can
93
+ use isolated Git worktrees without rebuilding the whole development environment.
120
94
 
121
- If an agent is already installed, Bivy uses its existing command, login, and
122
- configuration. Re-running the installer updates Bivy and restarts the service.
95
+ **The execution machine must stay awake and online.** To close your laptop and
96
+ leave work running, run the agent on a different, always-on machine.
123
97
 
124
- **Local and remote use.** `bivy run`, `bivy resume`, and `bivy sessions` work
125
- without an account or server. During setup, choose **local only for now** to skip
126
- remote access. The browser and phone apps need a control plane: use
127
- [app.bivy.sh](https://app.bivy.sh) or
128
- [self-host one](docs/self-host-quickstart.md). You can sign in later with
129
- `bivy login` (or use `bivy relay:setup` for self-hosted endpoint options).
98
+ [Environment and multi-machine recipes →](docs/capability-recipes.md)
130
99
 
131
- **What Cloud hosts.** Bivy Cloud runs the web app, control plane, and encrypted
132
- relay — not your agents or their machines. Connect a computer or server you
133
- already operate and bring your own agent subscription or model API key.
100
+ ### Use multiple agents, not multiple disconnected workflows
134
101
 
135
- - **Free Cloud:** every launch feature, including automations, with 10 new remote
136
- Sessions per rolling seven days. Manual and automated Sessions share this
137
- allowance; resuming existing Sessions and viewing history do not consume it.
138
- No credit card required.
139
- - **Cloud — $15/month:** unlimited remote Sessions, with the same features.
140
- - **Self-hosted Core:** run the app, control plane, and relay yourself, with no
141
- Bivy usage limits.
102
+ Run Claude Code for one task, Codex for another, and Pi or OpenCode where they
103
+ fit. Bivy supplies the shared session, remote-access, automation, and review
104
+ surfaces; your chosen agent still does the coding and uses your model provider.
142
105
 
143
- Agent subscriptions and model-provider charges are separate. See
144
- [bivy.sh#pricing](https://bivy.sh#pricing) for current hosted pricing.
106
+ - Choose an agent and, where supported, a model for each session or run.
107
+ - Import existing Claude Code and Codex sessions.
108
+ - Fork or move work to another agent or machine when a different setup fits
109
+ better. Continuation fidelity varies: some paths preserve native history,
110
+ while others replay portable turns or seed the destination with context.
111
+ - Use agent-native logins, Bivy-managed credentials, or local inference.
112
+ Bivy's custom OpenAI-compatible endpoint registry currently feeds Pi;
113
+ other agents may need their own provider configuration.
114
+ - Register your own ACP or headless process agent with `bivy agent add`.
145
115
 
146
- Prefer to inspect the installer first?
116
+ Bivy does not replace your agent, provide model inference, or make every agent's
117
+ features identical. Consult the [support matrix](docs/runtime-support-matrix.md)
118
+ and [handoff recipes](docs/capability-recipes.md#fork-or-move-a-session).
147
119
 
148
- ```bash
149
- curl -fsSL https://bivy.sh/install.sh -o install.sh
150
- less install.sh
151
- bash install.sh
152
- ```
120
+ ### Less signing in. Less copying secrets.
153
121
 
154
- **When the installer uses sudo:**
122
+ Bivy syncs **Bivy-managed API keys and supported OAuth credentials** across
123
+ enrolled machines for compatible runtimes. Connect supported credentials once
124
+ and reuse them where you run work, rather than manually distributing keys to
125
+ each machine.
155
126
 
156
- - Debian/Ubuntu without a suitable Node.js: `sudo apt-get install curl
157
- ca-certificates`, then NodeSource's Node 22 setup script via `sudo`.
158
- - Other Linux, or macOS, without a suitable Node.js: downloads the official
159
- Node 22 tarball from nodejs.org (sha256-checked) and installs it under
160
- `/usr/local` with `sudo`.
161
- - If npm's global prefix isn't writable it falls back to `~/.local` — it never
162
- runs `npm install` under `sudo`.
163
- - It appends a marked PATH block to `~/.bashrc` or `~/.zshrc`
164
- (`BIVY_NO_RC_UPDATE=1` to opt out).
127
+ For ordinary account sync, credentials are encrypted on the node before upload.
128
+ The control plane stores ciphertext and wrapped-key metadata; enrolled nodes
129
+ share access by wrapping the vault key to one another. Bivy Cloud does not
130
+ receive plaintext credentials through this sync path.
165
131
 
166
- Want no sudo at all? Bring your own Node.js 20+ and skip the script:
132
+ You can also keep credentials local, use labeled keys and project presets, or
133
+ reference environment variables and 1Password instead of embedding secrets in
134
+ configuration:
167
135
 
168
136
  ```bash
169
- npm install -g @bivy/bivy && bivy setup # install globally
170
- npx @bivy/bivy setup # or try it once, no install
137
+ bivy provider login
138
+ bivy credentials add anthropic work
139
+ bivy secrets ref github.repo-token op://Bivy/GitHub/repo-token
171
140
  ```
172
141
 
173
- Releases are published from CI with provenance attestations; verify a build's
174
- origin with `npm audit signatures`. See [`docs/releasing.md`](docs/releasing.md).
142
+ **Not every CLI login syncs.** Native agent logins may still be per-machine;
143
+ GitHub App private-key sync is separately opt-in. If you lose every node and
144
+ device able to unwrap a vault, you must sign in to providers again. Explicit
145
+ hosted-provisioning custody grants are separate from ordinary encrypted sync.
175
146
 
176
- ### Your first session
147
+ [Credential sync and runtime coverage →](docs/credential-sync.md) ·
148
+ [Credentials guide →](docs/credentials-guide.md) ·
149
+ [Key storage →](docs/key-management.md)
177
150
 
178
- After setup, start Bivy inside an existing repo:
151
+ ### Let events start the work
179
152
 
180
- ```bash
181
- cd your-repo
182
- bivy run claude # start an agent as a durable session in the current repo
183
- # Try: "Explain this repo and suggest one small, safe improvement."
184
- bivy open # open that same session in the web app (needs relay setup)
185
- bivy resume # or pick it back up here in the terminal
186
- ```
187
-
188
- From here the [quickstart](docs/quickstart.md) walks through Runs, multiple
189
- Machines, and automations.
190
-
191
- ### Install options
153
+ Automations turn recurring or incoming work into sessions you can join,
154
+ supervise, and review. Choose the repository, machine, agent, model, approval
155
+ mode, sandbox setting, and maximum attempts.
192
156
 
193
- Environment variables passed to the one-line installer change what it does:
194
-
195
- | Goal | Variable |
157
+ | Trigger | Example workflow |
196
158
  |---|---|
197
- | Pin an exact version | `BIVY_VERSION=0.1.0` |
198
- | Install the npm package into a user-owned prefix | `BIVY_NPM_PREFIX=~/.local` |
199
- | Preinstall every known upstream agent | `BIVY_INSTALL_ALL_AGENTS=1` |
200
- | Install optional Bivy bridges/native terminal dependency up front | `BIVY_INSTALL_OPTIONAL_DEPS=1` |
201
- | Don't touch `~/.bashrc` / `~/.zshrc`; print the PATH line instead | `BIVY_NO_RC_UPDATE=1` |
159
+ | **GitHub issues and mentions** | Label an issue `bivy` or `bivy/<machine>`, or mention your Bivy GitHub App, to work toward a pull request. |
160
+ | **Failed CI** | Match a failed workflow, ask the agent to reproduce it, make a fix, and run the affected checks. |
161
+ | **Linear** | Label an issue to start work without copying its description into an agent. |
162
+ | **Slack** | Send a request from the conversation where the work came up. |
163
+ | **Schedules** | Run a weekly dependency review, recurring maintenance, or a one-time task. |
164
+ | **Signed webhooks** | Connect alerts, internal tools, or your own event sources. |
202
165
 
203
- Working from a checkout of this repository instead:
166
+ Configure automations in the app or version them with your repository in
167
+ `.bivy/automations.yaml`:
204
168
 
205
169
  ```bash
206
- pnpm install
207
- pnpm run setup
170
+ bivy automation init
171
+ # Edit the generated definition for your repository and workflow.
172
+ bivy automation validate
173
+ bivy automation test --event .bivy/events/failed-ci.yaml # supply a local event fixture
174
+ bivy automation apply
208
175
  ```
209
176
 
210
- See [`docs/install.md`](docs/install.md) for where data lives, service
211
- management, and uninstall.
212
-
213
- ## Updating
177
+ Or delegate a one-off job without creating an automation:
214
178
 
215
179
  ```bash
216
- bivy update
180
+ bivy runs start "Review outdated dependencies and propose a small, tested update."
181
+ bivy runs wait <id>
217
182
  ```
218
183
 
219
- `bivy update` uses the same install method you used originally. It waits for an
220
- active turn to finish, updates Bivy, and restarts the background service:
184
+ Runs keep routing and lifecycle evidence, check results, and output references
185
+ in a reviewable Receipt. For unattended issue work, Bivy runs declared repository
186
+ checks after the agent's turn; failed required checks fail the run even if the
187
+ agent reports success. A completed process alone is not proof that the task
188
+ succeeded.
221
189
 
222
- | Install kind | What `bivy update` does |
223
- |---|---|
224
- | npm global (`npm i -g`) | updates the global npm package, then restarts the service |
225
- | installer / packaged | re-runs `install.sh` (migrating to npm if needed), then restart |
226
- | git checkout | `git pull --ff-only` + `pnpm install --frozen-lockfile`, then restart |
227
- | `npx` run | nothing to update — each run already fetches the latest |
190
+ [Automation recipes →](docs/capability-recipes.md#let-events-start-runs) ·
191
+ [Automations as code →](docs/automations-as-code.md) ·
192
+ [Run outcomes and reliability limits →](docs/automation-runs.md)
193
+
194
+ ### Start at your desk. Continue anywhere.
228
195
 
229
- The standard installer uses stable releases (`latest` on npm). Use
230
- `bivy update` to keep that installation current.
196
+ Open the same session in the browser, phone PWA, or terminal. Watch work live,
197
+ answer questions, approve supported tool calls, or stop the agent.
231
198
 
232
- To skip the wait for a busy session:
199
+ - Send screenshots, images, logs, and other files from your phone.
200
+ - Download reports and artifacts the agent creates.
201
+ - Use voice input and read-aloud where supported; provider-backed voice may
202
+ send audio or text to the selected provider.
203
+ - Keep a native terminal workflow or use structured chat, depending on the agent.
233
204
 
234
205
  ```bash
235
- bivy update --force # don't wait for an in-flight turn to finish
206
+ bivy run claude --no-follow # start without attaching
207
+ bivy open # open the web app
208
+ bivy resume # return to the session in your terminal
209
+ bivy link # pair a device directly via QR
236
210
  ```
237
211
 
238
- The daemon checks for new releases and posts an update notice in the Session.
212
+ No phone app installation is required. Open [app.bivy.sh](https://app.bivy.sh)
213
+ in your browser; adding it to your home screen is optional.
239
214
 
240
- ## Architecture
215
+ [Remote access →](docs/remote-access.md) ·
216
+ [Voice, files, and terminal recipes →](docs/capability-recipes.md)
241
217
 
242
- Bivy has three parts. For normal interactive Sessions, code, credentials, and
243
- transcripts stay on the node.
218
+ ## Get started
244
219
 
245
- ```text
246
- your machine hosted or self-hosted
247
-
248
- ┌──────────────┐ ┌─────────┐ ┌───────────────┐
249
- │ node daemon │ ──dials──▶ │ relay │ ◀────▶ │ control plane │
250
- │ agents, keys │ outbound │ opaque │ │ accounts, web │
251
- │ repo, tools │ │ frames │ │ app, metadata │
252
- └──────────────┘ └─────────┘ └───────────────┘
253
- ▲ ▲
254
- └────────── end-to-end encrypted session ───────────┘
255
- phone · browser · another terminal
256
- ```
220
+ ### Install
257
221
 
258
- - **Node** — a daemon on your machine. Owns the workspace, credentials, and agent
259
- processes. Serves an API and WebSocket on `http://localhost:4317` plus a
260
- `/healthz` probe. **It hosts no web UI.**
261
- - **Relay** — forwards encrypted frames between your node and your devices. Your
262
- node dials out, so no inbound port is opened. The relay cannot read the frames.
263
- - **Control plane** — holds your account, node registry, and session index, and
264
- serves the web/PWA client. Use the hosted one or run your own.
265
-
266
- The node has no web UI. The browser and phone apps come from `app.bivy.sh` or
267
- your own control plane; the terminal CLI needs neither. Session traffic is
268
- end-to-end encrypted between the node and paired devices, so the relay cannot
269
- read it.
270
-
271
- QR pairing with `bivy link` lets the node authorize the device directly. Hosted
272
- account pairing trusts the control plane to authorize devices and serve the web
273
- app that holds the keys. Read the
274
- [known limitations](docs/security-model.md#known-limitations-for-0x) before using
275
- Bivy with sensitive work.
276
-
277
- See [`docs/remote-access.md`](docs/remote-access.md) and
278
- [`docs/security-model.md`](docs/security-model.md).
279
-
280
- ## Supported agents
281
-
282
- **Claude Code, Codex, Pi, and OpenCode are the release-tested paths.** The other
283
- adapters are maintained, but their features vary. Check the
284
- [runtime support matrix](docs/runtime-support-matrix.md) for resume, models,
285
- approvals, sandboxing, and test status.
286
-
287
- | Agent | Command | Notes |
288
- |---|---|---|
289
- | Claude Code | `bivy run claude` | Uses the operator-installed `claude` command through an SDK bridge |
290
- | Codex | `bivy run codex` | Installs `@openai/codex` |
291
- | Pi | `bivy run pi` | Uses the operator-installed `pi` command and Pi auth/config |
292
- | OpenCode | `bivy run opencode` | Installs `opencode-ai` |
293
- | Gemini CLI | `bivy run gemini` | Installs `@google/gemini-cli` |
294
- | Qwen Code | `bivy run qwen` | Installs `@qwen-code/qwen-code` |
295
- | Goose | `bivy run goose` | Requires `goose` on PATH |
296
- | Aider | `bivy run aider` | No session resume (upstream gap) |
297
- | Cline | `bivy run cline` | Installs `cline` |
298
- | Crush | `bivy run crush` | No session resume (upstream gap) |
299
- | Cursor | `bivy run cursor` | ACP-capable |
300
- | GitHub Copilot | `bivy run copilot` | ACP-capable |
301
- | Grok | `bivy run grok` | Model selection |
302
- | Amp | `bivy run amp` | Native thread resume |
303
- | Auggie | `bivy run auggie` | Headless CLI |
304
- | Droid | `bivy run droid` | Model selection |
305
- | Continue | `bivy run continue` | Headless CLI |
306
- | Kilo Code | `bivy run kilocode` | ACP-capable |
307
- | Rovo Dev | `bivy run rovodev` | Installed out of band |
308
-
309
- Codebuff, Hermes, and OpenClaw are experimental and hidden from the picker.
310
- Run them with `BIVY_RUNTIME=<id>`.
311
-
312
- Run any command with `bivy run -- ./your-agent --flags`. For a reusable entry in
313
- the CLI and web picker, use `bivy agent add`. You can also create an experimental
314
- `v1alpha1` [plugin manifest](docs/plugins.md) with `bivy plugin init`.
315
-
316
- See the [runtime support matrix](docs/runtime-support-matrix.md) for details.
317
-
318
- ## Common commands
222
+ Bivy supports **macOS and Linux with Node.js 20+**. The installer installs the
223
+ `@bivy/bivy` package, runs guided setup, and starts a launchd or systemd service:
319
224
 
320
225
  ```bash
321
- bivy # show the command overview
322
- bivy run claude # launch Claude Code as a durable session
323
- bivy run codex # run a different agent
324
- bivy sessions # list live and saved sessions
325
- bivy resume # resume the most recent session
326
- bivy open # open the web app (requires relay setup)
327
- bivy automation init # create .bivy/automations.yaml
328
- bivy agent add # connect an existing ACP or process agent
329
- bivy plugin list # installed declarative integration packages
330
- bivy status # config summary and node reachability
331
- bivy doctor # health check
332
- bivy logs -f # tail node logs
333
- bivy update # update Bivy and restart the service
226
+ curl -fsSL https://bivy.sh/install.sh | bash
334
227
  ```
335
228
 
336
- Full command list, flags, and examples: [`docs/cli-reference.md`](docs/cli-reference.md).
337
-
338
- ## Configuration
229
+ Setup helps you choose an agent and configure remote access. Existing agents
230
+ keep their command, login, and configuration. The installer may use `sudo` to
231
+ install Node.js if needed, but never for `npm install`. To inspect it first,
232
+ download it with `curl -fsSL https://bivy.sh/install.sh -o install.sh`.
339
233
 
340
- The common knobs:
234
+ Already have Node.js and want to avoid sudo?
341
235
 
342
236
  ```bash
343
- BIVY_WORKSPACE=/path/to/repo # default workspace
344
- BIVY_SANDBOX=read-only # read-only | workspace-write (default) | danger-full-access
345
- BIVY_APPROVAL_MODE=risky # never | risky | always | autonomous (default)
237
+ npm install -g @bivy/bivy
238
+ bivy setup
346
239
  ```
347
240
 
348
- Manage node settings or add repo-specific checks and safety rules:
241
+ Then try one small task:
349
242
 
350
243
  ```bash
351
- bivy config init
352
- bivy config set defaults.agent codex
353
- bivy config explain defaults.sandbox
354
- bivy config init --project # .bivy/policy.yaml
244
+ cd your-repo
245
+ bivy run claude
246
+ # Ask: "Explain this repo and make one small, safe improvement. Run the relevant checks."
247
+ bivy open
355
248
  ```
356
249
 
357
- See [`docs/config-as-code.md`](docs/config-as-code.md). Every environment
358
- variable and precedence rule lives in
359
- [`docs/configuration.md`](docs/configuration.md).
360
-
361
- ## Approvals and sandboxing
250
+ Open that same session on your phone while it runs. Once that works, connect
251
+ another machine or add your first automation.
362
252
 
363
- The default approval mode is **`autonomous`**, so most actions do not prompt.
364
- Protection depends on the agent. Some agents enforce Bivy's sandbox setting;
365
- others expose tool calls that Bivy can approve or deny. A process agent that
366
- Bivy cannot intercept runs with your user permissions. The picker shows which
367
- case applies and asks for confirmation on unprotected paths.
253
+ **Local-only works too.** `bivy run`, `bivy resume`, and `bivy sessions` need no
254
+ account or server. Choose **local only for now** during setup; use `bivy login`
255
+ later. Browser and phone access need a hosted or self-hosted control plane;
256
+ the node itself does not serve a web UI.
368
257
 
369
- For tool calls it can see, Bivy blocks destructive system commands and writes
370
- outside the workspace. It asks before force pushes, publishing, deployments,
371
- and `sudo`. These checks help prevent accidents. **They are not a security
372
- sandbox.**
258
+ [Full quickstart →](docs/quickstart.md) ·
259
+ [Installer options, service management, and uninstall →](docs/install.md)
373
260
 
374
- To see more prompts, change the approval mode:
261
+ ### Choose hosted or self-hosted
375
262
 
376
- ```bash
377
- BIVY_APPROVAL_MODE=risky # prompt on risky shell commands and file edits
378
- BIVY_APPROVAL_MODE=always # prompt on all shell commands and file edits
379
- BIVY_APPROVAL_MODE=never # no prompts; structured-tool heuristic blocks still apply where available
380
- ```
381
-
382
- Approve from the terminal, browser, or phone.
383
-
384
- Codex, Claude Code, Gemini CLI, and Qwen Code enforce the `read-only`,
385
- `workspace-write`, and `danger-full-access` tiers themselves. Other agents may
386
- run with your full user permissions even when Bivy can inspect some tool calls.
387
- Check the Protection label in the picker. **Bivy does not provide an OS-level
388
- sandbox.**
263
+ | Option | What you get |
264
+ |---|---|
265
+ | **Free Cloud — $0** | Every launch feature, including automations; 10 new remote sessions per rolling seven days. No credit card required. |
266
+ | **Cloud — $15/month** | The same features with unlimited remote sessions. |
267
+ | **Self-hosted Core** | Operate the app, control plane, and relay yourself, with no Bivy usage limits. |
389
268
 
390
- ## Credentials
269
+ Manual and automated sessions share the Cloud allowance. Resuming existing
270
+ sessions and viewing history do not consume it. Agent subscriptions and model
271
+ provider charges are separate. See [current pricing](https://bivy.sh#pricing).
391
272
 
392
- Interactive prompts, transcripts, and workspace files stay encrypted across the
393
- relay. Credentials can remain on a Machine or in a vault you control:
273
+ Start on Cloud and self-host later if you prefer. Deploy the stack, reconnect
274
+ machines with `bivy relay:setup`, and pair devices to your server. This is not a
275
+ one-click migration of your Cloud account; your local repos and agent
276
+ configuration stay in place.
394
277
 
395
278
  ```bash
396
- bivy secrets list
397
- bivy secrets set github.repo-token
398
- bivy secrets ref github.repo-token op://Bivy/GitHub/repo-token
399
- bivy secrets doctor
279
+ bivy relay:setup \
280
+ --control-plane https://bivy.example.com \
281
+ --relay wss://relay.example.com
400
282
  ```
401
283
 
402
- `secret://`, `env://`, and `op://` (1Password) references are resolved only when
403
- an agent needs them, so the raw values do not appear in config files.
404
-
405
- Optional credential sync uploads encrypted vault data and per-machine wrapped
406
- keys, not plaintext credentials. See the
407
- [credential-sync guide](docs/credential-sync.md) for supported credentials and
408
- recovery limits, and the [key-management guide](docs/key-management.md) for
409
- storage options.
284
+ Self-hosting is community-supported: you own TLS, backups, upgrades, and
285
+ hardening. Public multi-architecture images are available as
286
+ `ghcr.io/bivysh/bivy-control-plane` and `ghcr.io/bivysh/bivy-relay`; pin a release
287
+ version or full commit SHA.
410
288
 
411
- Interactive session encryption does not cover every integration: Slack commands
412
- and generic webhook instructions reach the control plane in plaintext. Do not
413
- put secrets in them. The [security model](docs/security-model.md#what-the-control-plane-sees)
414
- explains what each path exposes.
289
+ [Self-host quickstart →](docs/self-host-quickstart.md) ·
290
+ [Operations reference →](docs/self-host.md)
415
291
 
416
- ## Automations as code
292
+ ## Architecture
417
293
 
418
- Define jobs in `.bivy/automations.yaml`, validate them, and test trigger events
419
- locally:
294
+ Your environment, with clear security boundaries:
420
295
 
421
- ```bash
422
- bivy automation init
423
- bivy automation validate
424
- bivy automation test --event .bivy/events/failed-ci.yaml
425
- bivy automation apply
296
+ ```text
297
+ Your machine Hosted or self-hosted
298
+ ┌──────────────────────┐ ┌──────────────────────┐
299
+ │ Node daemon │──outbound──▶│ Relay │
300
+ │ Agents, repos, tools │ │ Encrypted frames │
301
+ │ Local credentials │ └──────────┬───────────┘
302
+ └──────────────────────┘ │
303
+ Browser / phone
304
+ + control plane
305
+ (app, accounts, metadata)
426
306
  ```
427
307
 
428
- Bivy encrypts instructions on the node before upload. Each job records its
429
- sandbox, approval mode, and maximum number of attempts. See
430
- [`docs/automations-as-code.md`](docs/automations-as-code.md).
431
-
432
- ## GitHub Runs
308
+ - **Execution stays on your machine.** Bivy Cloud does not run your agents.
309
+ Your model provider still sees whatever the agent sends it.
310
+ - **Interactive traffic is end-to-end encrypted** between the node and paired
311
+ devices. The relay forwards opaque frames; your node dials out, so no inbound
312
+ public port is required.
313
+ - **Ordinary credential sync uploads ciphertext, not plaintext keys.**
314
+ Supported credentials and recovery limits are documented separately.
315
+ - **Encryption is not universal across integrations.** Slack commands and
316
+ generic webhook instructions reach the control plane in plaintext. Do not
317
+ put secrets in them. Routing and bounded run metadata are also visible there.
318
+ - **Device authorization matters.** QR pairing authorizes a device directly
319
+ through the node. Hosted account pairing trusts the control plane to authorize
320
+ devices and serve the web app that holds client keys.
321
+ - **Bivy is not an OS-level sandbox.** The default approval mode is
322
+ `autonomous`; protection depends on the runtime. Some agents enforce sandbox
323
+ tiers, while process agents may run with your full user permissions.
324
+ Heuristic tool checks help prevent accidents but are not isolation.
325
+
326
+ Review the runtime's Protection label and configure approval/sandbox settings
327
+ for the task, especially before enabling unattended work.
328
+
329
+ [Security model and known limitations →](docs/security-model.md) ·
330
+ [Runtime protection matrix →](docs/runtime-support-matrix.md) ·
331
+ [Configuration →](docs/configuration.md)
332
+
333
+ ## Agents and everyday commands
334
+
335
+ **Claude Code, Codex, Pi, and OpenCode are release-tested.** Additional adapters
336
+ include Gemini CLI, Qwen Code, Goose, Aider, Cline, Crush, Cursor, GitHub Copilot,
337
+ Grok, Amp, Auggie, Droid, Continue, Kilo Code, and Rovo Dev. Installation,
338
+ resume, model selection, and tool protection vary—see the
339
+ [support matrix](docs/runtime-support-matrix.md) and [agent guides](docs/agents/README.md).
340
+
341
+ Run an arbitrary command with `bivy run -- ./your-agent --flags`, register a
342
+ reusable entry with `bivy agent add`, or package a declarative integration with
343
+ experimental [plugins](docs/plugins.md).
433
344
 
434
- Label an issue `bivy` (or `bivy/<machine>` to target a Machine), or mention the
435
- Bivy GitHub App in a comment. Bivy creates a Run on the selected Machine, uses an
436
- isolated worktree, runs the configured checks, and posts the result.
437
-
438
- On Bivy Cloud, a new automation Session counts toward the same allowance as a
439
- manually started remote Session. Self-hosted Core has no Bivy usage limits.
440
-
441
- A private GitHub App only installs on the account that owns it, so connect one
442
- app per GitHub account — one for your personal repos, one per organization
443
- (`bivy github:app-create --org <org>`). A node can serve several at once, each
444
- with its own key and `@`-mention handle.
445
-
446
- See [`docs/github-work-queue.md`](docs/github-work-queue.md).
345
+ ```bash
346
+ bivy run claude # launch a durable session; also codex, pi, opencode
347
+ bivy sessions # list live and saved sessions
348
+ bivy resume # resume the most recent session
349
+ bivy open # open the web app (requires remote setup)
350
+ bivy nodes # list connected account machines
351
+ bivy runs list # inspect delegated work
352
+ bivy automation init # scaffold repo-owned automations
353
+ bivy provider login # connect supported model credentials
354
+ bivy agent add # register an ACP or process agent
355
+ bivy doctor # check installation and connectivity
356
+ bivy logs -f # follow node logs
357
+ bivy update # update and restart the service
358
+ ```
447
359
 
448
- ## Linear Runs
360
+ `bivy update` uses your original installation method and waits for an active
361
+ turn to finish before restarting. Use `--force` to skip that wait.
449
362
 
450
- Apply `bivy` or `bivy/<machine>` to a Linear issue to create a Run on the selected
451
- Machine. The Machine fetches issue content directly from Linear, works in an
452
- isolated GitHub worktree, and asks the agent to open a pull request. See
453
- [`docs/linear-work-queue.md`](docs/linear-work-queue.md).
363
+ [CLI reference →](docs/cli-reference.md) ·
364
+ [Node and project configuration →](docs/config-as-code.md) ·
365
+ [GitHub setup →](docs/github-setup.md) ·
366
+ [Linear setup →](docs/linear-work-queue.md)
454
367
 
455
- ## Development
368
+ ## Development and contributions
456
369
 
457
370
  ```bash
458
371
  pnpm install
459
372
  pnpm run dev # node daemon on http://localhost:4317
460
- pnpm run dev:web # web client dev server (proxies /api and /ws to the node)
373
+ pnpm run dev:web # web client dev server
461
374
  ```
462
375
 
463
- Checks — all of these run in CI:
376
+ | Directory | Contents |
377
+ |---|---|
378
+ | `src/`, `bin/` | Node daemon, CLI, runtime adapters, sessions, approvals, secrets |
379
+ | `packages/core/` | Shared protocol, pairing, and wire format |
380
+ | `packages/web/`, `packages/ui/` | React PWA and shared design system |
381
+ | `services/relay/` | Self-hostable encrypted relay |
382
+ | `services/control-plane/` | Self-hostable control plane |
383
+ | `deploy/` | Deployment examples |
464
384
 
465
385
  ```bash
466
386
  pnpm run typecheck
@@ -472,96 +392,30 @@ pnpm run check:licenses
472
392
  pnpm run check:secrets
473
393
  ```
474
394
 
475
- Repository layout:
476
-
477
- - `src/` — node daemon, runtime adapters, approvals, secrets, sessions
478
- - `bin/` — the `bivy` CLI
479
- - `packages/core` — shared protocol, pairing, wire format
480
- - `packages/web` — the React/Vite PWA client (`@bivy/web`)
481
- - `services/relay` — self-hostable relay
482
- - `services/control-plane` — self-hostable control plane
483
- - `deploy/` — self-host deployment examples
484
-
485
- See [`CONTRIBUTING.md`](CONTRIBUTING.md).
486
-
487
- ## Self-hosting
488
-
489
- The node, web/PWA client, relay, and control plane are all in this repository.
490
- Self-hosting means operating the remote-access infrastructure yourself; agents
491
- still run on computers or servers you have set up and connected.
492
-
493
- Point a node at your own deployment by passing URLs to `bivy relay:setup` —
494
- re-running it switches an existing node over to the new endpoints:
495
-
496
- ```bash
497
- bivy relay:setup \
498
- --control-plane https://bivy.example.com \
499
- --relay wss://relay.example.com
500
- ```
395
+ See [CONTRIBUTING.md](CONTRIBUTING.md) for the development workflow. Releases
396
+ are published from CI with provenance attestations; see
397
+ [release verification](docs/releasing.md).
501
398
 
502
- Each URL has a flag and an environment-variable equivalent (the flag wins):
399
+ **Found a security issue?** Use
400
+ [GitHub private vulnerability reporting](https://github.com/bivysh/bivy/security/advisories/new),
401
+ not a public issue. See [SECURITY.md](SECURITY.md).
503
402
 
504
- | Flag | Environment variable | Points at | Default |
505
- |---|---|---|---|
506
- | `--control-plane <url>` | `BIVY_CONTROL_PLANE_URL` | accounts, node registry, and the web-app API | hosted (`app.bivy.sh`) |
507
- | `--relay <wss-url>` | `BIVY_RELAY_URL` | the encrypted-frame relay your node dials out to | hosted |
508
- | `--client <url>` | `BIVY_CLIENT_BASE_URL` | base URL used when building app/PWA links | the `--control-plane` URL |
509
-
510
- Sign-in defaults to GitHub device login (`--github`); pass
511
- `--email you@example.com` for an email magic-link, or `--session-token <token>`
512
- to skip interactive sign-in. `relay:setup` checks the control plane is reachable,
513
- enrolls this node, and writes the endpoints to `.bivy/relay.json`, so `bivy open`,
514
- `bivy link`, and `bivy update` all keep using your deployment afterwards.
515
-
516
- **Self-hosting is community-supported** — no SLA, best-effort help via GitHub
517
- issues. You own TLS, backups, upgrades, and hardening. Start with the
518
- one-command VPS path in
519
- [`docs/self-host-quickstart.md`](docs/self-host-quickstart.md); the ops
520
- reference (backups, rotation, security boundary) is
521
- [`docs/self-host.md`](docs/self-host.md).
522
-
523
- Prebuilt Core service images are public on GHCR:
524
-
525
- ```text
526
- ghcr.io/bivysh/bivy-control-plane:<version-or-full-commit-sha>
527
- ghcr.io/bivysh/bivy-relay:<version-or-full-commit-sha>
528
- ```
529
-
530
- Use a release version for self-hosting or a full commit SHA for an immutable
531
- build. `latest` moves only when a production release is promoted. Each tag
532
- supports `linux/amd64` and `linux/arm64`; the images are built from this
533
- repository with SBOM and provenance attestations.
534
-
535
- ## Security
536
-
537
- Report vulnerabilities through [GitHub private vulnerability reporting](https://github.com/bivysh/bivy/security/advisories/new).
538
- Please don't open a public issue. See [`SECURITY.md`](SECURITY.md) for scope,
539
- response times, and safe harbour, and [`docs/security-model.md`](docs/security-model.md)
540
- for the trust model and known limitations.
541
-
542
- ## In development
543
-
544
- Ephemeral Machines — automatically provisioned, short-lived servers for agent
545
- work — are in development. The code includes provisioning work for both
546
- Bivy-hosted and self-hosted/bring-your-own-cloud deployments, but **neither path
547
- is ready or supported for this launch**. Bivy Cloud does not offer hosted agent
548
- Machines at launch. Use an existing computer or server you operate instead.
403
+ ### In development—not available at launch
549
404
 
405
+ Automatically provisioned, short-lived **ephemeral machines** are in development
406
+ for hosted and bring-your-own-cloud deployments. Neither path is ready or
407
+ supported for this launch. Use an existing computer or server you operate.
550
408
  Experimental provisioning has different credential-custody and encryption
551
- boundaries; see the [provisioning trust model](docs/hosted-provisioning-trust-model.md)
552
- before evaluating that code. Its presence in the repository is not a readiness
553
- or availability promise.
409
+ boundaries; see the [provisioning trust model](docs/hosted-provisioning-trust-model.md).
554
410
 
555
411
  ## License
556
412
 
557
- Bivy Core is free and open-source software under the GNU Affero General Public
558
- License, version 3.0 only (AGPL-3.0-only). You may use, study, modify, and
559
- self-host it under that license. If you modify Bivy and let users interact with
560
- it over a network, section 13 requires you to offer them the corresponding
561
- source code. See [`LICENSE`](LICENSE).
562
-
563
- **Where the open-core line is.** Everything in this repository — node, CLI,
564
- relay, control plane, and the web/PWA client — is AGPL Core, with no usage
565
- limits. **Bivy Cloud** is the hosted operation of that stack plus billing and
566
- plans, and lives in a separate private repository. Contributions are accepted
567
- under the [DCO](CONTRIBUTING.md#certificate-of-origin); there is no CLA.
413
+ Everything in this repository—node, CLI, web/PWA, relay, and control plane—is
414
+ free and open-source **AGPL-3.0-only Core**, with no Bivy usage limits. You may
415
+ use, modify, and self-host it under that license. If users interact with your
416
+ modified version over a network, section 13 requires you to offer its
417
+ corresponding source. See [LICENSE](LICENSE).
418
+
419
+ Bivy Cloud is the hosted operation of that stack plus billing and plans, in a
420
+ separate private repository. Contributions use the
421
+ [DCO](CONTRIBUTING.md#certificate-of-origin); there is no CLA.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@bivy/bivy",
3
- "version": "0.16.11",
3
+ "version": "0.16.12-staging.2",
4
4
  "type": "module",
5
5
  "license": "AGPL-3.0-only",
6
6
  "description": "Run coding agents on machines you own. Open-source, self-hostable agent workspace.",
@@ -67,6 +67,6 @@
67
67
  "nanoid": "3.3.18",
68
68
  "undici": "8.10.0"
69
69
  },
70
- "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 or Codex in the development environment you already use —\nwith your repo, running services, tools, and credentials. Leave your desk,\nopen the session on your phone, and answer a question, approve an action, or\nreview the diff. GitHub issues, CI, schedules, and webhooks can start work on\nthose same machines.\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 the web app (requires remote setup)\n```\n\nBivy does not replace your coding agent or provide model inference. It keeps\nSessions running, routes work to connected Machines, and gives you one place to\nstart, join, approve, and review work. A **Machine** is a Mac, Linux computer,\nor existing server you operate; a **Session** is the agent work running there.\nYour machine must stay awake and online for remote access.\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 run on your own machines?\n\nA fresh cloud sandbox can be useful, but it is not always the environment your\nwork needs. Bivy connects to the machines you already operate, so your agent can\nuse:\n\n- Your existing working tree, including uncommitted changes.\n- Running dev servers, databases, installed toolchains, and warm caches.\n- Private networks and internal APIs that machine can reach.\n- Your GPUs and local model servers.\n\nYou bring the environment; Bivy makes the work accessible from anywhere.\nBackground Runs can use isolated worktrees without rebuilding the whole machine.\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, opencode\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\n**What Cloud hosts.** Bivy Cloud runs the web app, control plane, and encrypted\nrelay — not your agents or their machines. Connect a computer or server you\nalready operate and bring your own agent subscription or model API key.\n\n- **Free Cloud:** every launch feature, including automations, with 10 new remote\n Sessions per rolling seven days. Manual and automated Sessions share this\n allowance; resuming existing Sessions and viewing history do not consume it.\n No credit card required.\n- **Cloud — $15/month:** unlimited remote Sessions, with the same features.\n- **Self-hosted Core:** run the app, control plane, and relay yourself, with no\n Bivy usage limits.\n\nAgent subscriptions and model-provider charges are separate. See\n[bivy.sh#pricing](https://bivy.sh#pricing) for current hosted pricing.\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| 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\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`) | updates the global npm package, then restarts 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\nThe standard installer uses stable releases (`latest` on npm). Use\n`bivy update` to keep that installation current.\n\nTo skip the wait for a busy session:\n\n```bash\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\nOptional credential sync uploads encrypted vault data and per-machine wrapped\nkeys, not plaintext credentials. See the\n[credential-sync guide](docs/credential-sync.md) for supported credentials and\nrecovery limits, and the [key-management guide](docs/key-management.md) for\nstorage options.\n\nInteractive session encryption does not cover every integration: Slack commands\nand generic webhook instructions reach the control plane in plaintext. Do not\nput secrets in them. The [security model](docs/security-model.md#what-the-control-plane-sees)\nexplains what each path exposes.\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\nOn Bivy Cloud, a new automation Session counts toward the same allowance as a\nmanually started remote Session. Self-hosted Core has no Bivy usage limits.\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\nThe node, web/PWA client, relay, and control plane are all in this repository.\nSelf-hosting means operating the remote-access infrastructure yourself; agents\nstill run on computers or servers you have set up and connected.\n\nPoint a node at your own deployment by passing URLs to `bivy relay:setup` —\nre-running it switches an existing 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\nPrebuilt Core service images are public on GHCR:\n\n```text\nghcr.io/bivysh/bivy-control-plane:<version-or-full-commit-sha>\nghcr.io/bivysh/bivy-relay:<version-or-full-commit-sha>\n```\n\nUse a release version for self-hosting or a full commit SHA for an immutable\nbuild. `latest` moves only when a production release is promoted. Each tag\nsupports `linux/amd64` and `linux/arm64`; the images are built from this\nrepository with SBOM and provenance attestations.\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## In development\n\nEphemeral Machines — automatically provisioned, short-lived servers for agent\nwork — are in development. The code includes provisioning work for both\nBivy-hosted and self-hosted/bring-your-own-cloud deployments, but **neither path\nis ready or supported for this launch**. Bivy Cloud does not offer hosted agent\nMachines at launch. Use an existing computer or server you operate instead.\n\nExperimental provisioning has different credential-custody and encryption\nboundaries; see the [provisioning trust model](docs/hosted-provisioning-trust-model.md)\nbefore evaluating that code. Its presence in the repository is not a readiness\nor availability promise.\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",
70
+ "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\nBivy is an open-source workspace for coding-agent work. Turn prompts, GitHub\nissues, CI failures, Slack messages, and schedules into live sessions on your\nmachines. Choose the agent and model, sync supported API keys and OAuth logins,\nand steer and review the work from your browser, phone, or terminal.\n\nKeep Claude Code, Codex, Pi, OpenCode, or another supported agent. Keep your\nrepos, tools, and development environment. Bivy connects them into a workflow\nthat doesn't end when you leave your desk.\n\n**[Start free on Bivy Cloud](https://app.bivy.sh)** ·\n**[Quickstart](docs/quickstart.md)** ·\n**[Documentation](docs/README.md)** ·\n**[Self-host](docs/self-host-quickstart.md)** ·\n**[Website](https://bivy.sh)**\n\n```bash\ncurl -fsSL https://bivy.sh/install.sh | bash # install + guided setup\ncd your-repo\nbivy run claude # or codex, pi, opencode\nbivy open # continue in the web app (needs remote setup)\n```\n\nBivy Cloud hosts the app, control plane, and relay—not the machines running your\nagents. Connect a Mac, Linux computer, or existing server and bring your own\nagent subscription, model API key, or local model. You can also self-host the\nentire remote-access stack.\n\n> **Bivy is 0.x software.** Claude Code, Codex, Pi, and OpenCode are the\n> release-tested paths. Credential sync, resume, handoffs, approvals, and\n> sandboxing depend on the runtime. See the\n> [runtime support matrix](docs/runtime-support-matrix.md).\n\n## More than remote access\n\nRemote access lets you reach an agent. Bivy also connects **what starts the\nwork, where it runs, which agent and credentials it uses, and how you review\nwhat happened**.\n\n| Capability | What it means for you |\n|---|---|\n| **One workspace, multiple agents** | Use different agents and models for different tasks without maintaining a separate workflow for each. |\n| **Your machines and environment** | Work beside your existing repos, dev servers, databases, private networks, toolchains, and GPUs. |\n| **Automations and triggers** | Let issues, failed CI, messages, schedules, and webhooks start work instead of copying requests into a chat. |\n| **Encrypted key and OAuth sync** | Reuse Bivy-managed provider credentials across enrolled machines and compatible runtimes, with less repeated setup. |\n| **Live sessions from anywhere** | Start at your desk, answer a question or approve an action from your phone, then return to the terminal. |\n| **Reviewable results** | See changes, declared checks, artifacts, and pull requests—not just an agent's claim that it finished. |\n| **Hosted convenience or self-hosting** | Use Bivy Cloud for managed remote access, or run the same open-source core yourself. |\n\n## One workflow, from trigger to review\n\n```text\nPrompt · GitHub issue · CI failure · Linear · Slack · Schedule · Webhook\n │\n ▼\n Choose machine + agent + model\n + supported credentials\n │\n ▼\n Live agent session\n Join · steer · approve · stop\n │\n ▼\n Changes · checks · artifacts · PR\n```\n\nA **Machine** is a computer or server you connect. A **Session** is live agent\nwork on that machine. A **Run** is delegated background work that creates a\nsession and tracks its outcome. An **Automation** is a reusable definition that\ncreates runs when an event matches.\n\nManual and automated work use the same kind of live session. You can join a run\nwhen it needs help rather than wait for a black-box job to finish.\n\n### Work in the environment you already have\n\nA clean cloud sandbox isn't always enough. Your agent may need the database\nrunning on localhost, an uncommitted change, an internal API behind your VPN,\nor a model running on your GPU. Bivy runs the agent where those things already\nexist, subject to that machine's permissions and the runtime's protection.\n\nConnect several machines to the same account: a laptop for interactive work,\na Linux server for background jobs, or a GPU box for local inference. Choose\nthe machine for each session or pin it in an automation. Repository runs can\nuse isolated Git worktrees without rebuilding the whole development environment.\n\n**The execution machine must stay awake and online.** To close your laptop and\nleave work running, run the agent on a different, always-on machine.\n\n[Environment and multi-machine recipes →](docs/capability-recipes.md)\n\n### Use multiple agents, not multiple disconnected workflows\n\nRun Claude Code for one task, Codex for another, and Pi or OpenCode where they\nfit. Bivy supplies the shared session, remote-access, automation, and review\nsurfaces; your chosen agent still does the coding and uses your model provider.\n\n- Choose an agent and, where supported, a model for each session or run.\n- Import existing Claude Code and Codex sessions.\n- Fork or move work to another agent or machine when a different setup fits\n better. Continuation fidelity varies: some paths preserve native history,\n while others replay portable turns or seed the destination with context.\n- Use agent-native logins, Bivy-managed credentials, or local inference.\n Bivy's custom OpenAI-compatible endpoint registry currently feeds Pi;\n other agents may need their own provider configuration.\n- Register your own ACP or headless process agent with `bivy agent add`.\n\nBivy does not replace your agent, provide model inference, or make every agent's\nfeatures identical. Consult the [support matrix](docs/runtime-support-matrix.md)\nand [handoff recipes](docs/capability-recipes.md#fork-or-move-a-session).\n\n### Less signing in. Less copying secrets.\n\nBivy syncs **Bivy-managed API keys and supported OAuth credentials** across\nenrolled machines for compatible runtimes. Connect supported credentials once\nand reuse them where you run work, rather than manually distributing keys to\neach machine.\n\nFor ordinary account sync, credentials are encrypted on the node before upload.\nThe control plane stores ciphertext and wrapped-key metadata; enrolled nodes\nshare access by wrapping the vault key to one another. Bivy Cloud does not\nreceive plaintext credentials through this sync path.\n\nYou can also keep credentials local, use labeled keys and project presets, or\nreference environment variables and 1Password instead of embedding secrets in\nconfiguration:\n\n```bash\nbivy provider login\nbivy credentials add anthropic work\nbivy secrets ref github.repo-token op://Bivy/GitHub/repo-token\n```\n\n**Not every CLI login syncs.** Native agent logins may still be per-machine;\nGitHub App private-key sync is separately opt-in. If you lose every node and\ndevice able to unwrap a vault, you must sign in to providers again. Explicit\nhosted-provisioning custody grants are separate from ordinary encrypted sync.\n\n[Credential sync and runtime coverage →](docs/credential-sync.md) ·\n[Credentials guide →](docs/credentials-guide.md) ·\n[Key storage →](docs/key-management.md)\n\n### Let events start the work\n\nAutomations turn recurring or incoming work into sessions you can join,\nsupervise, and review. Choose the repository, machine, agent, model, approval\nmode, sandbox setting, and maximum attempts.\n\n| Trigger | Example workflow |\n|---|---|\n| **GitHub issues and mentions** | Label an issue `bivy` or `bivy/<machine>`, or mention your Bivy GitHub App, to work toward a pull request. |\n| **Failed CI** | Match a failed workflow, ask the agent to reproduce it, make a fix, and run the affected checks. |\n| **Linear** | Label an issue to start work without copying its description into an agent. |\n| **Slack** | Send a request from the conversation where the work came up. |\n| **Schedules** | Run a weekly dependency review, recurring maintenance, or a one-time task. |\n| **Signed webhooks** | Connect alerts, internal tools, or your own event sources. |\n\nConfigure automations in the app or version them with your repository in\n`.bivy/automations.yaml`:\n\n```bash\nbivy automation init\n# Edit the generated definition for your repository and workflow.\nbivy automation validate\nbivy automation test --event .bivy/events/failed-ci.yaml # supply a local event fixture\nbivy automation apply\n```\n\nOr delegate a one-off job without creating an automation:\n\n```bash\nbivy runs start \"Review outdated dependencies and propose a small, tested update.\"\nbivy runs wait <id>\n```\n\nRuns keep routing and lifecycle evidence, check results, and output references\nin a reviewable Receipt. For unattended issue work, Bivy runs declared repository\nchecks after the agent's turn; failed required checks fail the run even if the\nagent reports success. A completed process alone is not proof that the task\nsucceeded.\n\n[Automation recipes →](docs/capability-recipes.md#let-events-start-runs) ·\n[Automations as code →](docs/automations-as-code.md) ·\n[Run outcomes and reliability limits →](docs/automation-runs.md)\n\n### Start at your desk. Continue anywhere.\n\nOpen the same session in the browser, phone PWA, or terminal. Watch work live,\nanswer questions, approve supported tool calls, or stop the agent.\n\n- Send screenshots, images, logs, and other files from your phone.\n- Download reports and artifacts the agent creates.\n- Use voice input and read-aloud where supported; provider-backed voice may\n send audio or text to the selected provider.\n- Keep a native terminal workflow or use structured chat, depending on the agent.\n\n```bash\nbivy run claude --no-follow # start without attaching\nbivy open # open the web app\nbivy resume # return to the session in your terminal\nbivy link # pair a device directly via QR\n```\n\nNo phone app installation is required. Open [app.bivy.sh](https://app.bivy.sh)\nin your browser; adding it to your home screen is optional.\n\n[Remote access →](docs/remote-access.md) ·\n[Voice, files, and terminal recipes →](docs/capability-recipes.md)\n\n## Get started\n\n### Install\n\nBivy supports **macOS and Linux with Node.js 20+**. The installer installs the\n`@bivy/bivy` package, runs guided setup, and starts a launchd or systemd service:\n\n```bash\ncurl -fsSL https://bivy.sh/install.sh | bash\n```\n\nSetup helps you choose an agent and configure remote access. Existing agents\nkeep their command, login, and configuration. The installer may use `sudo` to\ninstall Node.js if needed, but never for `npm install`. To inspect it first,\ndownload it with `curl -fsSL https://bivy.sh/install.sh -o install.sh`.\n\nAlready have Node.js and want to avoid sudo?\n\n```bash\nnpm install -g @bivy/bivy\nbivy setup\n```\n\nThen try one small task:\n\n```bash\ncd your-repo\nbivy run claude\n# Ask: \"Explain this repo and make one small, safe improvement. Run the relevant checks.\"\nbivy open\n```\n\nOpen that same session on your phone while it runs. Once that works, connect\nanother machine or add your first automation.\n\n**Local-only works too.** `bivy run`, `bivy resume`, and `bivy sessions` need no\naccount or server. Choose **local only for now** during setup; use `bivy login`\nlater. Browser and phone access need a hosted or self-hosted control plane;\nthe node itself does not serve a web UI.\n\n[Full quickstart →](docs/quickstart.md) ·\n[Installer options, service management, and uninstall →](docs/install.md)\n\n### Choose hosted or self-hosted\n\n| Option | What you get |\n|---|---|\n| **Free Cloud — $0** | Every launch feature, including automations; 10 new remote sessions per rolling seven days. No credit card required. |\n| **Cloud — $15/month** | The same features with unlimited remote sessions. |\n| **Self-hosted Core** | Operate the app, control plane, and relay yourself, with no Bivy usage limits. |\n\nManual and automated sessions share the Cloud allowance. Resuming existing\nsessions and viewing history do not consume it. Agent subscriptions and model\nprovider charges are separate. See [current pricing](https://bivy.sh#pricing).\n\nStart on Cloud and self-host later if you prefer. Deploy the stack, reconnect\nmachines with `bivy relay:setup`, and pair devices to your server. This is not a\none-click migration of your Cloud account; your local repos and agent\nconfiguration stay in place.\n\n```bash\nbivy relay:setup \\\n --control-plane https://bivy.example.com \\\n --relay wss://relay.example.com\n```\n\nSelf-hosting is community-supported: you own TLS, backups, upgrades, and\nhardening. Public multi-architecture images are available as\n`ghcr.io/bivysh/bivy-control-plane` and `ghcr.io/bivysh/bivy-relay`; pin a release\nversion or full commit SHA.\n\n[Self-host quickstart →](docs/self-host-quickstart.md) ·\n[Operations reference →](docs/self-host.md)\n\n## Architecture\n\nYour environment, with clear security boundaries:\n\n```text\nYour machine Hosted or self-hosted\n┌──────────────────────┐ ┌──────────────────────┐\n│ Node daemon │──outbound──▶│ Relay │\n│ Agents, repos, tools │ │ Encrypted frames │\n│ Local credentials │ └──────────┬───────────┘\n└──────────────────────┘ │\n Browser / phone\n + control plane\n (app, accounts, metadata)\n```\n\n- **Execution stays on your machine.** Bivy Cloud does not run your agents.\n Your model provider still sees whatever the agent sends it.\n- **Interactive traffic is end-to-end encrypted** between the node and paired\n devices. The relay forwards opaque frames; your node dials out, so no inbound\n public port is required.\n- **Ordinary credential sync uploads ciphertext, not plaintext keys.**\n Supported credentials and recovery limits are documented separately.\n- **Encryption is not universal across integrations.** Slack commands and\n generic webhook instructions reach the control plane in plaintext. Do not\n put secrets in them. Routing and bounded run metadata are also visible there.\n- **Device authorization matters.** QR pairing authorizes a device directly\n through the node. Hosted account pairing trusts the control plane to authorize\n devices and serve the web app that holds client keys.\n- **Bivy is not an OS-level sandbox.** The default approval mode is\n `autonomous`; protection depends on the runtime. Some agents enforce sandbox\n tiers, while process agents may run with your full user permissions.\n Heuristic tool checks help prevent accidents but are not isolation.\n\nReview the runtime's Protection label and configure approval/sandbox settings\nfor the task, especially before enabling unattended work.\n\n[Security model and known limitations →](docs/security-model.md) ·\n[Runtime protection matrix →](docs/runtime-support-matrix.md) ·\n[Configuration →](docs/configuration.md)\n\n## Agents and everyday commands\n\n**Claude Code, Codex, Pi, and OpenCode are release-tested.** Additional adapters\ninclude Gemini CLI, Qwen Code, Goose, Aider, Cline, Crush, Cursor, GitHub Copilot,\nGrok, Amp, Auggie, Droid, Continue, Kilo Code, and Rovo Dev. Installation,\nresume, model selection, and tool protection vary—see the\n[support matrix](docs/runtime-support-matrix.md) and [agent guides](docs/agents/README.md).\n\nRun an arbitrary command with `bivy run -- ./your-agent --flags`, register a\nreusable entry with `bivy agent add`, or package a declarative integration with\nexperimental [plugins](docs/plugins.md).\n\n```bash\nbivy run claude # launch a durable session; also codex, pi, opencode\nbivy sessions # list live and saved sessions\nbivy resume # resume the most recent session\nbivy open # open the web app (requires remote setup)\nbivy nodes # list connected account machines\nbivy runs list # inspect delegated work\nbivy automation init # scaffold repo-owned automations\nbivy provider login # connect supported model credentials\nbivy agent add # register an ACP or process agent\nbivy doctor # check installation and connectivity\nbivy logs -f # follow node logs\nbivy update # update and restart the service\n```\n\n`bivy update` uses your original installation method and waits for an active\nturn to finish before restarting. Use `--force` to skip that wait.\n\n[CLI reference →](docs/cli-reference.md) ·\n[Node and project configuration →](docs/config-as-code.md) ·\n[GitHub setup →](docs/github-setup.md) ·\n[Linear setup →](docs/linear-work-queue.md)\n\n## Development and contributions\n\n```bash\npnpm install\npnpm run dev # node daemon on http://localhost:4317\npnpm run dev:web # web client dev server\n```\n\n| Directory | Contents |\n|---|---|\n| `src/`, `bin/` | Node daemon, CLI, runtime adapters, sessions, approvals, secrets |\n| `packages/core/` | Shared protocol, pairing, and wire format |\n| `packages/web/`, `packages/ui/` | React PWA and shared design system |\n| `services/relay/` | Self-hostable encrypted relay |\n| `services/control-plane/` | Self-hostable control plane |\n| `deploy/` | Deployment examples |\n\n```bash\npnpm run typecheck\npnpm run typecheck:web\npnpm run lint\npnpm run test:unit\npnpm run test:core\npnpm run check:licenses\npnpm run check:secrets\n```\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for the development workflow. Releases\nare published from CI with provenance attestations; see\n[release verification](docs/releasing.md).\n\n**Found a security issue?** Use\n[GitHub private vulnerability reporting](https://github.com/bivysh/bivy/security/advisories/new),\nnot a public issue. See [SECURITY.md](SECURITY.md).\n\n### In development—not available at launch\n\nAutomatically provisioned, short-lived **ephemeral machines** are in development\nfor hosted and bring-your-own-cloud deployments. Neither path is ready or\nsupported for this launch. Use an existing computer or server you operate.\nExperimental provisioning has different credential-custody and encryption\nboundaries; see the [provisioning trust model](docs/hosted-provisioning-trust-model.md).\n\n## License\n\nEverything in this repository—node, CLI, web/PWA, relay, and control plane—is\nfree and open-source **AGPL-3.0-only Core**, with no Bivy usage limits. You may\nuse, modify, and self-host it under that license. If users interact with your\nmodified version over a network, section 13 requires you to offer its\ncorresponding source. See [LICENSE](LICENSE).\n\nBivy Cloud is the hosted operation of that stack plus billing and plans, in a\nseparate private repository. Contributions use the\n[DCO](CONTRIBUTING.md#certificate-of-origin); there is no CLA.\n",
71
71
  "readmeFilename": "README.md"
72
72
  }