Python
Docs: the Windows sandbox
Rohit C Prasad50177eff67c9
diff --git a/README.md b/README.mdindex fc7d7fe1..f096d35e 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. 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).+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; on Windows, through a hidden local account that cannot see your profile. See [docs/openshell.md](docs/openshell.md), [docs/macos-sandbox.md](docs/macos-sandbox.md) and [docs/windows-sandbox.md](docs/windows-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; on a Mac, the [built-in sandbox](docs/macos-sandbox.md) does the same with nothing to install.+- **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, and on Windows a [hidden local account](docs/windows-sandbox.md) does.- **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/windows-sandbox.md b/docs/windows-sandbox.mdnew file mode 100644index 00000000..dda067e1--- /dev/null+++ b/docs/windows-sandbox.md@@ -0,0 +1,216 @@+# The Windows sandbox — run an agent's commands as an account that cannot see your files++On Windows, OpenWorker can run a session's shell commands and file tools as a hidden local+account that Windows itself keeps out of your profile. There is nothing to install: one+setup step, run once with administrator rights, creates the account and its rules. After+that every command an agent runs, and every process those commands start, runs as that+account, in a job that ends with the session. The agent loop, your model keys and every+connector stay outside, in OpenWorker's own process, as you.++The wall is the operating system's own: file permissions, the Windows Firewall, and+Windows Filtering Platform filters, all written once at setup. Nothing is enforced by+environment variables alone.++```+ your machine+ ┌──────────────────────────────────────────┐ ┌───────────────────────────────────────────┐+ │ OpenWorker (desktop app or local server) │ │ the sandbox — one per agent session │+ │ runs as YOU │ │ runs as a hidden local account │+ │ │ │ │+ │ agent loop · approvals · audit │ named│ tool runner ── PowerShell, file tools │+ │ model keys · connectors · policy │ pipe │ every process it starts inherits the │+ │ tool definitions ───────────────────────────────► account, the job and the rules │+ │ │ │ │+ │ Windows provider │ │ session folders, same paths, rw / ro │+ │ grants the folders, starts the runner, │ │ a private folder for temp and caches │+ │ proves the wall before the session ────┼──┐ │ your profile: invisible │+ │ │ │ │ network: by account (below) │+ │ allow-list proxy (closed mode only) │ │ │ no keys, no OpenWorker state, no token │+ └──────────────────────────────────────────┘ │ └───────────────────────────────────────────┘+ ▼+ ┌────────────────────────────────────────────────────────────────────────────────────────────┐+ │ Windows — permissions on your folders (one entry per session folder), the profile boundary │+ │ (another account cannot read C:\Users\you), a firewall rule and loopback filters on the │+ │ closed account, a job object that ends every sandboxed process with the session │+ └────────────────────────────────────────────────────────────────────────────────────────────┘+```++A few things are true by design:++- **Files: your profile is out of reach.** `C:\Users\<you>` — `.ssh`, `.aws`, documents,+ browser profiles, OpenWorker's own state and its API token — cannot be read or listed by+ the sandbox account. A command can read and write the session's writable folders and one+ private folder of its own, and read its read-only folders.+- **Network: you choose, and the choice is an account.** Open (the default on Windows) runs+ commands as an account with no network rules. Strict and Standard run them as a second+ account whose only way out is OpenWorker's allow-list proxy: the firewall blocks its+ outbound traffic and kernel filters close every local port to it except the proxy's.+- **Secrets are absent, not denied.** The sandbox account has a profile of its own with+ nothing in it. Credentials you share on purpose are copied in for the session and+ removed with it.+- **The wall is checked before the session starts.** OpenWorker verifies from inside that+ every session folder is reachable, that your profile is **not**, and in the closed mode+ that a local port outside the proxy's range is unreachable. If any check fails 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.** OpenWorker runs commands directly, as it always+ has, until you turn the sandbox on for the machine.++## Turn it on++Settings ▸ Sandbox ▸ "Windows sandbox", or in `config.toml`:++```toml+sandbox_provider = "windows" # or "direct": commands run in the OpenWorker process+sandbox_network_profile = "open" # the Windows default; or "strict", "standard"+```++The setting is per machine; a project's own config cannot change it.++The first time the Windows sandbox is selected, OpenWorker asks for administrator rights+and runs the one-time setup (the command line form is `openworker machine sandbox setup`).+If you skip it, or cannot elevate on this machine, sessions still run, in a weaker mode+that is labelled as such (see "Without setup" below), and you are asked again next time.++## What the setup does++One elevated PowerShell script, one prompt. It:++1. creates two hidden local accounts with random passwords nobody sees, `OWSandboxOpenNet`+ and `OWSandboxClosedNet`, hidden from the sign-in screen, with remote, network and+ service logon denied;+2. writes one Windows Firewall rule that blocks every outbound connection for the closed+ account;+3. writes four Windows Filtering Platform filters for the closed account: on loopback it may+ reach ports 47800–47899, where OpenWorker's proxy listens, and nothing else. Windows+ Firewall does not look at loopback traffic; these filters do;+4. stores the passwords in `C:\ProgramData\OpenWorker\sandbox\account.cred`, readable by+ you, administrators and the system only;+5. makes `C:\ProgramData\OpenWorker\sandbox\sandboxes`, where each session gets a private+ folder;+6. records everything it changed in `setup.json`, so that `openworker machine sandbox+ remove` undoes exactly that.++`openworker machine sandbox status` shows each of these and what is missing.++## The network modes++```+ Settings ▸ Sandbox ▸ Network+ │+ ┌────────────────────────┴────────────────────────┐+ │ │+ Open (default) Strict / Standard+ │ │+ ▼ ▼+ runs as OWSandboxOpenNet runs as OWSandboxClosedNet+ no firewall rule, no filters firewall: all outbound BLOCKED+ any host, any local port filters: loopback closed except+ files still confined the proxy's port range+ │ │+ ▼ ▼+ internet ┌──────────────────────────────────────────┐+ │ OpenWorker's allow-list proxy (loopback) │+ │ CONNECT github.com:443 ✓ │+ │ CONNECT pypi.org:443 ✓ │+ │ CONNECT attacker.example:443 ✗ 403 │+ └──────────────────────────────────────────┘+ │+ ▼+ only listed hosts+```++- **Open** — any host. Nothing to configure. The files are still the wall. This is the+ default on Windows.+- **Strict** — GitHub, GitLab and the package registries (PyPI, npm, crates.io, the Go+ proxy), through the proxy. A program that ignores the proxy variables has no network at+ all, because the account's direct traffic is blocked in the kernel.+- **Standard** — Strict plus the search APIs.++Credentials shared on purpose (below) add the hosts their tools need.++Choosing a mode never touches the firewall. The rules are written once at setup; OpenWorker+picks the account. In the closed mode a sandbox can still **listen** on a local port (a dev+server your browser can open); it cannot **connect** to one, other than the proxy.++## What a command can reach++Read and write:++- the session's writable folders (one permission entry each, removed when the session ends);+- one private folder under `C:\ProgramData\OpenWorker\sandbox\sandboxes`, which holds the+ runner, temporary files and the tool caches.++Read only:++- the session's read-only folders;+- Windows itself and machine-wide installs (`C:\Windows`, `C:\Program Files`, and what any+ local account may read);+- folders **outside your profile**, such as `D:\work` or `C:\src`. Windows lets every local+ account read those by default, and so can the sandbox. Keep what the agent must not see+ under your profile.++Not readable:++- your profile, `C:\Users\<you>`, and every other account's profile. This includes+ developer tools installed per user (nvm for Windows, pyenv-win, Scoop, npm's global+ folder, Cargo). A read-only list of those, with switches in Settings, is the next+ change; until then, install the tools the agent needs machine-wide, or grant the folder+ to the session.++## 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 |++A copy is written into the sandbox account's own profile by the runner, so that Windows+OpenSSH accepts the key's permissions, and removed when the runner leaves. In the closed+mode `ssh` reaches its hosts through the proxy; OpenWorker ships the tunnel command, since+Windows has no `nc`. The agent is told what it can do ("you can push over SSH as the+user"), never where a credential is kept. Short-lived cloud roles (AWS first) and an+encrypted wallet for keys that cannot be short-lived are the next additions; see the+design notes.++## Without setup++If setup has not run, the Windows sandbox still limits writes: the runner starts as you,+under a write-restricted token, and can write only where the session's folders and its+private folder carry an entry for it. Reads and the network are yours. OpenWorker labels+this mode `partial` in every tool result and in Settings, and asks for setup again at the+next start. Shared SSH keys cannot be used in this mode (Windows OpenSSH does not finish+under a write-restricted token); the agent is told.++## Every agent, one account++All sessions run under the same account (one per network mode). The goal is to keep your+data away from the agents, not to keep agents away from each other: a sandbox can read+another sandbox's private folder, including credentials copied in for it. Cloud roles that+expire on their own limit what that is worth.++## Known limits++- The `open` mode is open: any host, any local port, including services on this machine.+- `curl.exe` needs `--ssl-revoke-best-effort` in the closed mode, because Windows' own TLS+ checks certificate revocation over plain HTTP, which the firewall blocks. Git, Python and+ Node use OpenSSL and are unaffected. PowerShell 5's `Invoke-WebRequest` ignores the proxy+ variables and sees no network in the closed mode; `curl.exe` follows them.+- OpenShell is not available on Windows today (its Windows driver is a preview of+ Microsoft's execution containers). The Windows sandbox is OpenWorker's own.++## How it compares++| | Windows sandbox | macOS sandbox | OpenShell |+|---|---|---|---|+| Mechanism | a second local account, permissions, firewall and kernel filters | the Seatbelt profile built into macOS | a Linux container with Landlock and seccomp |+| Install | one administrator prompt | nothing | OpenShell and Docker |+| Files | session folders; profile invisible; outside-profile folders readable | session folders; home invisible | session folders; nothing else |+| Network | open (default), or the allow list through the proxy | the allow list through the proxy, or open | the allow list in the policy, or open |+| Default | open | strict | strict |