@capybara-hq/device 0.1.0-rc.14 → 0.1.0-rc.16
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 +101 -157
- package/dist/api.d.ts +2 -2
- package/dist/args.d.ts +2 -8
- package/dist/args.js +2 -25
- package/dist/cli.d.ts +2 -11
- package/dist/cli.js +6 -61
- package/dist/client.d.ts +8 -45
- package/dist/client.js +25 -424
- package/dist/command-log.d.ts +14 -4
- package/dist/command-log.js +37 -1
- package/dist/commands/ceiling.d.ts +0 -2
- package/dist/commands/ceiling.js +3 -4
- package/dist/commands/login.d.ts +25 -1
- package/dist/commands/login.js +75 -61
- package/dist/commands/policy.d.ts +6 -8
- package/dist/commands/policy.js +30 -49
- package/dist/commands/start.d.ts +2 -17
- package/dist/commands/start.js +13 -53
- package/dist/exec/docker-operations.d.ts +2 -2
- package/dist/exec/docker-operations.js +4 -2
- package/dist/exec/docker.d.ts +37 -122
- package/dist/exec/docker.js +72 -717
- package/dist/exec/instance-binding.d.ts +4 -4
- package/dist/exec/linux-agent.js +30 -0
- package/dist/exec/linux-operation-backend.d.ts +5 -0
- package/dist/exec/linux-operation-backend.js +3 -1
- package/dist/exec/linux-operation-worker.d.ts +9 -0
- package/dist/exec/linux-operation-worker.js +11 -2
- package/dist/exec/mac-read-policy.d.ts +58 -0
- package/dist/exec/mac-read-policy.js +104 -0
- package/dist/exec/mac-self-check.d.ts +6 -3
- package/dist/exec/mac-self-check.js +28 -5
- package/dist/exec/operation-worker.d.ts +21 -2
- package/dist/exec/operation-worker.js +164 -43
- package/dist/exec/sandbox-check.d.ts +10 -0
- package/dist/exec/sandbox-check.js +18 -0
- package/dist/exec/sandbox-messages.d.ts +3 -11
- package/dist/exec/sandbox-messages.js +3 -18
- package/dist/exec/shared.d.ts +24 -47
- package/dist/exec/shared.js +53 -165
- package/dist/exec/types.d.ts +2 -66
- package/dist/exec/types.js +1 -1
- package/dist/node_modules/@anthropic-ai/sandbox-runtime/CAPYBARA-MODIFICATIONS.patch +71 -12
- package/dist/node_modules/@anthropic-ai/sandbox-runtime/dist/sandbox/macos-sandbox-utils.js +18 -4
- package/dist/node_modules/@anthropic-ai/sandbox-runtime/dist/sandbox/sandbox-config.js +6 -0
- package/dist/node_modules/@anthropic-ai/sandbox-runtime/dist/sandbox/sandbox-manager.js +4 -0
- package/dist/node_modules/@capybara-hq/plugin-sdk/agent-docs/concepts.md +9 -4
- package/dist/node_modules/@capybara-hq/plugin-sdk/agent-docs/extension-points/channel.md +1 -1
- package/dist/node_modules/@capybara-hq/plugin-sdk/agent-docs/extension-points/file-preview.md +2 -0
- package/dist/node_modules/@capybara-hq/plugin-sdk/agent-docs/extension-points/sandbox.md +1 -1
- package/dist/node_modules/@capybara-hq/plugin-sdk/agent-docs/plugin-format.md +1 -1
- package/dist/node_modules/@capybara-hq/plugin-sdk/dist/cards.d.ts +11 -0
- package/dist/node_modules/@capybara-hq/plugin-sdk/dist/cards.js +1 -1
- package/dist/node_modules/@capybara-hq/plugin-sdk/dist/channel.d.ts +37 -0
- package/dist/node_modules/@capybara-hq/plugin-sdk/dist/ctx.d.ts +47 -3
- package/dist/node_modules/@capybara-hq/plugin-sdk/dist/device-denied-paths.d.ts +14 -0
- package/dist/node_modules/@capybara-hq/plugin-sdk/dist/device-denied-paths.js +41 -0
- package/dist/node_modules/@capybara-hq/plugin-sdk/dist/device-protocol.d.ts +140 -20
- package/dist/node_modules/@capybara-hq/plugin-sdk/dist/device-protocol.js +419 -14
- package/dist/node_modules/@capybara-hq/plugin-sdk/dist/file-preview.d.ts +22 -5
- package/dist/node_modules/@capybara-hq/plugin-sdk/dist/hooks.d.ts +77 -13
- package/dist/node_modules/@capybara-hq/plugin-sdk/dist/http-access.d.ts +10 -0
- package/dist/node_modules/@capybara-hq/plugin-sdk/dist/index.d.ts +2 -2
- package/dist/node_modules/@capybara-hq/plugin-sdk/dist/index.js +2 -3
- package/dist/node_modules/@capybara-hq/plugin-sdk/dist/model.d.ts +89 -5
- package/dist/node_modules/@capybara-hq/plugin-sdk/dist/model.js +103 -0
- package/dist/node_modules/@capybara-hq/plugin-sdk/dist/permissions.d.ts +3 -2
- package/dist/node_modules/@capybara-hq/plugin-sdk/dist/permissions.js +2 -2
- package/dist/node_modules/@capybara-hq/plugin-sdk/dist/sandbox-operation.d.ts +4 -0
- package/dist/node_modules/@capybara-hq/plugin-sdk/dist/ui-parts.d.ts +1 -1
- package/dist/node_modules/@capybara-hq/plugin-sdk/dist/ui-parts.js +11 -0
- package/dist/node_modules/@capybara-hq/plugin-sdk/dist/ui.d.ts +25 -6
- package/dist/node_modules/@capybara-hq/plugin-sdk/package.json +1 -1
- package/dist/owner-report.d.ts +2 -2
- package/dist/owner-report.js +2 -2
- package/dist/policy-store.d.ts +6 -10
- package/dist/policy-store.js +9 -23
- package/dist/policy.d.ts +3 -32
- package/dist/policy.js +4 -74
- package/dist/runtime-manifest.json +1 -1
- package/dist/server-ops.d.ts +18 -46
- package/dist/server-ops.js +134 -269
- package/dist/staged-connect.js +44 -7
- package/dist/staged-device.d.ts +4 -4
- package/dist/staged-device.js +3 -0
- package/dist/staged-session.d.ts +5 -5
- package/dist/staged-session.js +4 -4
- package/dist/state.js +3 -2
- package/package.json +2 -2
- package/dist/commands/mode.d.ts +0 -69
- package/dist/commands/mode.js +0 -133
- package/dist/exec/fs-helper.d.ts +0 -21
- package/dist/exec/fs-helper.js +0 -171
- package/dist/exec/host.d.ts +0 -61
- package/dist/exec/host.js +0 -203
- package/dist/exec/listing.d.ts +0 -35
- package/dist/exec/listing.js +0 -157
- package/dist/exec/os.d.ts +0 -162
- package/dist/exec/os.js +0 -616
- package/dist/exec/procs.d.ts +0 -11
- package/dist/exec/procs.js +0 -67
- package/dist/exec/reap.d.ts +0 -41
- package/dist/exec/reap.js +0 -89
- package/dist/exec/switch.d.ts +0 -107
- package/dist/exec/switch.js +0 -204
- package/dist/network.d.ts +0 -45
- package/dist/network.js +0 -154
- package/dist/node_modules/@capybara-hq/plugin-sdk/dist/device-protocol-v3.d.ts +0 -117
- package/dist/node_modules/@capybara-hq/plugin-sdk/dist/device-protocol-v3.js +0 -409
package/README.md
CHANGED
|
@@ -2,8 +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
|
|
6
|
-
|
|
5
|
+
machine while the program is online, confined by the conversation's permission profile and by this
|
|
6
|
+
machine's owner ceiling.
|
|
7
7
|
|
|
8
8
|
Runs on macOS and Linux. Native Windows is refused: use WSL (then it is a Linux machine) or Docker
|
|
9
9
|
mode inside WSL. Node 22.12 or newer.
|
|
@@ -54,183 +54,129 @@ the device page says so. To start afresh, run `capybara-device logout` and then
|
|
|
54
54
|
and the platform rebuilds the device on its next use.
|
|
55
55
|
|
|
56
56
|
Commands: `login --url <url> [--no-browser] [--dir <path>] [--mode os|docker]`, `logout`,
|
|
57
|
-
`status [--json]
|
|
58
|
-
`drain [--wait] [--timeout <seconds>]`,
|
|
59
|
-
`
|
|
57
|
+
`status [--json]`, `start`, `stop`,
|
|
58
|
+
`drain [--wait] [--timeout <seconds>]`,
|
|
59
|
+
`ceiling show | ceiling set --full-access allow|deny --project-reach workspace|os-user [--yes]`,
|
|
60
|
+
`policy [show | set <key> <value> | add|remove <key> <value>]` and
|
|
60
61
|
`service install|uninstall|start|stop|restart|status`.
|
|
61
|
-
`
|
|
62
|
-
prints the risk text and asks for confirmation unless `--yes` is given.
|
|
62
|
+
`ceiling set` is the only way to change the owner ceiling (`policy set mode` points there); a
|
|
63
|
+
widening prints the risk text and asks for confirmation unless `--yes` is given. The old daily
|
|
64
|
+
`mode auto|sandbox` command is gone.
|
|
63
65
|
|
|
64
66
|
State lives in `$XDG_CONFIG_HOME/capybara-device` (default `~/.config/capybara-device`):
|
|
65
67
|
`credential.json` (mode 0600; the program refuses a file other users can read; it also holds the
|
|
66
68
|
deployment's reconnect grace and frame limit: a result larger than the frame limit is answered
|
|
67
69
|
with an error instead) and `policy.json` (a file with wrong field types stops `start` with an
|
|
68
70
|
error naming it; once running, the program re-reads the file when it changes, and a broken edit
|
|
69
|
-
|
|
71
|
+
is no authority: operations and owner reports are refused with the reason until it is fixed, never
|
|
72
|
+
served from a policy read earlier). Changes made with `capybara-device policy` take
|
|
70
73
|
`policy.json.lock`, so two writers never lose an update; keys this version does not know are kept.
|
|
71
74
|
The working directory (default `~/capybara-device/<deviceId>`) holds `workspace/`, `skills/`
|
|
72
75
|
and `tmp/`.
|
|
73
76
|
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
allowlist also admits (with an empty list, no network at all). Commands keep their package
|
|
91
|
-
caches in the workspace like any other file. The hello still reports your home directory, but
|
|
92
|
-
the deployment's directory listing and project scan cover the workspace only.
|
|
93
|
-
|
|
94
|
-
If the OS sandbox is unavailable on the machine (an unsupported platform or missing dependencies,
|
|
95
|
-
such as `bwrap` / `socat` on Linux), the device still starts and serves: auto mode works, and every
|
|
96
|
-
sandbox-mode command is refused with the reason and how to fix it (`capybara-device mode auto`, or
|
|
97
|
-
install the dependencies and restart). `capybara-device mode sandbox` is refused on such a machine
|
|
98
|
-
and the policy stays in auto; nothing ever runs unsandboxed by falling back. File operations
|
|
99
|
-
(read, write, stat) there follow only a fresh command decision (the latest command, within a
|
|
100
|
-
minute): without one they are refused, never served on the host. `login` into an organization that
|
|
101
|
-
forbids auto mode checks the OS sandbox first: when it is unavailable, no sandbox policy is written
|
|
102
|
-
and the login line says what to install (or to log in with `--mode docker`).
|
|
77
|
+
## Permissions
|
|
78
|
+
|
|
79
|
+
Every operation the deployment sends carries a scope: the conversation's permission profile
|
|
80
|
+
(`request-approval` and `approve-for-me` are restricted, `full-access` is Full access), the roots
|
|
81
|
+
it may read and write, and its network. The device checks each one against the **owner ceiling**
|
|
82
|
+
in `policy.json`, which only you change, on this machine:
|
|
83
|
+
|
|
84
|
+
- **Full access** `allow|deny`: whether a conversation set to Full access may run here. Full access
|
|
85
|
+
runs as you (in Docker mode, as the container's user): your files, credentials and network; the
|
|
86
|
+
deployment reviews every command, but that review is the boundary, not a sandbox.
|
|
87
|
+
- **Project reach** `workspace|os-user`: whether restricted work and project browsing may read
|
|
88
|
+
projects outside the device's `workspace/`.
|
|
89
|
+
|
|
90
|
+
A new login starts restricted (`deny`, `workspace`). `login` prints the ceiling and how to widen
|
|
91
|
+
it; a widening prints the risk text and needs `--yes` or a `y` at the prompt. The organization and
|
|
92
|
+
the platform can switch Full access off on their side; the narrowest setting wins.
|
|
103
93
|
|
|
104
94
|
```bash
|
|
105
|
-
capybara-device
|
|
106
|
-
capybara-device
|
|
107
|
-
capybara-device
|
|
108
|
-
capybara-device policy add allowedDomains files.slack.com
|
|
95
|
+
capybara-device ceiling show # the owner ceiling, network baseline, revision
|
|
96
|
+
capybara-device ceiling set --full-access deny --project-reach workspace # narrow
|
|
97
|
+
capybara-device ceiling set --full-access allow --project-reach os-user --yes # widen
|
|
98
|
+
capybara-device policy add allowedDomains files.slack.com
|
|
109
99
|
capybara-device policy remove allowedDomains files.slack.com
|
|
110
100
|
capybara-device policy show
|
|
111
101
|
```
|
|
112
102
|
|
|
113
|
-
|
|
114
|
-
sandbox
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
|
|
134
|
-
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
- api.foo.com:443: not in the organization's network allowlist. Only an organization admin can add it.
|
|
140
|
-
- 10.0.0.5:22: a private or local address; commands can never reach it.
|
|
141
|
-
```
|
|
142
|
-
|
|
143
|
-
The trailer is part of the command's output, so the agent reads it too. It comes after the
|
|
144
|
-
output the deployment asked for (`maxOutputBytes`), so stderr can exceed that cap by the trailer's
|
|
145
|
-
lines (at most 21).
|
|
146
|
-
|
|
147
|
-
In OS mode each command's result also carries the refused hosts and their layers, so the
|
|
148
|
-
deployment can ask the device owner on the spot (the device announces this in its hello, together
|
|
149
|
-
with a summary of its local policy: the owner's `mode`, never cut by an exec's ceiling (the
|
|
150
|
-
deployment applies its own), and the sandbox-mode `allowedDomains`).
|
|
151
|
-
|
|
152
|
-
### Sandbox mode details
|
|
153
|
-
|
|
154
|
-
In sandbox mode commands keep `HOME` = `workspace/`, writes stay inside the device directory, the
|
|
155
|
-
secret paths stay unreadable, and the network proxy refuses loopback, private addresses and
|
|
156
|
-
internal names as destinations. The device's `allowedDomains` are intersected with the
|
|
157
|
-
organization's allowlist; a host either list refuses is reported as described above.
|
|
158
|
-
|
|
159
|
-
Version managers (asdf, nvm, pyenv, mise, …) find their data under the real home, read only, so
|
|
160
|
-
their shims work with `HOME` = the workspace. Git can read a repository, but `.git/config` and
|
|
161
|
-
`.git/hooks` stay unwritable: a hook or `core.sshCommand` a command wrote would run when you later
|
|
162
|
-
run git there. When you want git to write (init, clone, remotes) or commands to use your
|
|
163
|
-
credentials, use auto mode.
|
|
164
|
-
|
|
165
|
-
### The auto mode risk
|
|
166
|
-
|
|
167
|
-
In auto mode agent commands have your full capability. The deployment reviews every command and
|
|
168
|
-
blocks or asks about the dangerous ones, but that review is the boundary, not an OS sandbox: prompt
|
|
169
|
-
injection can still make an agent attempt to delete files or send your credentials away. Commands
|
|
170
|
-
can also read this program's own credential (`credential.json`): if you suspect misuse, run
|
|
171
|
-
`capybara-device logout` and log in again, which revokes it. Keep auto mode to your own development
|
|
172
|
-
machine, with agents and material you trust; `capybara-device mode sandbox` turns the sandbox back
|
|
173
|
-
on.
|
|
103
|
+
**Restricted work** runs each operation in its own sandbox: macOS uses
|
|
104
|
+
`@anthropic-ai/sandbox-runtime` (Seatbelt); Linux and Docker mode use the SDK's restricted Linux
|
|
105
|
+
runtime (Landlock plus a seccomp broker). Writes stay in the scope's roots; reads stay in them too,
|
|
106
|
+
plus the system and developer tool directories (on macOS `/System`, `/usr`, `/bin`, `/sbin`,
|
|
107
|
+
`/private/etc`, Homebrew, Xcode and the Command Line Tools, `/Library/Apple`, `/Library/Frameworks`,
|
|
108
|
+
installed JDKs) and the data of the version managers your home uses, read only; other files of the
|
|
109
|
+
machine, such as the rest of your home, are not readable. Secret paths (`~/.ssh`, cloud CLI
|
|
110
|
+
credentials, `~/.netrc`, `~/.gnupg`, browser profiles, this program's state directory) stay
|
|
111
|
+
unreadable even inside those, and the network reaches only hosts in the local `allowedDomains` that
|
|
112
|
+
the organization's allowlist also admits (plus a run's or a task's grants, within that allowlist),
|
|
113
|
+
through a proxy that refuses loopback, private addresses and internal names. Restricted work also
|
|
114
|
+
follows one write policy (below). On macOS each restricted command also gets its own empty temporary
|
|
115
|
+
directory (`TMPDIR`, `TMP`, `TEMP`), removed when the command ends; `mktemp` without a template
|
|
116
|
+
writes to the user's shared temporary directory instead, which stays closed, so give it one (`mktemp
|
|
117
|
+
"$TMPDIR/x.XXXXXX"`). On Linux `TMPDIR` is the first write root. When the restricted runtime is
|
|
118
|
+
unavailable here, the device reports it to the deployment and refuses restricted work with the
|
|
119
|
+
reason; nothing falls back to running unconfined.
|
|
120
|
+
|
|
121
|
+
A change to the ceiling or the policy applies at the next operation without a restart, and running
|
|
122
|
+
work the narrower ceiling no longer allows is stopped. `add` and `remove` work on `allowedDomains`
|
|
123
|
+
and `allowCredentials`; every domain must be a lowercase host name (optionally `*.` for
|
|
124
|
+
subdomains, never the apex), never an IP address or an internal name.
|
|
125
|
+
|
|
126
|
+
In OS mode the hello reports your home directory (the base for project paths), and browsing
|
|
127
|
+
follows the project reach. The device tracks every process an operation starts and stops it
|
|
128
|
+
exactly when the operation ends, is cancelled or its task is stopped; it never kills by guessing.
|
|
174
129
|
|
|
175
130
|
### Changes from the deployment
|
|
176
131
|
|
|
177
132
|
The deployment changes the local policy only by narrowing it: it may add or remove
|
|
178
|
-
`allowedDomains` (an approval adds an exact host; the device page may add a `*.` wildcard) and
|
|
179
|
-
|
|
180
|
-
|
|
181
|
-
|
|
182
|
-
|
|
183
|
-
|
|
133
|
+
`allowedDomains` (an approval adds an exact host; the device page may add a `*.` wildcard) and
|
|
134
|
+
narrow the owner ceiling. It can never widen it. Every host is validated like a local one, and the
|
|
135
|
+
change is written under `policy.json.lock`.
|
|
136
|
+
|
|
137
|
+
### The command log
|
|
138
|
+
|
|
139
|
+
`commands.log` (next to `policy.json`, mode 0600, rotated to `commands.log.1` at 10 MiB) records
|
|
140
|
+
one line per command (exec or background start: tag, account, conversation, `restricted` or
|
|
141
|
+
`full`, exit code, the grants' source) and every policy change, from the deployment or the CLI,
|
|
142
|
+
refused or failed ones included. It never holds a command's text, its environment or file contents.
|
|
184
143
|
|
|
185
144
|
```text
|
|
145
|
+
{"op":"exec","tag":"t1","actor":{"accountId":"acc_123","conversationId":"conv_1"},"exitCode":0,"isolation":"restricted",...}
|
|
186
146
|
{"op":"policy","detail":"policy add files.slack.com by Ada Lovelace (acc_123) via web, approval apr_456",...}
|
|
187
|
-
{"op":"policy","detail":"
|
|
188
|
-
{"op":"exec","detail":"grants run run_789 by acc_123: files.slack.com",...}
|
|
147
|
+
{"op":"policy","detail":"ceiling set fullAccess allow, projectReach os-user by ada via cli",...}
|
|
189
148
|
```
|
|
190
149
|
|
|
191
|
-
A run's or a scheduled task's network grants apply in sandbox mode only, within the organization's
|
|
192
|
-
allowlist; auto mode has the machine's own network, so grants do nothing there.
|
|
193
|
-
|
|
194
|
-
Limit to know: commands of one device run as the same user, and the sandbox runtime ties a
|
|
195
|
-
command's list (including its run grants) to the proxy credentials it hands that command. Another
|
|
196
|
-
command running at the same time on the same device could reuse them, so a run's grants may be
|
|
197
|
-
usable by a concurrent command of another run on that device: same owner, same device.
|
|
198
|
-
|
|
199
150
|
Limits to know: the platform's `Grep` tool assumes GNU grep, so on macOS (BSD grep) in OS mode some
|
|
200
|
-
Grep options behave differently or fail.
|
|
151
|
+
Grep options behave differently or fail. In OS mode the `cpu` and `memoryMb` ceilings are not
|
|
152
|
+
enforced yet, and `allowCredentials` is ignored (Full access already has your credentials,
|
|
153
|
+
restricted work gets none).
|
|
201
154
|
|
|
202
|
-
|
|
203
|
-
|
|
204
|
-
|
|
205
|
-
|
|
206
|
-
|
|
207
|
-
|
|
155
|
+
### Upgrading from a protocol 2 program
|
|
156
|
+
|
|
157
|
+
The old program's auto mode ran commands as you, outside any tracking this version has: processes
|
|
158
|
+
they left running survive the upgrade. Restart the machine, or kill such leftovers from before the
|
|
159
|
+
upgrade yourself; this version never searches for them. In Docker mode the old container is
|
|
160
|
+
recreated at the first operation, which ends whatever it still ran.
|
|
208
161
|
|
|
209
162
|
## Docker mode
|
|
210
163
|
|
|
211
|
-
`login --mode docker` runs every
|
|
164
|
+
`login --mode docker` runs every operation in one container per device
|
|
212
165
|
(`capybara-device-<deviceId>`, started on first use from
|
|
213
|
-
`ghcr.io/capybara-hq/capybara-sandbox:<tag>`, the sandbox image of this release). On Linux
|
|
214
|
-
|
|
215
|
-
|
|
216
|
-
at `/workspace`, `/skills` and `/tmp`; the
|
|
217
|
-
|
|
218
|
-
`
|
|
219
|
-
|
|
220
|
-
|
|
221
|
-
|
|
222
|
-
|
|
223
|
-
|
|
224
|
-
|
|
225
|
-
|
|
226
|
-
|
|
227
|
-
|
|
228
|
-
In both, the hello reports your home directory, while the deployment's directory listing and
|
|
229
|
-
project scan cover the container's `/workspace` only (directory entries, never file contents).
|
|
230
|
-
|
|
231
|
-
The network is switched between the two without recreating the container (a container disconnected
|
|
232
|
-
from every network has no network, the same as `--network none`). Use OS mode's sandbox when you
|
|
233
|
-
need to allow single domains.
|
|
166
|
+
`ghcr.io/capybara-hq/capybara-sandbox:<tag>`, the sandbox image of this release). On Linux it runs
|
|
167
|
+
as your own uid:gid, so it can write the mounted directories you own (a root user falls back to the
|
|
168
|
+
image's `sandbox` user, uid 1000); on macOS as the image's `sandbox` user. `<dir>/workspace`,
|
|
169
|
+
`<dir>/skills` (read only) and `<dir>/tmp` are mounted at `/workspace`, `/skills` and `/tmp`; the
|
|
170
|
+
container has a read-only root file system, a pids limit of 1024, `--cap-drop ALL`,
|
|
171
|
+
`no-new-privileges`, and the policy's `cpu` and `memoryMb` as `--cpus`, `--memory` and an equal
|
|
172
|
+
`--memory-swap`.
|
|
173
|
+
|
|
174
|
+
The container is always on Docker's default bridge: Full access has the container's whole network.
|
|
175
|
+
Restricted work inside it is confined by the Linux launcher (Landlock, the seccomp broker and the
|
|
176
|
+
proxy with the allowlist above), on the container's paths. The hello reports no home directory, and
|
|
177
|
+
browsing covers the container's `/workspace` only. The container is reused while its mounts, flags
|
|
178
|
+
and format match, and recreated, once no operation holds it, when they differ or when it lost its
|
|
179
|
+
bridge; it stays running (idle) between starts.
|
|
234
180
|
|
|
235
181
|
## Running at login
|
|
236
182
|
|
|
@@ -270,14 +216,13 @@ agent out and waits (up to 10 s) until launchd has let it go, because `launchctl
|
|
|
270
216
|
before that; a `bootstrap` that still fails with error 5 (Input/output error) is retried a few
|
|
271
217
|
times. On Linux, installing again restarts the unit so the new file applies.
|
|
272
218
|
|
|
273
|
-
##
|
|
219
|
+
## Operation backend
|
|
274
220
|
|
|
275
|
-
The
|
|
276
|
-
|
|
277
|
-
|
|
278
|
-
|
|
279
|
-
|
|
280
|
-
broker), reported unavailable wherever that runtime's probe fails; there is no Full fallback.
|
|
221
|
+
The program speaks device protocol 3 only. It binds each instance generation the deployment creates
|
|
222
|
+
to a verified, sealed runtime and reports restricted support only once a self-check on that runtime
|
|
223
|
+
passed (macOS: a write in its root goes through, while a write outside it, reads of a denied secret
|
|
224
|
+
and of an ordinary file it was never granted, and a local connection are refused) or the runtime's
|
|
225
|
+
probe passed (Linux, Docker); there is no Full fallback for restricted work.
|
|
281
226
|
|
|
282
227
|
Each restricted operation has its own immutable sandbox-runtime process and proxy lifetime.
|
|
283
228
|
Native methods use the SDK's hash-checked Python helper and pinned directory descriptors, with a
|
|
@@ -299,7 +244,6 @@ The private supervisor consumes operation IDs durably before launch, records tru
|
|
|
299
244
|
identities, bounds output tails to 65,536 bytes and preserves cancellation and unknown outcomes.
|
|
300
245
|
A restarted supervisor never signals a recorded PID or relaunches a consumed operation. Cleanup
|
|
301
246
|
covers its registered execution groups; it does not discover arbitrary unregistered detached
|
|
302
|
-
processes. Its owner-policy watcher runs while it owns live work independently of connection state
|
|
303
|
-
|
|
304
|
-
that live integration before enabling this backend. Journals fail closed when their bounded
|
|
247
|
+
processes. Its owner-policy watcher runs while it owns live work independently of connection state,
|
|
248
|
+
and every successful policy write reconciles live work at once. Journals fail closed when their bounded
|
|
305
249
|
capacity is exhausted; terminal results remain subject to their reference retention deadlines.
|
package/dist/api.d.ts
CHANGED
|
@@ -15,10 +15,10 @@ export interface TokenResponse {
|
|
|
15
15
|
/** The program uses 16 MiB when it is absent. */
|
|
16
16
|
maxFrameBytes?: number;
|
|
17
17
|
/**
|
|
18
|
-
* Whether the organization
|
|
18
|
+
* Whether the platform and the organization allow Full access (`allowed`) or not (`off`):
|
|
19
19
|
* `login` prints the matching line. Absent counts as allowed.
|
|
20
20
|
*/
|
|
21
|
-
|
|
21
|
+
fullAccess?: "allowed" | "off";
|
|
22
22
|
}
|
|
23
23
|
/** An error response of the kernel: `{ error: { code, message } }`. */
|
|
24
24
|
export declare class ApiError extends Error {
|
package/dist/args.d.ts
CHANGED
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
import type { RestrictedProjectReach
|
|
1
|
+
import type { RestrictedProjectReach } from "./state.js";
|
|
2
2
|
export type DeviceMode = "os" | "docker";
|
|
3
3
|
/** A parsed command line. */
|
|
4
4
|
export type Command = {
|
|
@@ -30,12 +30,6 @@ export type Command = {
|
|
|
30
30
|
action: "set" | "add" | "remove";
|
|
31
31
|
key: string;
|
|
32
32
|
value: string;
|
|
33
|
-
} | {
|
|
34
|
-
command: "mode";
|
|
35
|
-
/** Absent: print the current mode. */
|
|
36
|
-
mode?: SandboxMode;
|
|
37
|
-
/** `--yes`: confirms `mode auto` without asking. */
|
|
38
|
-
yes?: true;
|
|
39
33
|
} | {
|
|
40
34
|
command: "ceiling";
|
|
41
35
|
action: "show";
|
|
@@ -52,7 +46,7 @@ export type Command = {
|
|
|
52
46
|
} | {
|
|
53
47
|
command: "help";
|
|
54
48
|
};
|
|
55
|
-
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
|
|
49
|
+
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 ceiling show Show this machine's owner ceiling (Full access, project reach)\n capybara-device ceiling set --full-access allow|deny --project-reach workspace|os-user [--yes]\n Set the owner ceiling; widening 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 for restricted work\n capybara-device policy add|remove allowCredentials <name>\n Allow or stop allowing a credential for restricted work\n capybara-device service install|uninstall\n Run at login as a user service, or remove it\n capybara-device service start|stop|restart\n Start, stop or restart the login service\n capybara-device service status Report whether the login service is loaded, what is running,\n and whether it is older than the installed program";
|
|
56
50
|
/** Thrown for a bad command line; the message is shown with the usage. */
|
|
57
51
|
export declare class UsageError extends Error {
|
|
58
52
|
}
|
package/dist/args.js
CHANGED
|
@@ -9,10 +9,6 @@ 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)
|
|
16
12
|
capybara-device ceiling show Show this machine's owner ceiling (Full access, project reach)
|
|
17
13
|
capybara-device ceiling set --full-access allow|deny --project-reach workspace|os-user [--yes]
|
|
18
14
|
Set the owner ceiling; widening needs --yes or a y at the prompt
|
|
@@ -20,9 +16,9 @@ export const USAGE = `Usage:
|
|
|
20
16
|
capybara-device policy set <key> <value>
|
|
21
17
|
Replace one field (cpu, memoryMb, allowCredentials)
|
|
22
18
|
capybara-device policy add|remove allowedDomains <host>
|
|
23
|
-
Allow or stop allowing a domain
|
|
19
|
+
Allow or stop allowing a domain for restricted work
|
|
24
20
|
capybara-device policy add|remove allowCredentials <name>
|
|
25
|
-
Allow or stop allowing a credential
|
|
21
|
+
Allow or stop allowing a credential for restricted work
|
|
26
22
|
capybara-device service install|uninstall
|
|
27
23
|
Run at login as a user service, or remove it
|
|
28
24
|
capybara-device service start|stop|restart
|
|
@@ -121,25 +117,6 @@ export function parseCommandLine(argv) {
|
|
|
121
117
|
}
|
|
122
118
|
throw new UsageError("usage: policy [show | set <key> <value> | add|remove <key> <value>]");
|
|
123
119
|
}
|
|
124
|
-
case "mode": {
|
|
125
|
-
const { values, positionals } = parse(rest, { yes: { type: "boolean", short: "y" } });
|
|
126
|
-
const [which, ...extra] = positionals;
|
|
127
|
-
if (extra.length > 0) {
|
|
128
|
-
throw new UsageError("usage: mode [auto|sandbox] [--yes]");
|
|
129
|
-
}
|
|
130
|
-
if (which !== undefined && which !== "auto" && which !== "sandbox") {
|
|
131
|
-
throw new UsageError("mode must be auto or sandbox");
|
|
132
|
-
}
|
|
133
|
-
const yes = values.yes === true;
|
|
134
|
-
if (yes && which === undefined) {
|
|
135
|
-
throw new UsageError("--yes needs a mode: mode auto|sandbox");
|
|
136
|
-
}
|
|
137
|
-
return {
|
|
138
|
-
command: "mode",
|
|
139
|
-
...(which !== undefined && { mode: which }),
|
|
140
|
-
...(yes && which !== undefined && { yes: true }),
|
|
141
|
-
};
|
|
142
|
-
}
|
|
143
120
|
case "ceiling": {
|
|
144
121
|
const { values, positionals } = parse(rest, {
|
|
145
122
|
"full-access": { type: "string" },
|
package/dist/cli.d.ts
CHANGED
|
@@ -1,4 +1,3 @@
|
|
|
1
|
-
import type { Executor } from "./exec/types.js";
|
|
2
1
|
import type { ProcessLookup } from "./pid.js";
|
|
3
2
|
import type { PolicyStore } from "./policy-store.js";
|
|
4
3
|
import type { RunSystem } from "./service/manager.js";
|
|
@@ -13,8 +12,7 @@ export interface CliEnv {
|
|
|
13
12
|
openBrowser?: (url: string) => void;
|
|
14
13
|
out?: (line: string) => void;
|
|
15
14
|
err?: (line: string) => void;
|
|
16
|
-
|
|
17
|
-
/** Builds the staged (protocol 3) program's parts; used only when the protocol selects it. */
|
|
15
|
+
/** Builds the program's parts (the binder and the operation backends). */
|
|
18
16
|
createStaged?: (cred: Credential, policy: PolicyStore) => Promise<StagedDevice> | StagedDevice;
|
|
19
17
|
kill?: typeof process.kill;
|
|
20
18
|
/** Runs a system command for `service` and `stop` and returns its output (default: execFileSync). */
|
|
@@ -23,7 +21,7 @@ export interface CliEnv {
|
|
|
23
21
|
ps?: ProcessLookup;
|
|
24
22
|
/** Standard input is a terminal (default: `process.stdin.isTTY`): a confirmation may be asked. */
|
|
25
23
|
stdinIsTTY?: boolean;
|
|
26
|
-
/** Whether the OS sandbox can run here, for `login`
|
|
24
|
+
/** Whether the OS sandbox can run here, for `login` (default: the runtime's check). */
|
|
27
25
|
sandboxAvailable?: () => {
|
|
28
26
|
ok: true;
|
|
29
27
|
} | {
|
|
@@ -35,12 +33,5 @@ export interface CliEnv {
|
|
|
35
33
|
/** Test seam for `ceiling set`: runs between its read and its locked write. */
|
|
36
34
|
beforeCeilingWrite?: () => void;
|
|
37
35
|
}
|
|
38
|
-
/**
|
|
39
|
-
* Logged when the local policy switches between auto and sandbox. It names the local choice, not
|
|
40
|
-
* the effective mode: the organization's ceiling still cuts it (a device whose org forbids auto
|
|
41
|
-
* runs in the sandbox even with this policy).
|
|
42
|
-
*/
|
|
43
|
-
export declare const AUTO_MODE_ON = "This machine's local policy is auto mode; the deployment's ceiling applies.";
|
|
44
|
-
export declare const AUTO_MODE_OFF = "This machine's local policy is sandbox mode; commands still running in auto mode were stopped.";
|
|
45
36
|
/** Runs one command line and returns the exit code. */
|
|
46
37
|
export declare function runCli(argv: string[], io?: CliEnv): Promise<number>;
|
package/dist/cli.js
CHANGED
|
@@ -4,7 +4,6 @@ import { ceilingCommand } from "./commands/ceiling.js";
|
|
|
4
4
|
import { drain, drainAndWait } from "./commands/drain.js";
|
|
5
5
|
import { login } from "./commands/login.js";
|
|
6
6
|
import { logout } from "./commands/logout.js";
|
|
7
|
-
import { modeCommand } from "./commands/mode.js";
|
|
8
7
|
import { policyCommand } from "./commands/policy.js";
|
|
9
8
|
import { serviceCommand } from "./commands/service.js";
|
|
10
9
|
import { start } from "./commands/start.js";
|
|
@@ -23,66 +22,21 @@ async function askOnTerminal(question) {
|
|
|
23
22
|
}
|
|
24
23
|
}
|
|
25
24
|
/**
|
|
26
|
-
*
|
|
27
|
-
*
|
|
28
|
-
*
|
|
29
|
-
*/
|
|
30
|
-
export const AUTO_MODE_ON = "This machine's local policy is auto mode; the deployment's ceiling applies.";
|
|
31
|
-
export const AUTO_MODE_OFF = "This machine's local policy is sandbox mode; commands still running in auto mode were stopped.";
|
|
32
|
-
/**
|
|
33
|
-
* The executor for the credential's mode; the program's state directory is unreadable to
|
|
34
|
-
* sandboxed commands. OS mode serves a {@link SwitchingExecutor}: the host (auto mode) or the OS
|
|
35
|
-
* sandbox (sandbox mode), chosen per command from the policy and the kernel's ceiling (spec §4.1).
|
|
36
|
-
*/
|
|
37
|
-
function defaultCreateExecutor(stateDir, home, err) {
|
|
38
|
-
return async (cred, store) => {
|
|
39
|
-
const policy = () => store.current();
|
|
40
|
-
if (cred.mode === "docker") {
|
|
41
|
-
const { createDockerExecutor } = await import("./exec/docker.js");
|
|
42
|
-
return createDockerExecutor({
|
|
43
|
-
dir: cred.dir,
|
|
44
|
-
deviceId: cred.deviceId,
|
|
45
|
-
policy,
|
|
46
|
-
});
|
|
47
|
-
}
|
|
48
|
-
// Loaded on demand: the sandbox runtime is only needed by start.
|
|
49
|
-
const [{ createOsExecutor }, { HostExecutor }, { SwitchingExecutor }] = await Promise.all([
|
|
50
|
-
import("./exec/os.js"),
|
|
51
|
-
import("./exec/host.js"),
|
|
52
|
-
import("./exec/switch.js"),
|
|
53
|
-
]);
|
|
54
|
-
const sandboxed = await createOsExecutor({
|
|
55
|
-
dir: cred.dir,
|
|
56
|
-
policy,
|
|
57
|
-
home,
|
|
58
|
-
denyRead: [stateDir],
|
|
59
|
-
});
|
|
60
|
-
return new SwitchingExecutor(sandboxed, new HostExecutor({ dir: cred.dir }), policy, (mode) => err(mode === "auto" ? AUTO_MODE_ON : AUTO_MODE_OFF));
|
|
61
|
-
};
|
|
62
|
-
}
|
|
63
|
-
/**
|
|
64
|
-
* The staged (protocol 3) program's parts (permission activation W3-M): the binder with one
|
|
65
|
-
* operation backend per bound generation, built for this host (macOS, Linux) or the device's
|
|
66
|
-
* container (docker mode). Loaded on demand like the executors.
|
|
25
|
+
* The program's parts (device protocol 3): the binder with one operation backend per bound
|
|
26
|
+
* generation, built for this host (macOS, Linux) or the device's container (docker mode). Loaded
|
|
27
|
+
* on demand: only start needs them.
|
|
67
28
|
*/
|
|
68
29
|
function defaultCreateStaged(stateDir, home) {
|
|
69
30
|
return async (cred, store) => {
|
|
70
31
|
const { createStagedDevice } = await import("./staged-device.js");
|
|
71
32
|
if (cred.mode === "docker") {
|
|
72
|
-
const {
|
|
73
|
-
const container = await
|
|
33
|
+
const { createDockerContainer } = await import("./exec/docker.js");
|
|
34
|
+
const container = await createDockerContainer({
|
|
74
35
|
dir: cred.dir,
|
|
75
36
|
deviceId: cred.deviceId,
|
|
76
37
|
policy: () => store.current(),
|
|
77
38
|
});
|
|
78
|
-
return createStagedDevice({
|
|
79
|
-
cred,
|
|
80
|
-
stateDir,
|
|
81
|
-
policy: store,
|
|
82
|
-
home,
|
|
83
|
-
container,
|
|
84
|
-
dispose: () => container.dispose(),
|
|
85
|
-
});
|
|
39
|
+
return createStagedDevice({ cred, stateDir, policy: store, home, container });
|
|
86
40
|
}
|
|
87
41
|
return createStagedDevice({ cred, stateDir, policy: store, home });
|
|
88
42
|
};
|
|
@@ -139,7 +93,6 @@ export async function runCli(argv, io = {}) {
|
|
|
139
93
|
stateDir: dir,
|
|
140
94
|
out,
|
|
141
95
|
err,
|
|
142
|
-
createExecutor: io.createExecutor ?? defaultCreateExecutor(dir, home, err),
|
|
143
96
|
createStaged: io.createStaged ?? defaultCreateStaged(dir, home),
|
|
144
97
|
...(io.env && { env: io.env }),
|
|
145
98
|
...(io.kill && { kill: io.kill }),
|
|
@@ -167,14 +120,6 @@ export async function runCli(argv, io = {}) {
|
|
|
167
120
|
});
|
|
168
121
|
case "policy":
|
|
169
122
|
return policyCommand(cmd, { stateDir: dir, out, err });
|
|
170
|
-
case "mode":
|
|
171
|
-
return modeCommand(cmd, {
|
|
172
|
-
stateDir: dir,
|
|
173
|
-
out,
|
|
174
|
-
err,
|
|
175
|
-
...(io.sandboxAvailable && { sandboxAvailable: io.sandboxAvailable }),
|
|
176
|
-
...((io.stdinIsTTY ?? process.stdin.isTTY === true) && { ask: io.ask ?? askOnTerminal }),
|
|
177
|
-
});
|
|
178
123
|
case "ceiling":
|
|
179
124
|
return ceilingCommand(cmd, {
|
|
180
125
|
stateDir: dir,
|