@cabane/companion 0.6.186 → 0.6.188

package/README.md

@@ -14,18 +14,18 @@ Three things, one relation each.
 - **A harness** is a coding tool on the device with a login behind it. The Companion detects each one and reports its state: connected, needs sign-in, limited, problem, off or gone. A device offers exactly the harnesses it has.
 - **An agent** is assigned to one device and runs through one of that device's harnesses, with a model from it. Assign in as many workspaces as you like: one Companion serves them all.
 
-**Cabane decides what an agent is; the device decides what it can touch.** Everything about the agent lives on its page in Cabane and is delivered with each turn, so an edit there lands on the next reply with no restart: its charter, its harness and model, its MCP servers, its host access and its starting folder. The device holds only what can't travel from a server: the device token, your secrets, and local overrides for this device.
+**Cabane decides what an agent is; the device decides what it can touch.** Everything about the agent lives on its page in Cabane and is delivered with each turn, so an edit there lands on the next reply with no restart: its charter, its harness and model, its MCP servers and its starting folder. The device holds only what can't travel from a server: the device token, your secrets, and local overrides for this device.
 
 How a turn runs, top to bottom:
 
-| Layer         | Holds                                                                                                                                                                                               |
-| ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| **Cabane**    | The agent's reach: **host access** off (workspace only, the default) or on (shell and files on the device, starting in a folder). Only the agent's owner changes it. A conversation can't widen it. |
-| **Companion** | The listener on the device. Holds the pairing and the harness logins, and runs as you.                                                                                                              |
-| **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.                                                                                   |
+| Layer         | Holds                                                                                                                                                                            |
+| ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Cabane**    | The agent: its charter, harness and model, the folder it starts in and its MCP servers. Who can edit it decides who changes them; an agent never does, and a conversation can't. |
+| **Companion** | The listener on the device. Holds the pairing and the harness logins.                                                                                                            |
+| **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 with host access acts on the device as the user account the Companion runs under, with no approval prompts.** Turn it on for an agent whose work needs the device, on a device where that reach is acceptable. To isolate an agent, 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.** 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.
 
 **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,7 +125,13 @@ A malformed block fails `cabane start` with the field named. A `runners` block o
 
 ### Isolation
 
-The companion does no sandboxing. An agent with host access runs as you, with your tools, your settings and your files. On Claude Code your own `~/.claude/settings.json` applies, permission rules and hooks included; on Codex your `config.toml` applies except the sandbox, which Cabane turns off for a host-access turn; OpenCode is your own server. To isolate an agent, run the companion itself somewhere isolated: a container, a VM, or a machine that exists for agents. Recipes for that follow. Cabane shows on the device page who the Companion runs as and whether it is in a container.
+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:
+
+- **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
 
@@ -142,4 +148,4 @@ cabane logs -f             # follow the log
 
 ## Not yet
 
-Windows has no service install and no self-update. There is no per-tool permissioning for an agent with host access in Cabane: it's all or nothing per agent, and the harness's own settings are the harness's.
+Windows has no service install and no self-update. There is no per-tool permissioning in Cabane: an agent on a device reaches the whole device, and the harness's own settings are the harness's.