From a85196817051df96f8f63aed4799371270cd1ef1 Mon Sep 17 00:00:00 2001 From: Vegard Stikbakke Date: Mon, 15 Jun 2026 09:16:13 +0200 Subject: [PATCH] docs(coding-agent): reorder containerization patterns --- README.md | 2 +- .../coding-agent/docs/containerization.md | 70 +++++++++---------- packages/coding-agent/docs/index.md | 2 +- packages/coding-agent/docs/security.md | 2 +- 4 files changed, 38 insertions(+), 38 deletions(-) diff --git a/README.md b/README.md index 563b6858..295dce24 100644 --- a/README.md +++ b/README.md @@ -62,9 +62,9 @@ Pi does not include a built-in permission system for restricting filesystem, pro If you need stronger boundaries, containerize or sandbox Pi. See [packages/coding-agent/docs/containerization.md](packages/coding-agent/docs/containerization.md) for three patterns: -- **OpenShell**: run the whole `pi` process in a policy-controlled sandbox. - **Gondolin extension**: keep `pi` and provider auth on the host while routing built-in tools and `!` commands into a local Linux micro-VM. - **Plain Docker**: run the whole `pi` process in a local container for simple isolation. +- **OpenShell**: run the whole `pi` process in a policy-controlled sandbox. ## Contributing diff --git a/packages/coding-agent/docs/containerization.md b/packages/coding-agent/docs/containerization.md index a3a96bee..33f2df3d 100644 --- a/packages/coding-agent/docs/containerization.md +++ b/packages/coding-agent/docs/containerization.md @@ -10,46 +10,12 @@ There are two general options. You can either | Pattern | What is isolated | Best for | Notes | | --- | --- | --- | --- | -| OpenShell | Whole `pi` process in a policy-controlled sandbox | Local or remote managed sandbox | Requires an OpenShell gateway | | Gondolin extension | Built-in tools and `!` commands | Local micro-VM isolation while keeping auth on host | See [`examples/extensions/gondolin/`](../examples/extensions/gondolin/). | | Plain Docker | Whole `pi` process in a local container | Simple local isolation | Provider API keys enter the container. | +| OpenShell | Whole `pi` process in a policy-controlled sandbox | Local or remote managed sandbox | Requires an OpenShell gateway | Extensions run wherever the `pi` process runs. If you run host `pi` with a tool-routing extension, other custom extension tools still run on the host unless they also delegate their operations. -## OpenShell - -Use [NVIDIA OpenShell](https://docs.nvidia.com/openshell/about/overview) when you want a policy-controlled sandbox with filesystem, process, network, credential, and inference controls. -OpenShell can run sandboxes through a local gateway backed by Docker, Podman, or a VM runtime, or through a remote Kubernetes gateway. - -Every sandbox requires an active gateway. -Register and select one before creating a sandbox: - -```bash -openshell gateway add --name -openshell gateway select -``` - -Launch `pi` inside an OpenShell sandbox: - -```bash -openshell sandbox create --name pi-sandbox --from pi -- pi -``` - -In this pattern, the whole `pi` process runs inside the sandbox. -Built-in tools, `!` commands, and extension tools execute inside the OpenShell boundary. - -If the gateway is remote, project files are not bind-mounted from the host, meaning writes in the sandbox are not reflected on your machine. -Clone the repository inside the sandbox or use OpenShell file transfer commands: - -```bash -openshell sandbox upload pi-sandbox ./repo /workspace -openshell sandbox download pi-sandbox /workspace/repo ./repo-out -``` - -OpenShell providers can keep raw model API keys outside the sandbox. -When inference routing is configured, code inside the sandbox can call `https://inference.local`, and the gateway injects the configured provider credentials upstream. -Configure Pi to use the corresponding OpenAI-compatible or Anthropic-compatible endpoint if you want model traffic to use this route. - ## Gondolin [Gondolin](https://github.com/earendil-works/gondolin) is a local Linux micro-VM. @@ -109,3 +75,37 @@ docker run --rm -it \ The `-v "$PWD:/workspace"` mounts your current directory into the container at /workspace such that reads and writes in `/workspace` inside Docker directly affect your host files, like in the Gondolin example. Use a named volume for `/root/.pi/agent` if you want container-local settings and sessions. Mounting your host `~/.pi/agent` exposes host auth and session files to the container. + +## OpenShell + +Use [NVIDIA OpenShell](https://docs.nvidia.com/openshell/about/overview) when you want a policy-controlled sandbox with filesystem, process, network, credential, and inference controls. +OpenShell can run sandboxes through a local gateway backed by Docker, Podman, or a VM runtime, or through a remote Kubernetes gateway. + +Every sandbox requires an active gateway. +Register and select one before creating a sandbox: + +```bash +openshell gateway add --name +openshell gateway select +``` + +Launch `pi` inside an OpenShell sandbox: + +```bash +openshell sandbox create --name pi-sandbox --from pi -- pi +``` + +In this pattern, the whole `pi` process runs inside the sandbox. +Built-in tools, `!` commands, and extension tools execute inside the OpenShell boundary. + +If the gateway is remote, project files are not bind-mounted from the host, meaning writes in the sandbox are not reflected on your machine. +Clone the repository inside the sandbox or use OpenShell file transfer commands: + +```bash +openshell sandbox upload pi-sandbox ./repo /workspace +openshell sandbox download pi-sandbox /workspace/repo ./repo-out +``` + +OpenShell providers can keep raw model API keys outside the sandbox. +When inference routing is configured, code inside the sandbox can call `https://inference.local`, and the gateway injects the configured provider credentials upstream. +Configure Pi to use the corresponding OpenAI-compatible or Anthropic-compatible endpoint if you want model traffic to use this route. diff --git a/packages/coding-agent/docs/index.md b/packages/coding-agent/docs/index.md index 71995831..b5ee017e 100644 --- a/packages/coding-agent/docs/index.md +++ b/packages/coding-agent/docs/index.md @@ -42,7 +42,7 @@ For the full first-run flow, see [Quickstart](quickstart.md). - [Using Pi](usage.md) - interactive mode, slash commands, context files, and CLI reference. - [Providers](providers.md) - subscription and API-key setup for built-in providers. - [Security](security.md) - project trust, sandbox boundaries, and vulnerability reporting. -- [Containerization](containerization.md) - sandbox pi with OpenShell, Gondolin, or Docker. +- [Containerization](containerization.md) - sandbox pi with Gondolin, Docker, or OpenShell. - [Settings](settings.md) - global and project settings. - [Keybindings](keybindings.md) - default shortcuts and custom keybindings. - [Sessions](sessions.md) - session management, branching, and tree navigation. diff --git a/packages/coding-agent/docs/security.md b/packages/coding-agent/docs/security.md index 3a268a8a..29828e03 100644 --- a/packages/coding-agent/docs/security.md +++ b/packages/coding-agent/docs/security.md @@ -42,7 +42,7 @@ For untrusted repositories, generated code you do not intend to monitor closely, Common patterns are documented in [Containerization](containerization.md): -- run the whole `pi` process inside OpenShell or Docker +- run the whole `pi` process inside a container/sandbox - run host pi while routing built-in tool execution into a Gondolin micro-VM - mount only the workspace paths the agent should access - avoid mounting host `~/.pi/agent` unless the container should access host sessions, settings, and credentials