Python
Docs: the macOS sandbox, with the README and config example pointing at it
Rohit C Prasadc8db7b9a3485
diff --git a/README.md b/README.mdindex e6dc2822..fc7d7fe1 100644--- a/README.md+++ b/README.md@@ -62,7 +62,7 @@ Governance is the architecture, not a plugin - the agent can't grant itself new2. **A ladder of earned autonomy.** Actions are approval-gated by default. One-off approvals can graduate into standing rules, then into config allowlists - each step explicit, visible, and revocable. In auto-approve mode a reviewer model lets routine actions through and escalates anything it isn't sure about to you; repeated denials trip a circuit breaker that pauses the reviewer and hands control back. Reviewer verdicts are judgments, not guarantees - the floors and the audit trail are what backstop them.3. **An audit trail that answers "who did this, and why?"** Every tool call is recorded with its approval provenance - auto-approved, user-approved, or denied, with the reviewer's reasoning attached - and persisted with the conversation.-4. **A sandbox for what the agent runs.** A session's commands and file tools can run inside an [NVIDIA OpenShell](https://github.com/NVIDIA/OpenShell) sandbox — one Linux container per agent that holds the session's folders and nothing else: no keys, no other files, and only an allow list of network hosts. The agent loop, the model keys and the connectors stay outside the wall, so a prompt injection that reaches a command lands in a box that holds nothing. See [docs/openshell.md](docs/openshell.md).+4. **A sandbox for what the agent runs.** A session's commands and file tools can run inside an [NVIDIA OpenShell](https://github.com/NVIDIA/OpenShell) sandbox — one Linux container per agent that holds the session's folders and nothing else: no keys, no other files, and only an allow list of network hosts. The agent loop, the model keys and the connectors stay outside the wall, so a prompt injection that reaches a command lands in a box that holds nothing. On a Mac the same protection is available with nothing to install, through the sandbox built into macOS. See [docs/openshell.md](docs/openshell.md) and [docs/macos-sandbox.md](docs/macos-sandbox.md).Unattended runs never self-approve: their asks park in an inbox until a human answers. Found a vulnerability? See [SECURITY.md](SECURITY.md).@@ -72,7 +72,7 @@ Unattended runs never self-approve: their asks park in an inbox until a human an- **Work from Slack** - mention `@OpenWorker` in a channel; a session opens on your desktop, the work happens with your tools, and the answer comes back as a thread reply.- **Use your everyday tools** - 25+ integrations including GitHub, Slack, Jira, Notion, Linear, HubSpot, Outlook, monday.com, Gmail, and Google Calendar, plus your **terminal and local files**. Any tool reachable over [MCP](https://modelcontextprotocol.io/) plugs in too, with per-tool control.- **Run on a schedule** - automations for recurring work: a morning brief, a weekly report, a standing watch over a channel. Runs land in the app with full transcripts.-- **Run commands in a sandbox** - turn on [NVIDIA OpenShell](docs/openshell.md) for a machine and every agent's shell and file tools run in their own Linux container, with the session's folders and an allow-listed network and nothing else.+- **Run commands in a sandbox** - turn on [NVIDIA OpenShell](docs/openshell.md) for a machine and every agent's shell and file tools run in their own Linux container, with the session's folders and an allow-listed network and nothing else; on a Mac, the [built-in sandbox](docs/macos-sandbox.md) does the same with nothing to install.- **Ask before acting** - writes, sends, and shell commands are approval-gated, with an optional auto-approve mode that still escalates anything uncertain - see [Governed by design](#governed-by-design).## Bring your own modeldiff --git a/docs/config.example.toml b/docs/config.example.tomlindex 0c80602b..15ae0301 100644--- a/docs/config.example.toml+++ b/docs/config.example.toml@@ -33,8 +33,8 @@ port = 8765# --- Sandbox (machine-level; a project's config cannot change it) ---------------------# Where a session's commands and file tools run: "direct" (in the OpenWorker process,-# the default) or "openshell" (one NVIDIA OpenShell container per agent).-# See docs/openshell.md.+# the default), "openshell" (one NVIDIA OpenShell container per agent) or "seatbelt"+# (the sandbox built into macOS). See docs/openshell.md and docs/macos-sandbox.md.# sandbox_provider = "openshell"# Network allow list inside a sandbox: "strict" (code hosts and package registries) or# "standard" (plus the search APIs).diff --git a/docs/macos-sandbox.md b/docs/macos-sandbox.mdnew file mode 100644index 00000000..a0a2fcfb--- /dev/null+++ b/docs/macos-sandbox.md@@ -0,0 +1,121 @@+# The macOS sandbox — run an agent's commands behind a wall, with nothing to install++On a Mac, OpenWorker can run a session's shell commands and file tools inside the sandbox+that is built into macOS (Seatbelt, the same mechanism the system uses for its own apps).+There is nothing to install: OpenWorker renders a profile from the session's folders and+starts its tool runner under it. The kernel enforces the profile, every process a command+starts inherits it, and the agent loop, your model keys and every connector stay outside.++A few things are true by design:++- **Files: only the session's folders.** A command can read and write the session's+ writable folders and one private temporary folder, and read its read-only folders. The+ rest of your home folder — `.ssh`, `.aws`, browser profiles, documents, OpenWorker's own+ state and its API token — cannot be read or even listed.+- **Network: only an allow list.** The sandbox may reach exactly one local port, an+ allow-list proxy that OpenWorker runs; the proxy tunnels to the hosts on the profile+ and refuses everything else, naming the host.+- **Secrets are absent, not denied.** Nothing in the sandbox holds a key, and variables+ in OpenWorker's environment whose names say they hold a secret are not passed in.+- **The wall is checked before the session starts.** OpenWorker verifies from inside that+ every session folder is reachable and that your home folder is **not**; if the wall is+ not up, the session is refused rather than run open.+- **Every tool result says which mode produced it.** The enforcement level is recorded on+ each tool-call event and in the audit trail.+- **Nothing changes until you choose.** The desktop app runs commands directly, as it+ always has, until you turn the sandbox on for the machine.++## Turn it on++Settings ▸ Sandbox ▸ "macOS sandbox", or in `config.toml`:++```toml+sandbox_provider = "seatbelt" # or "direct": commands run in the OpenWorker process+sandbox_network_profile = "strict" # or "standard"+```++The setting is per machine; a project's own config cannot change it.++## What a command can reach++Read and write:++- the session's writable folders;+- one private folder under `/tmp`, which holds the runner's socket, temporary files, the+ tool caches (`npm`, `pip`, `uv`, Go, Yarn are pointed there) and the sandbox's own home.++Read only:++- the session's read-only folders;+- the system: `/usr`, `/bin`, `/System`, `/Library`, `/opt`, `/Applications`, `/private/etc`;+- OpenWorker's managed tools folder, the tool runner and its Python;+- under your home folder, only a fixed list of developer toolchains — `.nvm`, `.volta`,+ `.bun`, `.deno`, `.pyenv`, `.rbenv`, `.asdf`, `.sdkman`, `.cargo`, `.rustup`,+ `.local/bin`, `.local/share/uv`, `.local/share/mise`, `.local/pipx`, `go` — plus git's+ settings (`.gitconfig`, `.config/git`).++Network: `localhost` on the proxy's port, nothing else. `curl`, `git`, `pip` and `npm`+follow the proxy variables; a program that ignores them has no network at all.++## The network allow list++Two profiles, shared with the OpenShell sandbox:++- **strict** (default): GitHub, GitLab, and the package registries — PyPI, npm, crates.io,+ the Go proxy.+- **standard**: strict plus the search APIs (Brave, Tavily, DuckDuckGo).++Credentials shared on purpose (below) add the hosts their tools need.++## Sharing a credential on purpose++By default the sandbox has none of your logins, which also means `git push` over SSH has+nothing to push with. Settings ▸ Sandbox lists files you can share, all off by default:++| Entry | Copied from | Lets the agent | Hosts added to the allow list |+|---|---|---|---|+| `ssh` | `~/.ssh` | push and pull over SSH, and log in to servers, as you | `github.com:22`, `gitlab.com:22` |+| `gh` | `~/.config/gh` | use `gh` as you: pull requests, issues, releases | `api.github.com:443`, `github.com:443` |+| `aws` | `~/.aws` | use `aws` with your profiles | `*.amazonaws.com:443` |+| `kube` | `~/.kube` | use `kubectl` with your clusters | the servers named in the kubeconfig |++An enabled entry is **copied** into the sandbox's private home when the sandbox starts,+owner-only, and deleted with the sandbox; the real files are never opened for writing.+For `ssh`, the copy is wired so that `ssh` and `git` inside use the copied keys and known+hosts through the proxy, with no agent.++Logins kept in the macOS Keychain (git over HTTPS) are not files and cannot be shared;+use an SSH remote, `gh`, or the GitHub connector. Connectors always run in OpenWorker+itself, outside every sandbox, with their own tokens.++## Known limits++- `ps` does not run inside the sandbox, and `pgrep` cannot list processes.+- A toolchain kept somewhere under your home folder that is not on the list above does not+ run until it is added.+- `cargo` cannot download crates: its registry lives under the read-only `~/.cargo`.+- When a folder is added to a running session, the sandbox is restarted with the new+ folder (a profile is fixed when a process starts). Shell state is lost; the agent is told.++## Security model++1. The tool runner inside the sandbox is untrusted: it holds no keys, decides nothing, and+ everything it returns is treated as data.+2. The sandbox holds the session's folders and nothing else of your home; secrets are+ absent, not denied.+3. The network is an allow list, enforced by the proxy; the refusal names the host.+4. The audit record comes from outside the wall: OpenWorker's tool-call events, each with+ the enforcement level.+5. When the wall cannot be proved up, the session is refused, never run open.++## Troubleshooting++- **"Sessions on this machine are refused"** — the machine is set to the sandbox and it+ cannot be used, usually because OpenWorker itself is running inside another sandbox+ (macOS does not nest them). `openworker machine sandbox status` says why.+- **A tool cannot be found inside the sandbox** — it lives somewhere under your home folder+ that is not on the toolchain list.+- **A host is refused** — it is not on the profile; switch to `standard` if it is a search+ API, or share the credential entry whose hosts include it.+- **`git push` says permission denied inside the sandbox** — no credential is shared.+ Switch the `ssh` (or `gh`) entry on in Settings ▸ Sandbox.