docs: add OpenShell local Docker guide

.github/workflows/build-operator.yml

@@ -82,6 +82,7 @@ jobs:
           - { suffix: "-antigravity", dockerfile: "Dockerfile.antigravity", artifact: "antigravity" }
           - { suffix: "-pi", dockerfile: "Dockerfile.pi", artifact: "pi" }
           - { suffix: "-native", dockerfile: "Dockerfile.native", artifact: "native" }
+          - { suffix: "-native-sandbox", dockerfile: "openshell/Dockerfile", artifact: "native-sandbox" }
         platform:
           - { os: linux/amd64, runner: ubuntu-latest }
           - { os: linux/arm64, runner: ubuntu-24.04-arm }
@@ -150,6 +151,7 @@ jobs:
           - { suffix: "-antigravity", artifact: "antigravity" }
           - { suffix: "-pi", artifact: "pi" }
           - { suffix: "-native", artifact: "native" }
+          - { suffix: "-native-sandbox", artifact: "native-sandbox" }
     runs-on: ubuntu-latest
     permissions:
       contents: read

.github/workflows/docker-smoke-test.yml

@@ -24,6 +24,7 @@ jobs:
           - { dockerfile: Dockerfile.grok, suffix: "-grok", agent: "grok", agent_args: "agent stdio" }
           - { dockerfile: Dockerfile.antigravity, suffix: "-antigravity", agent: "agy-acp", agent_args: "" }
           - { dockerfile: Dockerfile.pi, suffix: "-pi", agent: "pi-acp", agent_args: "" }
+          - { dockerfile: openshell/Dockerfile, suffix: "-native-sandbox", agent: "openab-agent", agent_args: "" }
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v6

docs/openshell.md

@@ -0,0 +1,158 @@
+# OpenShell
+
+Run OAB inside an [NVIDIA OpenShell](https://github.com/NVIDIA/OpenShell) sandbox for isolated, policy-enforced execution.
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────────────────────────────┐
+│  Host (Linux with Docker)                                           │
+│                                                                     │
+│  ┌───────────────────────────────────────────────────────────────┐  │
+│  │  OpenShell Gateway (systemd user service :17670)              │  │
+│  │  • manages sandbox lifecycle                                  │  │
+│  │  • enforces network policy (default-deny egress)              │  │
+│  │  • injects provider credentials into sandbox env              │  │
+│  └──────────────────────────┬────────────────────────────────────┘  │
+│                             │ creates & policies                     │
+│                             ▼                                        │
+│  ┌───────────────────────────────────────────────────────────────┐  │
+│  │  Docker Container (sandbox: "oab")                            │  │
+│  │                                                               │  │
+│  │  /home/sandbox/                                               │  │
+│  │  └── config.toml         ← bot token + agent config           │  │
+│  │                                                               │  │
+│  │  openab run ──stdio JSON-RPC──► openab-agent                  │  │
+│  │       │                              │                        │  │
+│  │       │ Discord WS                   │ ChatGPT API            │  │
+│  └───────┼──────────────────────────────┼────────────────────────┘  │
+│           │                              │                           │
+│  ┌────────┼──────────────────────────────┼────────────────────┐     │
+│  │ Network Policy (egress allowlist)     │                    │     │
+│  │  ✓ discord.com:443                    │                    │     │
+│  │  ✓ gateway.discord.gg:443            │                    │     │
+│  │  ✓ cdn.discordapp.com:443            │                    │     │
+│  │  ✓ chatgpt.com:443  ◄────────────────┘                    │     │
+│  │  ✓ auth0.openai.com:443                                   │     │
+│  │  ✗ everything else DENIED                                  │     │
+│  └────────┼───────────────────────────────────────────────────┘     │
+└───────────┼─────────────────────────────────────────────────────────┘
+            │
+            ▼
+┌──────────────────┐         ┌──────────────────┐
+│  Discord API     │         │  ChatGPT API     │
+│  (bot gateway)   │         │  (chatgpt.com)   │
+└──────────────────┘         └──────────────────┘
+```
+
+## Prerequisites
+
+- Docker running on the host (user must be in the `docker` group)
+- [OpenShell CLI](https://github.com/NVIDIA/OpenShell#install) installed
+
+```bash
+curl -LsSf https://raw.githubusercontent.com/NVIDIA/OpenShell/main/install.sh | sh
+```
+
+> **Note:** If the gateway fails with "failed to query Docker daemon version", add your user to the `docker` group and re-login:
+> ```bash
+> sudo usermod -aG docker $USER
+> # Log out and back in (or: loginctl terminate-user $USER)
+> ```
+
+## Quick Start
+
+### 1. Create credential provider
+
+```bash
+openshell provider create --name discord --type generic \
+  --credential "DISCORD_BOT_TOKEN=your-token-here"
+```
+
+### 2. Create sandbox
+
+Using the pre-built image:
+
+```bash
+openshell sandbox create --name oab \
+  --from ghcr.io/openabdev/openab-native-sandbox:latest \
+  --provider discord \
+  -- bash
+```
+
+Or build locally from `openshell/Dockerfile`:
+
+```bash
+docker build -t oab-sandbox openshell/
+openshell sandbox create --name oab \
+  --from oab-sandbox:latest \
+  --provider discord \
+  -- bash
+```
+
+### 3. Set network policy (from host)
+
+```bash
+openshell policy update oab \
+  --add-endpoint "discord.com:443:read-write:rest:enforce" \
+  --add-endpoint "gateway.discord.gg:443:read-write:websocket:enforce" \
+  --add-endpoint "cdn.discordapp.com:443:read-write:rest:enforce" \
+  --add-endpoint "chatgpt.com:443:read-write:rest:enforce" \
+  --add-endpoint "auth0.openai.com:443:read-write:rest:enforce"
+```
+
+### 4. Authenticate (inside sandbox)
+
+```bash
+sandbox$ openab-agent auth codex-oauth --no-browser
+```
+
+Open the printed URL in your browser, approve, then paste the `localhost:1455/auth/callback?...` URL back.
+
+### 5. Create config and run
+
+```bash
+sandbox$ cat > config.toml <<'EOF'
+[discord]
+bot_token = "your-bot-token"
+allow_all_channels = true
+
+[agent]
+command = "openab-agent"
+working_dir = "/home/sandbox"
+env = { OPENAB_AGENT_OPENAI_MODEL = "gpt-5.4-mini" }
+
+[pool]
+max_sessions = 3
+session_ttl_hours = 1
+
+[reactions]
+enabled = true
+EOF
+
+sandbox$ openab run --config config.toml
+```
+
+## Network Policy
+
+OpenShell sandboxes have **default-deny egress**. Required endpoints by backend:
+
+| Backend | Endpoints |
+|---------|-----------|
+| All | `discord.com:443`, `gateway.discord.gg:443`, `cdn.discordapp.com:443` |
+| Native Agent (codex) | `chatgpt.com:443`, `auth0.openai.com:443` |
+| Native Agent (anthropic) | `api.anthropic.com:443` |
+| GitHub access | `api.github.com:443`, `github.com:443` |
+
+## Reconnecting
+
+```bash
+openshell sandbox connect oab
+```
+
+## Cleanup
+
+```bash
+openshell sandbox delete oab
+openshell provider delete discord
+```

openshell/Dockerfile

@@ -0,0 +1,9 @@
+FROM ghcr.io/openabdev/openab-native:beta
+
+USER root
+RUN apt-get update && apt-get install -y --no-install-recommends iproute2 && rm -rf /var/lib/apt/lists/*
+RUN groupadd -g 1000660000 sandbox && \
+    useradd -u 1000660000 -g sandbox -m -s /bin/bash sandbox
+
+USER sandbox
+WORKDIR /home/sandbox