Skip to content
Python

Docs: the macOS sandbox, with the README and config example pointing at it

Rohit C Prasadc8db7b9a3485
diff --git a/README.md b/README.md
index 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 new
2. **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 model
diff --git a/docs/config.example.toml b/docs/config.example.toml
index 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.md
new file mode 100644
index 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.