@capybara-hq/device 0.1.0-rc.14 → 0.1.0-rc.15

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 (109) hide show
  1. package/README.md +101 -157
  2. package/dist/api.d.ts +2 -2
  3. package/dist/args.d.ts +2 -8
  4. package/dist/args.js +2 -25
  5. package/dist/cli.d.ts +2 -11
  6. package/dist/cli.js +6 -61
  7. package/dist/client.d.ts +8 -45
  8. package/dist/client.js +25 -424
  9. package/dist/command-log.d.ts +14 -4
  10. package/dist/command-log.js +37 -1
  11. package/dist/commands/ceiling.d.ts +0 -2
  12. package/dist/commands/ceiling.js +3 -4
  13. package/dist/commands/login.d.ts +25 -1
  14. package/dist/commands/login.js +75 -61
  15. package/dist/commands/policy.d.ts +6 -8
  16. package/dist/commands/policy.js +30 -49
  17. package/dist/commands/start.d.ts +2 -17
  18. package/dist/commands/start.js +13 -53
  19. package/dist/exec/docker-operations.d.ts +2 -2
  20. package/dist/exec/docker-operations.js +4 -2
  21. package/dist/exec/docker.d.ts +37 -122
  22. package/dist/exec/docker.js +72 -717
  23. package/dist/exec/instance-binding.d.ts +4 -4
  24. package/dist/exec/linux-agent.js +30 -0
  25. package/dist/exec/linux-operation-backend.d.ts +5 -0
  26. package/dist/exec/linux-operation-backend.js +3 -1
  27. package/dist/exec/linux-operation-worker.d.ts +9 -0
  28. package/dist/exec/linux-operation-worker.js +11 -2
  29. package/dist/exec/mac-read-policy.d.ts +58 -0
  30. package/dist/exec/mac-read-policy.js +104 -0
  31. package/dist/exec/mac-self-check.d.ts +6 -3
  32. package/dist/exec/mac-self-check.js +28 -5
  33. package/dist/exec/operation-worker.d.ts +18 -2
  34. package/dist/exec/operation-worker.js +154 -43
  35. package/dist/exec/sandbox-check.d.ts +10 -0
  36. package/dist/exec/sandbox-check.js +18 -0
  37. package/dist/exec/sandbox-messages.d.ts +3 -11
  38. package/dist/exec/sandbox-messages.js +3 -18
  39. package/dist/exec/shared.d.ts +24 -47
  40. package/dist/exec/shared.js +53 -165
  41. package/dist/exec/types.d.ts +2 -66
  42. package/dist/exec/types.js +1 -1
  43. package/dist/node_modules/@anthropic-ai/sandbox-runtime/CAPYBARA-MODIFICATIONS.patch +71 -12
  44. package/dist/node_modules/@anthropic-ai/sandbox-runtime/dist/sandbox/macos-sandbox-utils.js +18 -4
  45. package/dist/node_modules/@anthropic-ai/sandbox-runtime/dist/sandbox/sandbox-config.js +6 -0
  46. package/dist/node_modules/@anthropic-ai/sandbox-runtime/dist/sandbox/sandbox-manager.js +4 -0
  47. package/dist/node_modules/@capybara-hq/plugin-sdk/agent-docs/concepts.md +9 -4
  48. package/dist/node_modules/@capybara-hq/plugin-sdk/agent-docs/extension-points/channel.md +1 -1
  49. package/dist/node_modules/@capybara-hq/plugin-sdk/agent-docs/extension-points/file-preview.md +2 -0
  50. package/dist/node_modules/@capybara-hq/plugin-sdk/agent-docs/extension-points/sandbox.md +1 -1
  51. package/dist/node_modules/@capybara-hq/plugin-sdk/agent-docs/plugin-format.md +1 -1
  52. package/dist/node_modules/@capybara-hq/plugin-sdk/dist/cards.d.ts +11 -0
  53. package/dist/node_modules/@capybara-hq/plugin-sdk/dist/cards.js +1 -1
  54. package/dist/node_modules/@capybara-hq/plugin-sdk/dist/channel.d.ts +37 -0
  55. package/dist/node_modules/@capybara-hq/plugin-sdk/dist/ctx.d.ts +47 -3
  56. package/dist/node_modules/@capybara-hq/plugin-sdk/dist/device-denied-paths.d.ts +14 -0
  57. package/dist/node_modules/@capybara-hq/plugin-sdk/dist/device-denied-paths.js +41 -0
  58. package/dist/node_modules/@capybara-hq/plugin-sdk/dist/device-protocol.d.ts +140 -20
  59. package/dist/node_modules/@capybara-hq/plugin-sdk/dist/device-protocol.js +419 -14
  60. package/dist/node_modules/@capybara-hq/plugin-sdk/dist/file-preview.d.ts +22 -5
  61. package/dist/node_modules/@capybara-hq/plugin-sdk/dist/hooks.d.ts +77 -13
  62. package/dist/node_modules/@capybara-hq/plugin-sdk/dist/http-access.d.ts +10 -0
  63. package/dist/node_modules/@capybara-hq/plugin-sdk/dist/index.d.ts +2 -2
  64. package/dist/node_modules/@capybara-hq/plugin-sdk/dist/index.js +2 -3
  65. package/dist/node_modules/@capybara-hq/plugin-sdk/dist/model.d.ts +89 -5
  66. package/dist/node_modules/@capybara-hq/plugin-sdk/dist/model.js +103 -0
  67. package/dist/node_modules/@capybara-hq/plugin-sdk/dist/permissions.d.ts +3 -2
  68. package/dist/node_modules/@capybara-hq/plugin-sdk/dist/permissions.js +2 -2
  69. package/dist/node_modules/@capybara-hq/plugin-sdk/dist/sandbox-operation.d.ts +4 -0
  70. package/dist/node_modules/@capybara-hq/plugin-sdk/dist/ui-parts.d.ts +1 -1
  71. package/dist/node_modules/@capybara-hq/plugin-sdk/dist/ui-parts.js +11 -0
  72. package/dist/node_modules/@capybara-hq/plugin-sdk/dist/ui.d.ts +25 -6
  73. package/dist/node_modules/@capybara-hq/plugin-sdk/package.json +1 -1
  74. package/dist/owner-report.d.ts +2 -2
  75. package/dist/owner-report.js +2 -2
  76. package/dist/policy-store.d.ts +6 -10
  77. package/dist/policy-store.js +9 -23
  78. package/dist/policy.d.ts +3 -32
  79. package/dist/policy.js +4 -74
  80. package/dist/runtime-manifest.json +1 -1
  81. package/dist/server-ops.d.ts +18 -46
  82. package/dist/server-ops.js +134 -269
  83. package/dist/staged-connect.js +44 -7
  84. package/dist/staged-device.d.ts +4 -4
  85. package/dist/staged-device.js +3 -0
  86. package/dist/staged-session.d.ts +5 -5
  87. package/dist/staged-session.js +4 -4
  88. package/dist/state.js +3 -2
  89. package/package.json +2 -2
  90. package/dist/commands/mode.d.ts +0 -69
  91. package/dist/commands/mode.js +0 -133
  92. package/dist/exec/fs-helper.d.ts +0 -21
  93. package/dist/exec/fs-helper.js +0 -171
  94. package/dist/exec/host.d.ts +0 -61
  95. package/dist/exec/host.js +0 -203
  96. package/dist/exec/listing.d.ts +0 -35
  97. package/dist/exec/listing.js +0 -157
  98. package/dist/exec/os.d.ts +0 -162
  99. package/dist/exec/os.js +0 -616
  100. package/dist/exec/procs.d.ts +0 -11
  101. package/dist/exec/procs.js +0 -67
  102. package/dist/exec/reap.d.ts +0 -41
  103. package/dist/exec/reap.js +0 -89
  104. package/dist/exec/switch.d.ts +0 -107
  105. package/dist/exec/switch.js +0 -204
  106. package/dist/network.d.ts +0 -45
  107. package/dist/network.js +0 -154
  108. package/dist/node_modules/@capybara-hq/plugin-sdk/dist/device-protocol-v3.d.ts +0 -117
  109. 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, in auto mode (as you, with every command reviewed by the deployment) or inside an OS
6
- sandbox, while the program is online.
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]` (it prints the command mode too), `start`, `stop`,
58
- `drain [--wait] [--timeout <seconds>]`, `mode [auto|sandbox] [--yes]`,
59
- `policy [show | set <key> <value> [--yes] | add|remove <key> <value>]` and
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
- `mode` is the only way to switch the command mode (`policy set mode` points there); `mode auto`
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
- keeps the last valid policy and logs one error). Changes made with `capybara-device policy` take
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
- In OS mode a device runs every command in one of two modes (`mode` in `policy.json`; switch it
75
- with `capybara-device mode`):
76
-
77
- - **auto** (the default of a new login): commands run directly on this computer as you — your real
78
- `HOME`, `PATH`, environment, caches, credentials (SSH keys, `gh`, cloud CLIs), Docker and any
79
- network. It is what a coding agent without an OS sandbox has, and what Claude Code calls auto
80
- mode. The deployment reviews every command before it runs and blocks, or asks about, the
81
- dangerous ones (deleting outside the workspace, sending a secret away, force-pushing a protected
82
- branch). The platform's file tools reach any absolute path on the machine. The hello reports
83
- your home directory, and the deployment can list any directory you can read and scan your home
84
- for projects (directory entries only, never file contents).
85
- - **sandbox**: today's strict `@anthropic-ai/sandbox-runtime` profile (macOS Seatbelt, Linux
86
- bubblewrap; Linux needs `bwrap` and `socat`). Writes only under `workspace/` and `tmp/`,
87
- `skills/` read only, `HOME` = the workspace, `~/.ssh`, cloud CLI credentials, `~/.netrc`,
88
- `~/.gnupg`, browser profiles and this program's state directory unreadable, no local binding or
89
- unix sockets, and network only to the domains of the local policy that the organization's
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 mode # print the current mode
106
- capybara-device mode sandbox # switch to the sandbox
107
- capybara-device mode auto # prints the risk text and asks; or add --yes
108
- capybara-device policy add allowedDomains files.slack.com # sandbox mode
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
- A change applies at the next command; a running program does not need a restart. Turning the
114
- sandbox back on stops the commands still running in auto mode. Auto mode is set only on the
115
- machine: the deployment may narrow a device to `sandbox` but never turn auto mode on. An
116
- organization can allow or forbid auto mode; when it forbids it, this device runs in the sandbox
117
- and its summary says so, and the device's own `mode sandbox` always wins. `add` and `remove` work
118
- on `allowedDomains` and `allowCredentials`; every domain must be a lowercase host name (optionally
119
- `*.` for subdomains, never the apex), never an IP address or an internal name. They apply in
120
- sandbox mode only.
121
-
122
- A command ends with everything it started: once it returns (or times out, or is stopped), the
123
- program kills what it left running, such as `server &` or `nohup …`, because inside the sandbox no
124
- later command may signal another command's processes. Its process group goes at once, and a process
125
- that left the group (`setsid`) is found by the marker every process of the command carries. On
126
- macOS only a background task launch (`Bash` with `run_in_background`, whose command starts with the
127
- line `# capybara: background task launch`) keeps what it starts. On Linux the sandbox's pid
128
- namespace already ends every process with its command. In Docker mode and without a sandbox, a
129
- later command can stop what an earlier one left, so nothing is killed.
130
-
131
- When a command is refused a domain, the program says why. Clients that print the proxy's answer
132
- show a reason such as `capybara: files.slack.com is not in this device's allowed domains`, and
133
- after the command its stderr ends with a trailer naming each refused host (at most 20) and who can
134
- lift it:
135
-
136
- ```text
137
- [capybara-device] Network access was blocked:
138
- - files.slack.com:443: not in this device's allowed domains. Only the device owner can allow it (capybara-device policy add allowedDomains files.slack.com, or the device page).
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 set
179
- `mode: "sandbox"`. It can never set `mode: "auto"` — that is `capybara-device mode auto` on the
180
- machine, with its risk text and confirmation. Every host is validated like a local one, the change
181
- is written under `policy.json.lock`, and it applies at the next command. Each change from the
182
- deployment is recorded in the local command log (`commands.log`, next to `policy.json`) with who
183
- decided it, and so is a refused attempt and the grants a command was given:
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":"policy refused mode auto by Ada Lovelace (acc_123) via web",...}
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. Docker mode (a Linux container) does not have this issue.
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
- Not enforced yet in OS mode: the `cpu` and `memoryMb` ceilings. In auto mode commands already see
203
- the owner's credentials, so `allowCredentials` has nothing to add; in sandbox mode they get none.
204
- Processes a command leaves running are killed when it ends; on macOS a child that leaves the
205
- command's process group and runs only Apple system binaries cannot be found by its marker
206
- (`ps -E` hides their environment), so it survives (Linux runs each command in its own pid
207
- namespace, which takes every child down with it).
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 command with `docker exec` in one container per device
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 commands
214
- run as your own uid:gid, so they can write the mounted directories you own (a root user falls back to
215
- 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
216
- at `/workspace`, `/skills` and `/tmp`; the container has a read-only root file system, a pids limit of 1024, `--memory-swap` equal to
217
- `memoryMb`, `--cap-drop ALL` and `no-new-privileges`. The policy's `cpu` and
218
- `memoryMb` become `--cpus` and `--memory`. The container is reused while its mounts and flags
219
- match and recreated when they change (at the next command that finds it idle); it stays running
220
- (idle) between starts. Commands always have the container's own localhost and unix sockets.
221
-
222
- Docker mode has no per-domain network filter, so the mode alone decides:
223
-
224
- - **auto**: the container runs on Docker's default bridge (the whole internet and this machine's
225
- network), and the platform's file tools reach any absolute path in the container.
226
- - **sandbox**: the container has no network at all, and file operations stay in the mounted roots.
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
- ## Staged operation backend
219
+ ## Operation backend
274
220
 
275
- The package includes a private macOS operation backend for the forthcoming permission-profile
276
- protocol. The current CLI, wire version 2, hello and dispatch still use the existing executors.
277
- The staged factory does not advertise restricted support: actual adapter acceptance and the
278
- coordinated policy-writer, background and protocol integration gates remain open. Linux and local
279
- Docker hosts get their own backends on the SDK's restricted Linux runtime (Landlock plus a seccomp
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
- The later protocol cutover must also call reconciliation after successful policy writes and verify
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 allows auto mode (`allowed`, the default) or forbids it (`off`):
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
- autoMode?: "allowed" | "off";
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, SandboxMode } from "./state.js";
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 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 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 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, 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";
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 in sandbox mode
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 in sandbox mode
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
- createExecutor?: (cred: Credential, policy: PolicyStore) => Promise<Executor> | Executor;
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` and `mode` (default: the runtime's check). */
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
- * Logged when the local policy switches between auto and sandbox. It names the local choice, not
27
- * the effective mode: the organization's ceiling still cuts it (a device whose org forbids auto
28
- * runs in the sandbox even with this policy).
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 { createDockerExecutor } = await import("./exec/docker.js");
73
- const container = await createDockerExecutor({
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,