@cabane/companion 0.6.192 → 0.6.194

package/README.md

@@ -25,7 +25,7 @@ How a turn runs, top to bottom:
 | **Runner**    | A child process per turn with a one-turn credential.                                                                                                                             |
 | **Harness**   | Claude Code, Codex or OpenCode with its normal tools and your own settings. Nothing asks for permission mid-task.                                                                |
 
-> **An agent on this device reaches the whole device.** It runs the device's harness with its tools and the files there, and no approval prompts. Put agents on a device where that reach is acceptable. To confine them, set the harness's own sandbox, or isolate the Companion (see Isolation). An agent that reads untrusted input (public web, inbound mail, outside members) runs on a Companion that is isolated, whatever the device.
+> **An agent on this device reaches the whole device, with no approval prompts.** It runs the device's harness with its tools and the files there, and nothing waits for a click: nobody is at the screen, and approvals would hold the work to a person's pace. For almost everyone, the recommendation is to run the Companion and its harness together in a container or VM; running directly, with the harness's own sandbox set, is the alternative, and that sandbox restricts particular tools (see Isolation). An agent that reads untrusted input (public web, inbound mail, outside members) runs on a Companion that is isolated, whatever the device.
 
 **No account password or full-account token ever touches the device.** The setup code delivers a device token (`cabdev_…`) good only for pulling this device's assignments and reporting liveness. Each assigned agent gets its own workspace-bound credential, delivered once. Renaming, deactivating, removing a device and rotating its token happen in Cabane.
 
@@ -125,14 +125,21 @@ A malformed block fails `cabane start` with the field named. A `runners` block o
 
 ### Isolation
 
-The Companion does no sandboxing, and Cabane has no setting for it. Every agent runs the device's harness with its tools, settings and the files there. Confining agents is set in each harness's own file, and governs your own sessions there as well as every agent on the device:
+There are no tool approvals. Every agent runs the device's harness with its tools, settings and the files there, and nothing waits for a click: nobody is at the screen, and with the amount of work a person or a team puts through Cabane, approvals would hold it to a person's pace. The Companion approves Claude Code's tools through a hook, similar to `bypassPermissions` (it doesn't set that permission mode), and runs Codex with `approval_policy = "never"`.
+
+Cabane has no sandbox setting of its own. A harness's own sandbox settings restrict particular tools; they don't isolate the Companion and everything it launches. A container or VM contains the Companion and its child processes.
+
+So where agents run is your choice, and there are two ways:
+
+- **The Companion in a container or VM**, recommended for almost everyone: the Companion and the harness together in Docker, OrbStack or a VM, sharing only the folders and credentials they need. Agents keep a full shell to work and code in, still with no approvals, while the container or VM limits what they reach to what you put in, MCP servers, hooks and the harness process included. If you haven't set one up before, ask Claude to help; **Common device patterns** in Cabane's Docs walks through one with Docker.
+- **Directly on your device**, with the harness's own sandbox set to taste. It restricts particular tools, and each harness draws a different line.
+
+Running directly, confining agents is set in each harness's own file, and governs your own sessions there as well as every agent on the device:
 
 - **Claude Code**, `~/.claude/settings.json`: `"sandbox": { "enabled": true, "allowUnsandboxedCommands": false, "failIfUnavailable": true }`. Commands can then write only in the agent's folder, the temp folder and the paths you add, and reach only the hosts you allow; reads stay open unless you deny them, and Claude's own file tools obey permission `deny` rules, not the sandbox. Set `allowUnsandboxedCommands: false`: when a sandboxed command fails the model can retry it unsandboxed, and on a Cabane turn there is nobody to ask, so the retry would be approved. `failIfUnavailable` stops commands running unsandboxed when bubblewrap is missing.
 - **Codex**, `~/.codex/config.toml` (or `$CODEX_HOME/config.toml`): set `sandbox_mode` and the Companion passes no sandbox flag, so the file governs; set nothing and turns run `danger-full-access`. `workspace-write` confines writes to the agent's folder, `/tmp` and your `writable_roots`, leaves reads open, turns command network off unless `[sandbox_workspace_write] network_access = true`, and runs each command in its own namespace, so a process it leaves running (a dev server, a background build) stops when the command returns. Docker doesn't work inside it.
 - **OpenCode** is your own `opencode serve`.
 
-For agents stricter than you, run the Companion as a second user account, with its own `~/.claude` and `~/.codex`, or run it somewhere isolated: a container, a VM, or a machine that exists for agents. Only that also covers what neither sandbox touches: MCP servers, hooks, the harness process and reads. Recipes for that follow.
-
 ## Debugging a turn
 
 Cabane shows the reply, not how the agent got there. Every turn writes its full stream to `~/.cabane/transcripts/`: the tool list, every tool call and its result, the text, the outcome. A failed turn's log line names its transcript.