@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.
- package/README.md +90 -179
- package/dist/api.d.ts +5 -0
- package/dist/args.d.ts +7 -2
- package/dist/args.js +33 -16
- package/dist/cli.d.ts +7 -5
- package/dist/cli.js +20 -31
- package/dist/client.d.ts +0 -2
- package/dist/client.js +9 -10
- package/dist/command-log.d.ts +3 -5
- package/dist/commands/login.js +55 -1
- package/dist/commands/mode.d.ts +52 -0
- package/dist/commands/mode.js +108 -0
- package/dist/commands/policy.d.ts +11 -65
- package/dist/commands/policy.js +62 -249
- package/dist/commands/start.d.ts +2 -2
- package/dist/commands/start.js +14 -6
- package/dist/commands/status.js +11 -3
- package/dist/exec/docker.d.ts +22 -30
- package/dist/exec/docker.js +81 -69
- package/dist/exec/fs-helper.d.ts +13 -8
- package/dist/exec/fs-helper.js +30 -12
- package/dist/exec/host.d.ts +8 -8
- package/dist/exec/host.js +9 -9
- package/dist/exec/os.d.ts +36 -69
- package/dist/exec/os.js +65 -159
- package/dist/exec/sandbox-messages.d.ts +14 -0
- package/dist/exec/sandbox-messages.js +21 -0
- package/dist/exec/shared.d.ts +21 -36
- package/dist/exec/shared.js +30 -164
- package/dist/exec/switch.d.ts +38 -55
- package/dist/exec/switch.js +58 -108
- package/dist/exec/types.d.ts +8 -18
- package/dist/index.d.ts +1 -1
- package/dist/network.d.ts +7 -7
- package/dist/network.js +11 -18
- package/dist/policy-store.d.ts +7 -8
- package/dist/policy-store.js +11 -15
- package/dist/policy.d.ts +25 -100
- package/dist/policy.js +44 -146
- package/dist/server-ops.d.ts +15 -35
- package/dist/server-ops.js +36 -117
- package/dist/state.d.ts +15 -16
- package/dist/state.js +38 -36
- package/package.json +2 -2
- package/dist/proxy-guard.d.ts +0 -58
- 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,
|
|
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]
|
|
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
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
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
|
|
78
|
-
capybara-device
|
|
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
|
-
|
|
84
|
-
|
|
85
|
-
|
|
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
|
|
115
|
-
|
|
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
|
-
|
|
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
|
-
|
|
151
|
-
|
|
152
|
-
|
|
153
|
-
|
|
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
|
-
|
|
227
|
-
|
|
228
|
-
|
|
229
|
-
|
|
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
|
-
|
|
233
|
-
|
|
234
|
-
|
|
235
|
-
|
|
236
|
-
|
|
237
|
-
|
|
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
|
-
|
|
242
|
-
|
|
243
|
-
|
|
244
|
-
|
|
245
|
-
|
|
246
|
-
|
|
247
|
-
|
|
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
|
|
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
|
-
|
|
268
|
-
|
|
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
|
|
283
|
-
|
|
284
|
-
|
|
285
|
-
|
|
286
|
-
|
|
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
|
|
298
|
-
|
|
299
|
-
|
|
300
|
-
|
|
301
|
-
|
|
302
|
-
|
|
303
|
-
|
|
304
|
-
|
|
305
|
-
|
|
306
|
-
|
|
307
|
-
|
|
308
|
-
|
|
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
|
-
|
|
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
|
|
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 (
|
|
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
|
|
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 {
|
|
106
|
-
const yes = values.yes === true;
|
|
103
|
+
const { positionals } = parse(rest, {});
|
|
107
104
|
const [action, key, value, ...extra] = positionals;
|
|
108
|
-
if (
|
|
109
|
-
|
|
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
|
|
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
|
-
|
|
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
|
-
/**
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
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 {
|
|
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
|
-
/**
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
export const
|
|
29
|
-
|
|
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
|
|
33
|
-
*
|
|
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, (
|
|
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). */
|