Skip to content
Python

Docs: OpenShell sandboxes, a README tier and bullet, and the config example

Rohit C Prasadde8ce3dd5fdd
diff --git a/README.md b/README.md
index 60172b41..e6dc2822 100644
--- a/README.md
+++ b/README.md
@@ -8,7 +8,7 @@
**AI that gets your everyday tasks done.** OpenWorker is an open-source AI coworker that lives on your desktop and delivers **finished work**, not just chat: your code reviewed for vulnerabilities with fixes ready to go, a polished document, a Slack reply with the numbers, a triaged inbox. It ships **specialist Security coworkers** first — attackers already use AI, and defenders deserve the same leverage, governed.
-It runs on your machine and doesn't lock you into any model: bring your own API key for OpenAI, Anthropic, Google, or an open-weight provider, or run fully local with Ollama. Your data leaves your machine only through the model and integrations *you* choose. Every action an agent takes is governed and logged — see [Governed by design](#governed-by-design).
+It runs on your machine and doesn't lock you into any model: bring your own API key for OpenAI, Anthropic, Google, or an open-weight provider, or run fully local with Ollama. Your data leaves your machine only through the model and integrations *you* choose. Every action an agent takes is governed and logged — see [Governed by design](#governed-by-design) — and its commands can run inside an [NVIDIA OpenShell](docs/openshell.md) sandbox.
[![How OpenWorker works](docs/assets/how-it-works.png)](https://openworker.com)
@@ -56,12 +56,14 @@ Under the hood:
## Governed by design
-Governance is the architecture, not a plugin - the agent can't grant itself new permissions, and no prompt can talk it past a gate. Three tiers, all in this repo:
+Governance is the architecture, not a plugin - the agent can't grant itself new permissions, and no prompt can talk it past a gate. Four tiers, all in this repo:
1. **Hard floors.** A set of dangerous and irreversible operations is human-only, always. No mode - including full auto-approve - lowers these floors; they always escalate to you.
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).
+
Unattended runs never self-approve: their asks park in an inbox until a human answers. Found a vulnerability? See [SECURITY.md](SECURITY.md).
## What it can do
@@ -70,6 +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.
- **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 b3c592bb..0c80602b 100644
--- a/docs/config.example.toml
+++ b/docs/config.example.toml
@@ -30,3 +30,17 @@ auto_allow = ["write_file", "replace_in_file", "apply_patch", "apply_unified_dif
# Server (openworker-server) bind address.
host = "127.0.0.1"
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.
+# sandbox_provider = "openshell"
+# Network allow list inside a sandbox: "strict" (code hosts and package registries) or
+# "standard" (plus the search APIs).
+# sandbox_network_profile = "strict"
+# Credentials an agent may be given, copied into the sandbox for the session and deleted
+# with it. All off unless enabled here or in Settings ▸ Sandbox.
+# [[sandbox_credentials]]
+# name = "ssh"
+# enabled = true
diff --git a/docs/openshell.md b/docs/openshell.md
new file mode 100644
index 00000000..5f0241f4
--- /dev/null
+++ b/docs/openshell.md
@@ -0,0 +1,161 @@
+# OpenShell — run an agent's commands inside a sandbox
+
+OpenWorker can run a session's shell commands and file tools inside an
+[NVIDIA OpenShell](https://github.com/NVIDIA/OpenShell) sandbox: one Linux container per
+agent that holds the session's folders and nothing else of your machine. The agent loop,
+your model keys and every connector stay outside it. This works on Linux and on a Mac
+(with Docker Desktop, where the sandboxes run inside Docker's Linux VM against your
+folders).
+
+A few things are true by design, before any setup:
+
+- **Files: only the session's folders.** A sandbox sees the folders the session was given,
+ at the same paths, read-write or read-only as the session has them. The rest of your
+ home folder — `.ssh`, `.aws`, browser profiles, documents, OpenWorker's own state and
+ its API token — is not there.
+- **Network: only an allow list.** Package registries and code hosts by default; every
+ other host is refused.
+- **Secrets are absent, not denied.** Nothing in the sandbox holds a key. A prompt
+ injection that lands in a sandboxed command lands in a box that holds nothing.
+- **The wall is enforced by the container, not by the model.** Every process a command
+ starts inherits it, and a session is refused rather than run open when OpenShell
+ cannot be used.
+- **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 OpenShell on for the machine.
+
+## How it fits together
+
+```text
+ your machine
+ ┌─────────────────────────────────────────┐ ┌──────────────────────────────────────────┐
+ │ OpenWorker (desktop app or local server)│ │ OpenShell sandbox — one per agent │
+ │ │ │ (Linux container from a pinned image) │
+ │ agent loop · approvals · audit │ │ │
+ │ model keys · connectors · policy │ exec │ tool runner ── shell, file tools │
+ │ tool definitions ─────────────────────────────► (standard library only, read-only mount)│
+ │ │stream│ │
+ │ OpenShell provider │ │ session folders, same paths, rw / ro │
+ │ renders the policy, create / delete ──┼──┐ │ network: the allow list, nothing else │
+ │ │ │ │ no keys, no home folder, no state dir │
+ └─────────────────────────────────────────┘ │ └──────────────────────────────────────────┘
+ ▼
+ ┌─────────────────────────────────────────────────────────────────────────────────────────┐
+ │ OpenShell gateway — creates the sandbox, applies the policy (Landlock, seccomp, │
+ │ network), carries the exec stream, writes its own OCSF audit log │
+ └─────────────────────────────────────────────────────────────────────────────────────────┘
+```
+
+OpenWorker uses OpenShell as it is. For each agent it creates a sandbox from a pinned base
+image with a policy OpenWorker renders from the session: the folders, the user that owns
+them, the network profile. Inside the sandbox runs OpenWorker's **tool runner**, a small
+standard-library program that hosts the agent's shell and file tools. The desktop app or
+the local server talks to it over OpenShell's own exec stream; no port is opened and
+nothing is forwarded. Tool *definitions* stay in OpenWorker; only their *execution*
+crosses into the sandbox, and everything that comes back is treated as data.
+
+## What you need
+
+- A Linux machine, or a Mac with Docker Desktop.
+- Docker or Podman.
+- OpenShell 0.0.116, the release OpenWorker is tested against.
+
+## Set it up
+
+```bash
+openworker machine sandbox status
+openworker machine sandbox setup
+```
+
+`status` lists what is missing. `setup` shows each change before it makes it and asks
+first: it runs NVIDIA's installer for the pinned OpenShell release, allows bind mounts in
+the gateway's configuration (that is how your folders reach a sandbox), keeps the gateway
+running after you log out, and sets the machine to use OpenShell. It never runs `sudo` for
+you; when a step needs an administrator, it prints the command.
+
+The setting is per machine, in Settings ▸ Sandbox or in `config.toml`:
+
+```toml
+sandbox_provider = "openshell" # or "direct": commands run in the OpenWorker process
+sandbox_network_profile = "strict" # or "standard"
+```
+
+A project's own config cannot change it. When a machine is set to OpenShell and OpenShell
+cannot be used (not installed, not running, bind mounts off), sessions are **refused**
+with the reason, so a lost wall is never silent. A headless machine (`openworker up`, see
+[Remote machines](remote-machines.md)) uses OpenShell on its own when it is installed and
+running, and warns loudly when it has to run unprotected.
+
+## What a sandbox gets
+
+- The session's folders as bind mounts at the same absolute paths, read-only where the
+ session has them read-only.
+- The tool runner as a read-only mount, never baked into an image, started as the
+ sandbox's main command so it lives as long as the sandbox.
+- A policy with Landlock as a hard requirement: a kernel without it refuses to run
+ instead of running open.
+- The network profile below. No OpenShell credential providers are attached.
+
+When a folder is added to a running session, the sandbox is recreated with the new folder
+(filesystem rules are fixed when an OpenShell sandbox is created). Shell state is lost;
+the agent is told.
+
+## The network allow list
+
+Two profiles:
+
+- **strict** (default): GitHub, GitLab, and the package registries — PyPI, npm, crates.io,
+ the Go proxy.
+- **standard**: strict plus the search APIs (Brave, Tavily, DuckDuckGo).
+
+OpenShell enforces the list in the container. Credentials shared on purpose (next
+section) add the hosts their tools need.
+
+## Sharing a credential on purpose
+
+By default a sandbox has none of your logins, which also means `git push` over SSH has
+nothing to push with. If you want a tool to work inside as it does outside, you can share
+specific files. Settings ▸ Sandbox lists them, 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 |
+
+You can add your own entries (a name, a path under your home folder, the hosts it needs).
+
+An enabled entry is **copied** into a private home that is mounted into the sandbox when
+it 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, with no agent. Connectors always run in OpenWorker itself, outside every
+sandbox, with their own tokens.
+
+```toml
+[[sandbox_credentials]]
+name = "ssh"
+enabled = true
+```
+
+## 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 the machine; secrets are
+ absent, not denied.
+3. The network is an allow list, enforced by OpenShell.
+4. The audit record comes from outside the wall: OpenWorker's tool-call events (with the
+ enforcement level) plus OpenShell's own OCSF log.
+5. When OpenShell cannot be used, the session is refused, never run open.
+
+## Troubleshooting
+
+- **"Sessions on this machine are refused"** — the machine is set to OpenShell and it
+ cannot be used right now. Run `openworker machine sandbox status` for the reason; the
+ usual ones are the gateway not running, or bind mounts not allowed.
+- **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.