@capybara-hq/device 0.1.0-rc.8 → 0.1.0-rc.9

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 (46) hide show
  1. package/README.md +90 -179
  2. package/dist/api.d.ts +5 -0
  3. package/dist/args.d.ts +7 -2
  4. package/dist/args.js +33 -16
  5. package/dist/cli.d.ts +7 -5
  6. package/dist/cli.js +20 -31
  7. package/dist/client.d.ts +0 -2
  8. package/dist/client.js +9 -10
  9. package/dist/command-log.d.ts +3 -5
  10. package/dist/commands/login.js +55 -1
  11. package/dist/commands/mode.d.ts +52 -0
  12. package/dist/commands/mode.js +108 -0
  13. package/dist/commands/policy.d.ts +11 -65
  14. package/dist/commands/policy.js +62 -249
  15. package/dist/commands/start.d.ts +2 -2
  16. package/dist/commands/start.js +14 -6
  17. package/dist/commands/status.js +11 -3
  18. package/dist/exec/docker.d.ts +22 -30
  19. package/dist/exec/docker.js +81 -69
  20. package/dist/exec/fs-helper.d.ts +13 -8
  21. package/dist/exec/fs-helper.js +30 -12
  22. package/dist/exec/host.d.ts +8 -8
  23. package/dist/exec/host.js +9 -9
  24. package/dist/exec/os.d.ts +36 -69
  25. package/dist/exec/os.js +65 -159
  26. package/dist/exec/sandbox-messages.d.ts +14 -0
  27. package/dist/exec/sandbox-messages.js +21 -0
  28. package/dist/exec/shared.d.ts +21 -36
  29. package/dist/exec/shared.js +30 -164
  30. package/dist/exec/switch.d.ts +38 -55
  31. package/dist/exec/switch.js +58 -108
  32. package/dist/exec/types.d.ts +8 -18
  33. package/dist/index.d.ts +1 -1
  34. package/dist/network.d.ts +7 -7
  35. package/dist/network.js +11 -18
  36. package/dist/policy-store.d.ts +7 -8
  37. package/dist/policy-store.js +11 -15
  38. package/dist/policy.d.ts +25 -100
  39. package/dist/policy.js +44 -146
  40. package/dist/server-ops.d.ts +15 -35
  41. package/dist/server-ops.js +36 -117
  42. package/dist/state.d.ts +15 -16
  43. package/dist/state.js +38 -36
  44. package/package.json +2 -2
  45. package/dist/proxy-guard.d.ts +0 -58
  46. package/dist/proxy-guard.js +0 -137
package/README.md CHANGED
@@ -2,7 +2,8 @@
2
2
 
3
3
  `capybara-device` connects a laptop or server to a [Capybara](https://github.com/capybara-hq/core)
4
4
  deployment as a device: the platform's agents run commands and read and write files on this
5
- machine, inside a sandbox, while the program is online.
5
+ machine, in auto mode (as you, with every command reviewed by the deployment) or inside an OS
6
+ sandbox, while the program is online.
6
7
 
7
8
  Runs on macOS and Linux. Native Windows is refused: use WSL (then it is a Linux machine) or Docker
8
9
  mode inside WSL. Node 22.12 or newer.
@@ -49,9 +50,12 @@ the device page says so. To start afresh, run `capybara-device logout` and then
49
50
  and the platform rebuilds the device on its next use.
50
51
 
51
52
  Commands: `login --url <url> [--no-browser] [--dir <path>] [--mode os|docker]`, `logout`,
52
- `status [--json]`, `start`, `stop`, `drain [--wait] [--timeout <seconds>]`,
53
+ `status [--json]` (it prints the command mode too), `start`, `stop`,
54
+ `drain [--wait] [--timeout <seconds>]`, `mode [auto|sandbox] [--yes]`,
53
55
  `policy [show | set <key> <value> [--yes] | add|remove <key> <value>]` and
54
56
  `service install|uninstall|status`.
57
+ `mode` is the only way to switch the command mode (`policy set mode` points there); `mode auto`
58
+ prints the risk text and asks for confirmation unless `--yes` is given.
55
59
 
56
60
  State lives in `$XDG_CONFIG_HOME/capybara-device` (default `~/.config/capybara-device`):
57
61
  `credential.json` (mode 0600; the program refuses a file other users can read; it also holds the
@@ -63,26 +67,46 @@ keeps the last valid policy and logs one error). Changes made with `capybara-dev
63
67
  The working directory (default `~/capybara-device/<deviceId>`) holds `workspace/`, `skills/`
64
68
  and `tmp/`.
65
69
 
66
- In OS mode every command runs inside `@anthropic-ai/sandbox-runtime` (macOS Seatbelt, Linux
67
- bubblewrap; Linux needs `bwrap` and `socat`): writes only under `workspace/` and `tmp/`,
68
- `skills/` read only, `~/.ssh`, cloud CLI credentials, `~/.netrc`, `~/.gnupg`, browser profiles and
69
- this program's state directory unreadable. What else a command may do depends on the device's
70
- [sandbox tier](#sandbox-tiers): at `strict`, network only to the domains of the local policy that
71
- the device's egress also allows (with an empty list, no network at all); at `dev` (the default of
72
- every organization unless changed) also the common package registries and local servers; at
73
- `open` anything the organization allows. You edit the policy locally; the deployment can change it
74
- only as described in [Changes from the deployment](#changes-from-the-deployment):
70
+ In OS mode a device runs every command in one of two modes (`mode` in `policy.json`; switch it
71
+ with `capybara-device mode`):
72
+
73
+ - **auto** (the default of a new login): commands run directly on this computer as you — your real
74
+ `HOME`, `PATH`, environment, caches, credentials (SSH keys, `gh`, cloud CLIs), Docker and any
75
+ network. It is what a coding agent without an OS sandbox has, and what Claude Code calls auto
76
+ mode. The deployment reviews every command before it runs and blocks, or asks about, the
77
+ dangerous ones (deleting outside the workspace, sending a secret away, force-pushing a protected
78
+ branch). The platform's file tools reach any absolute path on the machine.
79
+ - **sandbox**: today's strict `@anthropic-ai/sandbox-runtime` profile (macOS Seatbelt, Linux
80
+ bubblewrap; Linux needs `bwrap` and `socat`). Writes only under `workspace/` and `tmp/`,
81
+ `skills/` read only, `HOME` = the workspace, `~/.ssh`, cloud CLI credentials, `~/.netrc`,
82
+ `~/.gnupg`, browser profiles and this program's state directory unreadable, no local binding or
83
+ unix sockets, and network only to the domains of the local policy that the organization's
84
+ allowlist also admits (with an empty list, no network at all). Commands keep their package
85
+ caches in the workspace like any other file.
86
+
87
+ If the OS sandbox is unavailable on the machine (an unsupported platform or missing dependencies,
88
+ such as `bwrap` / `socat` on Linux), the device still starts and serves: auto mode works, and every
89
+ sandbox-mode command is refused with the reason and how to fix it (`capybara-device mode auto`, or
90
+ install the dependencies and restart). `capybara-device mode sandbox` is refused on such a machine
91
+ and the policy stays in auto; nothing ever runs unsandboxed by falling back.
75
92
 
76
93
  ```bash
77
- capybara-device policy set allowedDomains registry.npmjs.org,*.github.com
78
- capybara-device policy add allowedDomains files.slack.com
94
+ capybara-device mode # print the current mode
95
+ capybara-device mode sandbox # switch to the sandbox
96
+ capybara-device mode auto # prints the risk text and asks; or add --yes
97
+ capybara-device policy add allowedDomains files.slack.com # sandbox mode
79
98
  capybara-device policy remove allowedDomains files.slack.com
80
99
  capybara-device policy show
81
100
  ```
82
101
 
83
- Changes apply at the next command; a running program does not need a restart. `add` and `remove`
84
- work on `allowedDomains` and `allowCredentials`; every domain must be a lowercase host name
85
- (optionally `*.` for subdomains, never the apex), never an IP address or an internal name.
102
+ A change applies at the next command; a running program does not need a restart. Turning the
103
+ sandbox back on stops the commands still running in auto mode. Auto mode is set only on the
104
+ machine: the deployment may narrow a device to `sandbox` but never turn auto mode on. An
105
+ organization can allow or forbid auto mode; when it forbids it, this device runs in the sandbox
106
+ and its summary says so, and the device's own `mode sandbox` always wins. `add` and `remove` work
107
+ on `allowedDomains` and `allowCredentials`; every domain must be a lowercase host name (optionally
108
+ `*.` for subdomains, never the apex), never an IP address or an internal name. They apply in
109
+ sandbox mode only.
86
110
 
87
111
  A command ends with everything it started: once it returns (or times out, or is stopped), the
88
112
  program kills what it left running, such as `server &` or `nohup …`, because inside the sandbox no
@@ -111,165 +135,50 @@ lines (at most 21).
111
135
 
112
136
  In OS mode each command's result also carries the refused hosts and their layers, so the
113
137
  deployment can ask the device owner on the spot (the device announces this in its hello, together
114
- with a summary of its local policy: the chosen and effective `tier`, `isolation`, what `localhost`
115
- and `unixSockets` give on this machine, `allowedDomains` and `remoteGrants`).
116
-
117
- ### Sandbox tiers
118
-
119
- `tier` in `policy.json` is `strict`, `dev` or `open`; without it (the default) the device follows
120
- the organization's default tier, which is `dev` unless an admin changed it. The deployment sends
121
- the organization's ceiling with every command, and the device runs the command at its own tier cut
122
- to that ceiling: a device set to `open` in an organization that allows at most `dev` runs at
123
- `dev`.
124
-
125
- | | `strict` | `dev` | `open` |
126
- |---|---|---|---|
127
- | Network | `allowedDomains` within the organization's list | also the dev hosts (npm, PyPI, GitHub, crates.io, Go, Maven / Gradle, Docker Hub, Playwright) | anything the organization allows |
128
- | Local servers (macOS) | no | yes, unless a local proxy is detected | same as `dev` |
129
- | Unix sockets (macOS) | no | under `workspace/`, `tmp/` and the socket directory | same as `dev` |
130
- | Package caches | none | `<dir>/cache/` | same as `dev` |
131
-
132
- In every tier commands keep `HOME` = `workspace/`, writes stay inside the device directory (plus
133
- the socket directory), the secret paths stay unreadable, and the network proxy refuses loopback,
134
- private addresses and internal names as destinations. Local servers are a separate permission:
135
- at `dev` and `open` on macOS a command may listen on and connect to this machine's localhost
136
- directly (below), never through the proxy.
137
-
138
- The tier sets what the device adds to its own list; the organization's ceiling only cuts. So a
139
- device at `strict` under a `dev` ceiling still reaches a dev host (say `registry.npmjs.org`) when
140
- its owner listed it in `allowedDomains`: `strict` means "only what I listed", not "less than the
141
- organization's strict list".
138
+ with a summary of its local policy: the effective `mode` and the sandbox-mode
139
+ `allowedDomains`).
142
140
 
143
- ```bash
144
- capybara-device policy set tier dev # or strict
145
- capybara-device policy set tier open --yes # anything the organization allows
146
- capybara-device policy set tier default # follow the organization's default again
147
- capybara-device policy show # what the tier gives on this machine
148
- ```
141
+ ### Sandbox mode details
149
142
 
150
- `set tier open` prints the risk and changes nothing without a confirmation: `--yes`, or, on a
151
- terminal, an answer of `y` at the prompt (without a terminal and without `--yes` it exits with
152
- status 2): at `open` a command can upload files to any outside site the organization allows, and
153
- prompt injection can make an agent do that. Turn it on only on your own development machine, with
154
- agents and material you trust. Lower tiers are always accepted. When the organization allows any
155
- host too, the program lets a command reach any public host only while a command started that way
156
- is running (the sandbox runtime cannot list "any host" per command, so it is allowed process-wide
157
- meanwhile; a lower tier takes effect at once). The device's owner can also raise the tier on the
158
- device page, behind the same risk text, while `remoteGrants` is `owner`.
159
-
160
- An older `policy.json` with `network` is read without it (the device follows the organization's
161
- default) and loses the key at the next change; `start` says so at each start while it held
162
- `network: open`. Any `capybara-device policy set` writes the file again and so clears the notice.
163
-
164
- #### Local servers, sockets and caches at `dev` and `open`
165
-
166
- - **Git.** Commands may write `.git/config`, so `git init`, `git clone`, `git config`,
167
- `git remote add` and branch tracking work. `.git/hooks` stays unwritable at every tier (a hook is
168
- code that runs unsandboxed when you later run git in that folder yourself), and `GIT_TEMPLATE_DIR`
169
- points at an empty, read-only `<dir>/git-template`, so init and clone copy no sample hooks. At
170
- `strict`, `.git/config` stays unwritable too. Remaining risk: a `.git/config` a command wrote can
171
- set `core.hooksPath`, `core.fsmonitor`, `core.sshCommand` or similar, which run when you later
172
- run git in that repository on your own machine. Treat a repository a command created or
173
- configured like any downloaded one (check `git config --local --list` before running git there),
174
- or keep the device at `strict`.
175
-
176
- - **Local servers (macOS).** Commands may listen on local ports (a dev server, a browser's
177
- debugging port) and connect to this machine's localhost. That also reaches any local proxy that
178
- forwards past the network allowlist (Clash and the like) or Docker's TCP API, so the program
179
- looks for one when it starts and whenever `policy.json` changes: the system proxy
180
- (`scutil --proxy`), `HTTP_PROXY` / `HTTPS_PROXY` / `ALL_PROXY` pointing at loopback in its own
181
- environment, and a listener on 127.0.0.1 or ::1 ports 7890, 7891, 7897, 1080, 1087, 8118, 9050,
182
- 9150, 2375 or 2376. When it finds one, commands get no localhost and `policy show` says why. A
183
- proxy set up only through a PAC file (automatic proxy configuration) or on another port is not
184
- found: if you run one, keep `localhost auto` and consider tier `strict`. To allow localhost
185
- despite a detected proxy: `capybara-device policy set localhost allow` (back with
186
- `localhost auto`).
187
- - **Local servers (Linux).** The sandbox has its own network namespace: a server listens and
188
- answers inside the command (and its children), never reachable from the host's browser.
189
- - **Unix sockets (macOS).** Allowed under `workspace/`, `tmp/` and a short socket directory
190
- `/private/tmp/cap-<8 hex>` (mode 0700, made at start), never anywhere else (Docker's socket stays
191
- out of reach). `TMPDIR` and `MAC_CHROMIUM_TMPDIR` point at the socket directory, so a headless
192
- Chromium's socket path stays under the 104-byte limit (`chromium-headless-shell` with
193
- `--single-process`; full Chrome needs the patched sandbox runtime, see below).
194
- - **The sandbox runtime patch is not in published installs yet.** This repository patches
195
- `@anthropic-ai/sandbox-runtime` (`patches/@anthropic-ai__sandbox-runtime@*.patch`, applied by pnpm
196
- in the workspace) so the macOS profile lets full Chrome read the `hw.product` and
197
- `kern.hv_vmm_present` sysctls it needs to start headless. The package is built with plain `tsc`
198
- and depends on the runtime from npm, so `npm i -g @capybara-hq/device` installs the unpatched
199
- runtime: there, full Chrome (and Puppeteer's or Playwright's default `chrome` / `chromium`
200
- headless mode) fails to start in the macOS sandbox. Everything else works the same:
201
- `chromium-headless-shell` with `--single-process`, local servers, unix sockets, package caches,
202
- the network rules, Linux (the patch is macOS only), Docker mode and running without a sandbox.
203
- - **Unix sockets (Linux).** Blocked: the sandbox runtime can only allow every socket there,
204
- including the host daemons' (Docker, D-Bus, ssh-agent). Allowing them with the daemons' sockets
205
- masked is planned after a spike that proves them unreachable; it has not been done yet. Use
206
- Docker mode for browsers on Linux.
207
- - **Package caches.** `XDG_CACHE_HOME`, `npm_config_cache`, `PIP_CACHE_DIR`, `UV_CACHE_DIR`,
208
- `CARGO_HOME`, `GOMODCACHE`, `GOCACHE`, `GRADLE_USER_HOME`, `MAVEN_OPTS` (`-Dmaven.repo.local`), `PLAYWRIGHT_BROWSERS_PATH` and `COREPACK_HOME` point at
209
- folders of `<dir>/cache/`, kept across commands. Your own `~/.npm`, `~/.cache` and pnpm store stay
210
- read only, so a sandboxed command cannot poison your own builds. A command that sets one of
211
- these variables itself keeps its value. pnpm's store is not redirected (pnpm reads it only from
212
- `npm_config_store_dir`, which makes npm warn on every command): it stays at pnpm's default under
213
- the command's HOME, the workspace.
214
-
215
- ### Running without a sandbox
216
-
217
- `isolation` in `policy.json` is `sandbox` (default) or `none`. With `none` and tier `open`, in OS
218
- mode, commands run directly on this computer as you: your real `HOME`, `PATH`, environment,
219
- caches, credentials (SSH keys, cloud accounts, keychain), Docker and any network, like a coding
220
- agent with its sandbox off. They still start in `workspace/`, and the platform's file tools still
221
- stay inside the device's directories. Such commands can also read this program's own credential
222
- (`credential.json`): if you suspect misuse, run `capybara-device logout` and log in again, which
223
- revokes it. Prompt injection can make an agent delete files or send your credentials away: turn it
224
- on only on your own development machine, with agents and material you fully trust.
143
+ In sandbox mode commands keep `HOME` = `workspace/`, writes stay inside the device directory, the
144
+ secret paths stay unreadable, and the network proxy refuses loopback, private addresses and
145
+ internal names as destinations. The device's `allowedDomains` are intersected with the
146
+ organization's allowlist; a host either list refuses is reported as described above.
225
147
 
226
- ```bash
227
- capybara-device policy set tier open --yes # first: an explicit local tier open
228
- capybara-device policy set isolation none --yes
229
- capybara-device policy set isolation sandbox # back to the sandbox
230
- ```
148
+ Version managers (asdf, nvm, pyenv, mise, …) find their data under the real home, read only, so
149
+ their shims work with `HOME` = the workspace. Git can read a repository, but `.git/config` and
150
+ `.git/hooks` stay unwritable: a hook or `core.sshCommand` a command wrote would run when you later
151
+ run git there. When you want git to write (init, clone, remotes) or commands to use your
152
+ credentials, use auto mode.
231
153
 
232
- It is set only on this machine: `set isolation none` is refused unless `tier` is set to `open` in
233
- `policy.json` (following the organization's default is not enough), prints the risk and needs
234
- `--yes` or a `y` at the prompt, and the device refuses it from the deployment whatever `remoteGrants` says (turning it
235
- back to `sandbox` from the deployment is accepted). A Docker-mode device refuses it. The platform
236
- or the organization may refuse to use a device that runs without a sandbox; its owner then turns
237
- the sandbox back on.
154
+ ### The auto mode risk
155
+
156
+ In auto mode agent commands have your full capability. The deployment reviews every command and
157
+ blocks or asks about the dangerous ones, but that review is the boundary, not an OS sandbox: prompt
158
+ injection can still make an agent attempt to delete files or send your credentials away. Commands
159
+ can also read this program's own credential (`credential.json`): if you suspect misuse, run
160
+ `capybara-device logout` and log in again, which revokes it. Keep auto mode to your own development
161
+ machine, with agents and material you trust; `capybara-device mode sandbox` turns the sandbox back
162
+ on.
238
163
 
239
164
  ### Changes from the deployment
240
165
 
241
- `remoteGrants` in `policy.json` decides whether the deployment may widen this device's network
242
- policy on the device owner's decision (an approval answered in a signed-in web or IM session, or
243
- the device page):
244
-
245
- - `owner` (default): the device accepts the `policy` operation's additions to `allowedDomains`
246
- (an approval adds an exact host; the device page may add a `*.` wildcard) and a higher `tier`,
247
- and adds a run's or a scheduled task's granted hosts to a command's list. Grants are exact hosts
248
- and never go beyond the organization's egress.
249
- - `off`: the device refuses every widening from the deployment (additions, a higher `tier`, run and
250
- task grants) with "This device does not accept network changes from the deployment; allow it
251
- locally: capybara-device policy add allowedDomains <host>".
252
-
253
- `isolation: none` is never accepted from the deployment. Narrowing (removing hosts, a lower
254
- `tier`, `isolation: sandbox`) is always accepted. Every host is validated like
255
- a local one, the change is written under `policy.json.lock`, and it applies at the next command.
256
- `remoteGrants` itself is set only locally: `capybara-device policy set remoteGrants owner|off`
257
- (or in `policy.json`). Each change from the deployment is
258
- recorded in the local command log (`commands.log`, next to `policy.json`) with who decided it,
259
- and so is a refused attempt and the grants a command was given:
166
+ The deployment changes the local policy only by narrowing it: it may add or remove
167
+ `allowedDomains` (an approval adds an exact host; the device page may add a `*.` wildcard) and set
168
+ `mode: "sandbox"`. It can never set `mode: "auto"` — that is `capybara-device mode auto` on the
169
+ machine, with its risk text and confirmation. Every host is validated like a local one, the change
170
+ is written under `policy.json.lock`, and it applies at the next command. Each change from the
171
+ deployment is recorded in the local command log (`commands.log`, next to `policy.json`) with who
172
+ decided it, and so is a refused attempt and the grants a command was given:
260
173
 
261
174
  ```text
262
175
  {"op":"policy","detail":"policy add files.slack.com by Ada Lovelace (acc_123) via web, approval apr_456",...}
263
- {"op":"policy","detail":"policy refused tier open by Ada Lovelace (acc_123) via web",...}
176
+ {"op":"policy","detail":"policy refused mode auto by Ada Lovelace (acc_123) via web",...}
264
177
  {"op":"exec","detail":"grants run run_789 by acc_123: files.slack.com",...}
265
178
  ```
266
179
 
267
- Docker mode has no per-domain allowlist (a container has either no network or the whole
268
- internet), so a Docker-mode device refuses every widening from the deployment ("This device runs
269
- commands in Docker mode, which cannot limit network access per domain; switch the device to OS mode
270
- to allow single domains."), reports no refused hosts and ignores grants; narrowing still applies.
271
- `capybara-device policy add allowedDomains` on a Docker-mode device warns that any allowed domain
272
- opens the whole internet.
180
+ A run's or a scheduled task's network grants apply in sandbox mode only, within the organization's
181
+ allowlist; auto mode has the machine's own network, so grants do nothing there.
273
182
 
274
183
  Limit to know: commands of one device run as the same user, and the sandbox runtime ties a
275
184
  command's list (including its run grants) to the proxy credentials it hands that command. Another
@@ -279,11 +188,12 @@ usable by a concurrent command of another run on that device: same owner, same d
279
188
  Limits to know: the platform's `Grep` tool assumes GNU grep, so on macOS (BSD grep) in OS mode some
280
189
  Grep options behave differently or fail. Docker mode (a Linux container) does not have this issue.
281
190
 
282
- Not enforced yet in OS mode: the `cpu` and `memoryMb` ceilings, and `allowCredentials` (commands
283
- get no local credentials at all). Processes a command leaves running are killed when it ends;
284
- on macOS a child that leaves the command's process group and runs only Apple system binaries
285
- cannot be found by its marker (`ps -E` hides their environment), so it survives (Linux runs each
286
- command in its own pid namespace, which takes every child down with it).
191
+ Not enforced yet in OS mode: the `cpu` and `memoryMb` ceilings. In auto mode commands already see
192
+ the owner's credentials, so `allowCredentials` has nothing to add; in sandbox mode they get none.
193
+ Processes a command leaves running are killed when it ends; on macOS a child that leaves the
194
+ command's process group and runs only Apple system binaries cannot be found by its marker
195
+ (`ps -E` hides their environment), so it survives (Linux runs each command in its own pid
196
+ namespace, which takes every child down with it).
287
197
 
288
198
  ## Docker mode
289
199
 
@@ -294,18 +204,19 @@ run as your own uid:gid, so they can write the mounted directories you own (a ro
294
204
  the image's `sandbox` user, uid 1000); on macOS as the image's `sandbox` user. `<dir>/workspace`, `<dir>/skills` (read only) and `<dir>/tmp` are mounted
295
205
  at `/workspace`, `/skills` and `/tmp`; the container has a read-only root file system, a pids limit of 1024, `--memory-swap` equal to
296
206
  `memoryMb`, `--cap-drop ALL` and `no-new-privileges`. The policy's `cpu` and
297
- `memoryMb` become `--cpus` and `--memory`; at tier `dev` and `open` `/dev/shm` grows to a quarter
298
- of `memoryMb` (at most 1 GiB; 1 GiB without a ceiling) for browsers. The container is reused while
299
- its mounts and flags match and recreated when they change (at the next command that finds it
300
- idle); it stays running (idle) between starts. Commands always have the container's own localhost
301
- and unix sockets; `isolation none` is refused.
302
-
303
- Docker mode has no domain allowlist: a command has either no network (`--network none`) or the
304
- default bridge, with the whole internet and this machine's network. It gets the bridge only when
305
- the local `allowedDomains` holds a domain the device's egress allows, or the tier is `open` and the
306
- organization allows any host (under an organization allowlist, `open` counts only the explicit
307
- local domains, like the lower tiers); the dev hosts of tier `dev` do not open it. Use OS mode to limit
308
- commands to single domains.
207
+ `memoryMb` become `--cpus` and `--memory`. The container is reused while its mounts and flags
208
+ match and recreated when they change (at the next command that finds it idle); it stays running
209
+ (idle) between starts. Commands always have the container's own localhost and unix sockets.
210
+
211
+ Docker mode has no per-domain network filter, so the mode alone decides:
212
+
213
+ - **auto**: the container runs on Docker's default bridge (the whole internet and this machine's
214
+ network), and the platform's file tools reach any absolute path in the container.
215
+ - **sandbox**: the container has no network at all, and file operations stay in the mounted roots.
216
+
217
+ The network is switched between the two without recreating the container (a container disconnected
218
+ from every network has no network, the same as `--network none`). Use OS mode's sandbox when you
219
+ need to allow single domains.
309
220
 
310
221
  ## Running at login
311
222
 
package/dist/api.d.ts CHANGED
@@ -14,6 +14,11 @@ export interface TokenResponse {
14
14
  reconnectGraceSeconds: number;
15
15
  /** The program uses 16 MiB when it is absent. */
16
16
  maxFrameBytes?: number;
17
+ /**
18
+ * Whether the organization allows auto mode (`allowed`, the default) or forbids it (`off`):
19
+ * `login` prints the matching line. Absent counts as allowed.
20
+ */
21
+ autoMode?: "allowed" | "off";
17
22
  }
18
23
  /** An error response of the kernel: `{ error: { code, message } }`. */
19
24
  export declare class ApiError extends Error {
package/dist/args.d.ts CHANGED
@@ -1,3 +1,4 @@
1
+ import type { SandboxMode } from "./state.js";
1
2
  export type DeviceMode = "os" | "docker";
2
3
  /** A parsed command line. */
3
4
  export type Command = {
@@ -29,7 +30,11 @@ export type Command = {
29
30
  action: "set" | "add" | "remove";
30
31
  key: string;
31
32
  value: string;
32
- /** `--yes`: confirms `set tier open` or `set isolation none` without asking. */
33
+ } | {
34
+ command: "mode";
35
+ /** Absent: print the current mode. */
36
+ mode?: SandboxMode;
37
+ /** `--yes`: confirms `mode auto` without asking. */
33
38
  yes?: true;
34
39
  } | {
35
40
  command: "service";
@@ -37,7 +42,7 @@ export type Command = {
37
42
  } | {
38
43
  command: "help";
39
44
  };
40
- export declare const USAGE = "Usage:\n capybara-device login --url <url> [--no-browser] [--dir <path>] [--mode os|docker]\n Connect this machine: approve the code in the browser\n capybara-device logout Forget the credential on this machine\n capybara-device status [--json] Show whether this machine is logged in\n capybara-device start Connect and serve the device\n capybara-device stop Stop the running program\n capybara-device drain [--wait] [--timeout <seconds>]\n Finish running commands, accept no new ones, then stop;\n --wait returns once it has stopped (default limit 600 s)\n capybara-device policy [show] Show the local policy\n capybara-device policy set <key> <value>\n Replace one field (applies at the next command)\n capybara-device policy set tier strict|dev|open|default [--yes]\n Choose the sandbox tier (default: follow the organization)\n capybara-device policy set isolation sandbox|none [--yes]\n none: at tier open, run commands without a sandbox (OS mode)\n capybara-device policy set localhost auto|allow\n allow: reach localhost at tier dev or open despite a local proxy\n capybara-device policy set remoteGrants owner|off\n Let the device owner widen the network from the web, or not\n capybara-device policy add|remove allowedDomains <host>\n Allow or stop allowing a domain (applies at the next command)\n capybara-device service install|uninstall\n Run at login as a user service\n capybara-device service status Report whether the login service is loaded and running";
45
+ export declare const USAGE = "Usage:\n capybara-device login --url <url> [--no-browser] [--dir <path>] [--mode os|docker]\n Connect this machine: approve the code in the browser\n capybara-device logout Forget the credential on this machine\n capybara-device status [--json] Show whether this machine is logged in\n capybara-device start Connect and serve the device\n capybara-device stop Stop the running program\n capybara-device drain [--wait] [--timeout <seconds>]\n Finish running commands, accept no new ones, then stop;\n --wait returns once it has stopped (default limit 600 s)\n capybara-device mode [auto|sandbox] [--yes]\n Show or choose how commands run: auto (as you on this\n machine, every command reviewed) or sandbox (applies at\n the next command; auto needs --yes or a y at the prompt)\n capybara-device policy [show] Show the local policy\n capybara-device policy set <key> <value>\n Replace one field (cpu, memoryMb, allowCredentials)\n capybara-device policy add|remove allowedDomains <host>\n Allow or stop allowing a domain in sandbox mode\n capybara-device policy add|remove allowCredentials <name>\n Allow or stop allowing a credential in sandbox mode\n capybara-device service install|uninstall\n Run at login as a user service\n capybara-device service status Report whether the login service is loaded and running";
41
46
  /** Thrown for a bad command line; the message is shown with the usage. */
42
47
  export declare class UsageError extends Error {
43
48
  }
package/dist/args.js CHANGED
@@ -9,19 +9,17 @@ export const USAGE = `Usage:
9
9
  capybara-device drain [--wait] [--timeout <seconds>]
10
10
  Finish running commands, accept no new ones, then stop;
11
11
  --wait returns once it has stopped (default limit 600 s)
12
+ capybara-device mode [auto|sandbox] [--yes]
13
+ Show or choose how commands run: auto (as you on this
14
+ machine, every command reviewed) or sandbox (applies at
15
+ the next command; auto needs --yes or a y at the prompt)
12
16
  capybara-device policy [show] Show the local policy
13
17
  capybara-device policy set <key> <value>
14
- Replace one field (applies at the next command)
15
- capybara-device policy set tier strict|dev|open|default [--yes]
16
- Choose the sandbox tier (default: follow the organization)
17
- capybara-device policy set isolation sandbox|none [--yes]
18
- none: at tier open, run commands without a sandbox (OS mode)
19
- capybara-device policy set localhost auto|allow
20
- allow: reach localhost at tier dev or open despite a local proxy
21
- capybara-device policy set remoteGrants owner|off
22
- Let the device owner widen the network from the web, or not
18
+ Replace one field (cpu, memoryMb, allowCredentials)
23
19
  capybara-device policy add|remove allowedDomains <host>
24
- Allow or stop allowing a domain (applies at the next command)
20
+ Allow or stop allowing a domain in sandbox mode
21
+ capybara-device policy add|remove allowCredentials <name>
22
+ Allow or stop allowing a credential in sandbox mode
25
23
  capybara-device service install|uninstall
26
24
  Run at login as a user service
27
25
  capybara-device service status Report whether the login service is loaded and running`;
@@ -102,20 +100,39 @@ export function parseCommandLine(argv) {
102
100
  return { command: "drain", wait: true, timeoutSeconds: seconds };
103
101
  }
104
102
  case "policy": {
105
- const { values, positionals } = parse(rest, { yes: { type: "boolean", short: "y" } });
106
- const yes = values.yes === true;
103
+ const { positionals } = parse(rest, {});
107
104
  const [action, key, value, ...extra] = positionals;
108
- if (!yes &&
109
- (action === undefined || (action === "show" && key === undefined && extra.length === 0))) {
105
+ if (action === undefined)
106
+ return { command: "policy", action: "show" };
107
+ if (action === "show" && key === undefined && extra.length === 0) {
110
108
  return { command: "policy", action: "show" };
111
109
  }
112
110
  if ((action === "set" || action === "add" || action === "remove") &&
113
111
  key !== undefined &&
114
112
  value !== undefined &&
115
113
  extra.length === 0) {
116
- return { command: "policy", action, key, value, ...(yes && { yes: true }) };
114
+ return { command: "policy", action, key, value };
115
+ }
116
+ throw new UsageError("usage: policy [show | set <key> <value> | add|remove <key> <value>]");
117
+ }
118
+ case "mode": {
119
+ const { values, positionals } = parse(rest, { yes: { type: "boolean", short: "y" } });
120
+ const [which, ...extra] = positionals;
121
+ if (extra.length > 0) {
122
+ throw new UsageError("usage: mode [auto|sandbox] [--yes]");
123
+ }
124
+ if (which !== undefined && which !== "auto" && which !== "sandbox") {
125
+ throw new UsageError("mode must be auto or sandbox");
126
+ }
127
+ const yes = values.yes === true;
128
+ if (yes && which === undefined) {
129
+ throw new UsageError("--yes needs a mode: mode auto|sandbox");
117
130
  }
118
- throw new UsageError("usage: policy [show | set <key> <value> [--yes] | add|remove <key> <value>]");
131
+ return {
132
+ command: "mode",
133
+ ...(which !== undefined && { mode: which }),
134
+ ...(yes && which !== undefined && { yes: true }),
135
+ };
119
136
  }
120
137
  case "service": {
121
138
  const { positionals } = parse(rest, {});
package/dist/cli.d.ts CHANGED
@@ -19,10 +19,12 @@ export interface CliEnv {
19
19
  /** Asks one question on the terminal and resolves the answer (default: node:readline). */
20
20
  ask?: (question: string) => Promise<string>;
21
21
  }
22
- /** Shown once when a Docker-mode device's policy says `isolation: none` (it is ignored there). */
23
- export declare const DOCKER_ISOLATION_IGNORED: string;
24
- /** Logged when commands start or stop running without a sandbox. */
25
- export declare const UNSANDBOXED_ON = "Commands on this device now run without a sandbox (isolation none).";
26
- export declare const UNSANDBOXED_OFF: string;
22
+ /**
23
+ * Logged when the local policy switches between auto and sandbox. It names the local choice, not
24
+ * the effective mode: the organization's ceiling still cuts it (a device whose org forbids auto
25
+ * runs in the sandbox even with this policy).
26
+ */
27
+ export declare const AUTO_MODE_ON = "This machine's local policy is auto mode; the deployment's ceiling applies.";
28
+ export declare const AUTO_MODE_OFF = "This machine's local policy is sandbox mode; commands still running in auto mode were stopped.";
27
29
  /** Runs one command line and returns the exit code. */
28
30
  export declare function runCli(argv: string[], io?: CliEnv): Promise<number>;
package/dist/cli.js CHANGED
@@ -3,7 +3,8 @@ import { parseCommandLine, USAGE, UsageError } from "./args.js";
3
3
  import { drain, drainAndWait } from "./commands/drain.js";
4
4
  import { login } from "./commands/login.js";
5
5
  import { logout } from "./commands/logout.js";
6
- import { confirmRisk, isolationRefusal, needsConfirmation, policyCommand, policyRisk, } from "./commands/policy.js";
6
+ import { modeCommand } from "./commands/mode.js";
7
+ import { policyCommand } from "./commands/policy.js";
7
8
  import { serviceCommand } from "./commands/service.js";
8
9
  import { start } from "./commands/start.js";
9
10
  import { status } from "./commands/status.js";
@@ -20,24 +21,22 @@ async function askOnTerminal(question) {
20
21
  rl.close();
21
22
  }
22
23
  }
23
- /** Shown once when a Docker-mode device's policy says `isolation: none` (it is ignored there). */
24
- export const DOCKER_ISOLATION_IGNORED = "policy.json says isolation none, which works in OS mode only: this device runs commands in " +
25
- "Docker mode, always in a container.";
26
- /** Logged when commands start or stop running without a sandbox. */
27
- export const UNSANDBOXED_ON = "Commands on this device now run without a sandbox (isolation none).";
28
- export const UNSANDBOXED_OFF = "Commands on this device run in the sandbox again; commands still running without one were " +
29
- "stopped.";
24
+ /**
25
+ * Logged when the local policy switches between auto and sandbox. It names the local choice, not
26
+ * the effective mode: the organization's ceiling still cuts it (a device whose org forbids auto
27
+ * runs in the sandbox even with this policy).
28
+ */
29
+ export const AUTO_MODE_ON = "This machine's local policy is auto mode; the deployment's ceiling applies.";
30
+ export const AUTO_MODE_OFF = "This machine's local policy is sandbox mode; commands still running in auto mode were stopped.";
30
31
  /**
31
32
  * The executor for the credential's mode; the program's state directory is unreadable to
32
- * sandboxed commands. OS mode serves a {@link SwitchingExecutor}: the OS sandbox, or no sandbox
33
- * when the owner set `isolation none` locally and the command's tier is `open` (spec §5.4).
33
+ * sandboxed commands. OS mode serves a {@link SwitchingExecutor}: the host (auto mode) or the OS
34
+ * sandbox (sandbox mode), chosen per command from the policy and the kernel's ceiling (spec §4.1).
34
35
  */
35
36
  function defaultCreateExecutor(stateDir, home, err) {
36
37
  return async (cred, store) => {
37
38
  const policy = () => store.current();
38
39
  if (cred.mode === "docker") {
39
- if (policy().isolation === "none")
40
- err(DOCKER_ISOLATION_IGNORED);
41
40
  const { createDockerExecutor } = await import("./exec/docker.js");
42
41
  return createDockerExecutor({
43
42
  dir: cred.dir,
@@ -57,7 +56,7 @@ function defaultCreateExecutor(stateDir, home, err) {
57
56
  home,
58
57
  denyRead: [stateDir],
59
58
  });
60
- return new SwitchingExecutor(sandboxed, new HostExecutor({ dir: cred.dir }), policy, (i) => err(i === "none" ? UNSANDBOXED_ON : UNSANDBOXED_OFF));
59
+ return new SwitchingExecutor(sandboxed, new HostExecutor({ dir: cred.dir }), policy, (mode) => err(mode === "auto" ? AUTO_MODE_ON : AUTO_MODE_OFF));
61
60
  };
62
61
  }
63
62
  /** Runs one command line and returns the exit code. */
@@ -118,25 +117,15 @@ export async function runCli(argv, io = {}) {
118
117
  ...(io.sleep && { sleep: io.sleep }),
119
118
  ...(cmd.timeoutSeconds !== undefined && { timeoutMs: cmd.timeoutSeconds * 1000 }),
120
119
  });
121
- case "policy": {
122
- // `set isolation none` that cannot apply (Docker mode, no local tier open): refused before
123
- // any risk text or question (policyCommand refuses it too, under the lock).
124
- const refusal = isolationRefusal(cmd, dir);
125
- if (refusal !== undefined) {
126
- err(refusal);
127
- return 2;
128
- }
129
- // `set tier open` / `set isolation none` without --yes: ask on a terminal (after printing
130
- // the risk text); elsewhere policyCommand refuses them.
131
- if (needsConfirmation(cmd) && (io.stdinIsTTY ?? process.stdin.isTTY === true)) {
132
- if (!(await confirmRisk(cmd, { out, ask: io.ask ?? askOnTerminal }))) {
133
- err(policyRisk(cmd)?.needsYes ?? "Nothing changed.");
134
- return 1;
135
- }
136
- return policyCommand(cmd, { stateDir: dir, out, err, confirmed: true });
137
- }
120
+ case "policy":
138
121
  return policyCommand(cmd, { stateDir: dir, out, err });
139
- }
122
+ case "mode":
123
+ return modeCommand(cmd, {
124
+ stateDir: dir,
125
+ out,
126
+ err,
127
+ ...((io.stdinIsTTY ?? process.stdin.isTTY === true) && { ask: io.ask ?? askOnTerminal }),
128
+ });
140
129
  case "service":
141
130
  return serviceCommand(cmd.action, {
142
131
  stateDir: dir,
package/dist/client.d.ts CHANGED
@@ -20,8 +20,6 @@ export interface ConnectOptions {
20
20
  random?: () => number;
21
21
  now?: () => number;
22
22
  programVersion?: string;
23
- /** The platform the policy summary describes (default: this process's; for tests). */
24
- platform?: NodeJS.Platform;
25
23
  /** A connection must stay up this long before the backoff resets (default 10 s). */
26
24
  stableMs?: number;
27
25
  /** Terminate a socket that heard nothing from the server for this long (default 60 s). */