blog: isolate your AI agents with uf sandbox — containerized OpenCode sessions via Podman

[jflowers]

Suggested Blog Post

Title

Isolate Your AI Agents with uf sandbox — Containerized OpenCode Sessions via Podman

Narrative Arc (per content pack BA-001)

Problem: AI coding agents run with full access to the host filesystem. A destructive command, a corrupted git history, or a runaway process affects the real project. There is no isolation boundary between the agent's workspace and the engineer's files. If the agent runs rm -rf / or git push --force, the damage is real and immediate.

Approach: uf sandbox wraps the entire OpenCode + Unbound Force toolchain in a Podman container. One command replaces 4 manual steps. The engineer's project directory is mounted read-only by default — the agent works on a copy inside the container. Changes come out only through a reviewed git format-patch extraction, giving the engineer a chance to inspect every line before it touches the real repo.

Evidence / Walkthrough: Walk through the round-trip workflow:

1. uf sandbox start — show the prerequisite check, platform detection output, health check dots, TUI attachment
2. Run /unleash inside the sandbox — the agent works normally, commits changes
3. uf sandbox extract — show the patch summary, review prompt, git am application
4. Show that the host repo now has the changes with commit history preserved

Include actual terminal output (screenshots or code blocks) from each step.

Conclusion + CTA: The blast radius of any agent mistake is now contained to a disposable container. Start using it: brew upgrade unbound-force && uf sandbox start.

Key Messages (per BA-007, VB-007 — lead with benefit)

• "Your repo is untouchable" — isolated mode mounts read-only. The agent cannot modify your files.
• "One command, not four" — uf sandbox start replaces: check Ollama, build podman run flags, wait for server, opencode attach.
• "Review before apply" — uf sandbox extract shows you every change before it reaches your repo. You approve or decline.
• "Works on Mac and Fedora" — auto-detects arm64/amd64, SELinux :Z flags, Ollama connectivity. No platform-specific flags needed.

Sections to Include

1. The Problem (2-3 paragraphs)

   • Agents with full filesystem access
   • Real-world risk scenarios (accidental deletion, force push, corrupted state)
   • Why existing solutions (careful prompting, git stash) are insufficient

2. The Solution: uf sandbox (1-2 paragraphs)

   • One-command containerized sessions
   • Two modes: isolated (default, read-only mount) and direct (read-write)

3. Walkthrough (the bulk of the post)

   • Prerequisites: Podman, Ollama, API key
   • uf sandbox start — what happens step by step
   • Working inside the sandbox — it's a normal OpenCode session
   • uf sandbox extract — the round-trip
   • uf sandbox status, stop, attach — lifecycle management

4. Security Model (table)

   • Rootless Podman, read-only mounts, no push credentials, resource limits, SELinux, non-root user

5. Google Cloud / Vertex AI Users (short section)

   • GOOGLE_CLOUD_PROJECT and VERTEX_LOCATION forwarded
   • Service account key file auto-mounted
   • gcloud ADC fallback

6. Current Limitations (per VB-004 — be honest)

   • Single container at a time
   • Requires Podman (not Docker)
   • Health check timeout is fixed at 60 seconds (no --timeout flag)
   • No concurrent sandbox sessions

7. What's Next (brief)

   • CDE / Eclipse Che integration (Discussion #88)
   • Reference the containerfile repo for custom images

Content Pack Compliance Notes

Rule	How to comply
BA-001	Narrative arc: problem → approach → walkthrough → CTA
BA-002	Title states topic (uf sandbox) + value (isolate agents)
BA-003	Include actual terminal output from each step
BA-004	No "recently" or "new" — use version number (v0.12.0 or whatever ships)
BA-005	Self-contained — explain Podman/containers briefly for readers from search
BA-007	Lead with "your repo is untouchable" not "we added a sandbox command"
VB-002	No "simply run" or "just start"
VB-004	Current Limitations section — be honest about single container, no Docker
VB-007	Every feature stated as a benefit ("one command" not "new subcommands")
FA-001	All commands verified against shipped binary

References

• PR #93: unbound-force/unbound-force (implementation)
• Spec 028: specs/028-sandbox-command/
• Discussion #88: CDE and Podman architecture
• Manual test script: temp/uf-sandbox-manual-test.md (22 tests for verification)
• Content pack: .opencode/uf/packs/content.md (BA + VB rules)

[jflowers]

Update: CDE Is the Primary Workflow

The original blog outline focuses on the local Podman workflow (uf sandbox start → extract → apply). After further design (see Discussion #88 update and Issue #95), the framing should be updated:

CDE (Eclipse Che / Red Hat Dev Spaces) is the primary workflow, not just Podman. The iterative demo loop — /unleash → demo → /speckit.clarify → repeat — works best in a persistent Che workspace where there is no extract/recompile cycle between iterations.

Suggested Blog Structure Update

The post should present two workflows, with CDE first:

1. The Tight Loop (CDE) — Primary

• Persistent workspace survives across sessions
• Engineer reviews demos inside Che IDE (terminal tab, browser tab, API endpoints)
• Engineer runs slash commands via opencode attach from host
• Feedback via /speckit.clarify → /unleash resumes in same workspace
• No extraction, no recompilation, no context loss

2. The Extraction Loop (Local Podman) — Fallback

• Ephemeral container for engineers without Che/Dev Spaces
• uf sandbox extract → review → git am
• Works but requires extract/compile/demo cycle per iteration

Key Message Update

The current key messages focus on isolation. Add:

• "Iterate without leaving the workspace" — CDE keeps your agent's context, compiled binaries, and Dewey index alive between demo iterations. No re-orientation.
• "Demo where you build" — CLI in the terminal tab, web app in a browser tab, API via curl — all inside the Che IDE. No uf sandbox extract needed.

Architecture Diagram to Include

Show the dual access path: opencode attach (TUI on host) + Che IDE (browser) both pointing to the same persistent workspace. This is the visual that communicates why CDE matters.

Current Limitations Update

Add to the limitations section:

• CDE backend (--backend che) not yet implemented (tracked in #95)
• Requires a running Eclipse Che or Red Hat Dev Spaces instance
• Ollama endpoint must be a K8s service or external URL in CDE (not host.containers.internal)