Python
Docs: OpenShell sandboxes, a README tier and bullet, and the config example
Rohit C Prasadde8ce3dd5fdd
diff --git a/README.md b/README.mdindex 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.[](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 modeldiff --git a/docs/config.example.toml b/docs/config.example.tomlindex 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 = truediff --git a/docs/openshell.md b/docs/openshell.mdnew file mode 100644index 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.