Evaluate NVIDIA OpenShell as sandbox backend for network isolation

[jflowers]

Summary

NVIDIA OpenShell (v0.0.55, Apache 2.0, 6.7k stars, 61 contributors) is an open-source sandbox runtime for AI agents built in Rust. It provides containerized isolation with a centralized gateway, declarative YAML network/filesystem/process policies, and an inference routing layer. It supports rootless Podman and — as of v0.0.55 — Google Vertex AI as a first-class provider (including the global region that UF's gateway currently rejects).

The primary motivation for this evaluation is network isolation: UF's current sandbox has zero network policy enforcement — containers get full, unrestricted network access. OpenShell's L7 policy engine is its defining feature.

Feature Comparison

Dimension	UF Sandbox + Gateway	OpenShell
Container runtimes	Podman only (rootless)	Docker, Podman, MicroVM, Kubernetes
Network policy	None — full network access	L7 declarative YAML (host, HTTP method, path), hot-reloadable
Filesystem policy	isolated or direct modes	Declarative YAML, per-path allow/deny, locked at creation
Process policy	None	Seccomp + privilege escalation prevention
Credential isolation	Gateway proxies Anthropic/Vertex/Bedrock; other keys forwarded raw	Placeholder-based injection — agent never sees real values
Vertex AI	Claude only; rejects global region; shells out to gcloud	Claude + Gemini + third-party; global/us/eu/regional; native OAuth2 refresh
Multi-provider	One provider per gateway session	Multiple named providers, runtime attach/detach
Multi-sandbox	One per project (fixed name)	Multiple named sandboxes, concurrent
Agent support	OpenCode	Claude Code, OpenCode, Codex, Copilot, others
GPU support	None	Experimental (NVIDIA Container Toolkit)
Kubernetes	None	Experimental Helm chart
TUI	None	Real-time terminal dashboard
Maturity	Fully implemented, single-developer	Alpha (single-player), NVIDIA-backed, rapid iteration

Key Advantages of OpenShell

1. Network Policy Enforcement (primary motivation)

OpenShell's L7 proxy intercepts every outbound connection and enforces allow/deny rules by host, HTTP method, and URL path. Hot-reloadable at runtime. Example:

# GET allowed, POST blocked
curl -sS https://api.github.com/zen              # ✓
curl -sS -X POST https://api.github.com/repos/... # ✗ policy_denied

UF containers currently have unrestricted network access. Building an equivalent L7 proxy with TLS interception, credential placeholder resolution, and seccomp enforcement in Go would be a multi-month effort.

2. Credential Isolation Model

OpenShell never exposes real credentials to the agent process. The agent sees opaque placeholder tokens; the proxy resolves them at request time. If resolution fails, the request is rejected (fail-closed) rather than forwarding a raw placeholder. UF forwards raw API keys into the container environment for non-Anthropic providers.

3. Vertex AI Completeness

OpenShell supports global, us, eu, and regional Vertex endpoints with this hostname logic:

Region value	Vertex host
global	aiplatform.googleapis.com
us or eu	aiplatform.{region}.rep.googleapis.com
Any other	{region}-aiplatform.googleapis.com

It routes Claude through rawPredict and Gemini/others through the OpenAI-compatible endpoint. No gcloud subprocess dependency — manages OAuth2 refresh natively.

UF's gateway rejects global (see internal/gateway/provider.go:203-212), only supports Claude (not Gemini), and depends on gcloud being installed.

4. Multi-Runtime Support

Docker, Podman, MicroVM, Kubernetes vs. Podman-only.

What UF Sandbox Does Better

• Tight workflow integration: uf sandbox start auto-detects providers, auto-starts gateway, integrates with uf CLI
• DevPod backend: IDE-based workflows (VSCode, Cursor, Fleet)
• Simpler setup: Single command vs. multi-step provider + inference + sandbox creation
• Parent directory mounting: Sibling repo access in sandbox
• Stability: Fully tested, non-alpha

Proposed Adoption Path

Phase 1: Evaluation Spike (1-2 days)

• Install OpenShell v0.0.55 locally
• Create a sandbox with OpenCode using Vertex AI provider with global region
• Test network policy enforcement
• Validate rootless Podman on macOS
• Document blockers

Phase 2: Integration Design (spec)

• Design backend: openshell in .uf/config.yaml
• Map uf sandbox commands to openshell sandbox commands
• Define default network policies for Go development workloads
• Translate gateway auto-start to OpenShell provider creation

Phase 3: Implementation

• Add OpenShellBackend implementing the Backend interface in internal/sandbox/
• Wire CLI commands to delegate to openshell binary
• Generate sandbox policies from project context
• Deprecate (but don't remove) direct Podman backend

Phase 4: Gateway Retirement

• Once OpenShell handles all provider/inference scenarios, deprecate internal/gateway/
• Remove gcloud subprocess dependency
• UF becomes thin orchestration over OpenShell for sandbox operations

Open Questions

1. macOS rootless Podman: Does OpenShell handle virtiofs UID mapping issues? UF has specific workarounds (--uidmap probe in detect.go).
2. Distribution model: OpenShell installs via curl | sh. Should UF bundle it, or require it as a prerequisite (like Podman/DevPod)?
3. Default policy allowlist: What should UF's default network policy look like for Go development? (e.g., allow proxy.golang.org, sum.golang.org, github.com, api.github.com)
4. DevPod compatibility: Can OpenShell sandboxes be used as DevPod backends, or are these mutually exclusive?
5. OpenShell stability: Alpha label refers to multi-tenancy aspirations, not single-player stability. But how mature is the macOS Podman path specifically?

References

• NVIDIA/OpenShell — main repo
• OpenShell v0.0.55 release — includes Vertex AI provider
• OpenShell Vertex AI docs — full documentation
• maxamillion/OpenShell vertex-provider branch — Vertex AI implementation commits
• OpenShell architecture — gateway, sandbox, policy engine design
• UF gateway: internal/gateway/ (current Vertex proxy implementation)
• UF sandbox: internal/sandbox/ (current Podman/DevPod backends)
• UF gateway Vertex global rejection: internal/gateway/provider.go:203-212

[jflowers]

Update: Red Hat Engineer's Setup Gist Confirms Operational Maturity

@maxamillion (Adam Miller, Red Hat) — the developer who added Podman rootless support and the Vertex AI provider to OpenShell — published setup instructions for his team:

Red Hat: OpenShell + Podman + Fedora/RHEL Vertex AI Anthropic Quickstart

This changes several assumptions from the initial evaluation.

Key findings

1. Fedora/RHEL-native packaging already exists

sudo dnf copr enable maxamillion/nvidia-openshell
sudo dnf install openshell-gateway openshell

OpenShell is packaged as RPMs in a COPR repo with a systemd user unit for the gateway:

systemctl --user start openshell-gateway.service

This is operationally more mature than UF's current approach (re-exec with sentinel env var + PID file management at .uf/gateway.pid). A persistent systemd user service handles lifecycle, logging, and restart automatically.

2. VERTEX_AI_REGION=global confirmed working in production

The gist uses --config VERTEX_AI_REGION=global directly. This is a Red Hat engineer's actual team setup, confirming that global + rawPredict works in practice — not just in test code. This further validates that UF's gateway rejection of global (internal/gateway/provider.go:203-212) is based on an incorrect assumption about the Vertex AI API surface.

3. End-to-end setup is ~10 commands

# Install
sudo dnf install openshell-gateway openshell

# Start gateway as systemd user service
systemctl --user start openshell-gateway.service

# Register local gateway
openshell gateway add https://localhost:17670 --local

# Enable providers v2 (temporary flag)
openshell settings set --global --key providers_v2_enabled --value true --yes

# Create Vertex AI provider from gcloud ADC
openshell provider create --name vertex-local --type google-vertex-ai \
  --from-gcloud-adc --config VERTEX_AI_PROJECT_ID="${vertex_project}" \
  --config VERTEX_AI_REGION=global

# Configure inference routing
openshell inference set --provider vertex-local --model claude-sonnet-4-6

# Create sandbox
openshell sandbox create --name my-sandbox --provider vertex-local

# Inside sandbox: run Claude Code or OpenCode
ANTHROPIC_BASE_URL="https://inference.local" ANTHROPIC_API_KEY=unused claude --bare
ANTHROPIC_BASE_URL="https://inference.local/v1" ANTHROPIC_API_KEY=unused opencode

Notable details:

• ANTHROPIC_API_KEY=unused — the agent never sees real credentials. The gateway strips this dummy value and injects the real Vertex OAuth token. This is the placeholder credential model in action.
• claude --bare — skips Anthropic OAuth login flow, which would fail inside a sandbox since the sandbox doesn't expose Anthropic auth endpoints.
• --from-gcloud-adc handles the full OAuth2 refresh token flow in one command — no gcloud subprocess dependency at runtime.

Impact on adoption plan

Phase 1 (evaluation spike) is lower risk than initially assessed. The COPR packaging and systemd integration mean OpenShell is already deployed in a Red Hat engineering context, not just as a standalone alpha project.

The integration layer is thinner than expected. UF wouldn't need to reimplement OpenShell's credential model or network policy. The integration would primarily be:

1. Ensure openshell is installed (or install it)
2. Run openshell gateway add once during setup
3. Map uf sandbox commands to openshell sandbox commands
4. Generate --provider and --config flags from UF's existing configuration

macOS remains the key unknown. The gist is Fedora/RHEL-specific. UF's primary development environment is macOS. The Phase 1 spike should prioritize validating macOS + rootless Podman + OpenShell, since that's where UF's existing workarounds live (virtiofs UID mapping probes, host.containers.internal networking, macOS-specific volume mount semantics).