When I first introduced oc-box, the goal was simple: give OpenCode a Linux environment it could freely modify without turning my host machine into its playground.
Since then, the project has grown beyond a container launcher. The latest release, v0.1.27, adds encrypted credential storage, per-project credential selection, improved recovery, easier installation, and better tools for understanding what is running.
The guiding principle remains the same: keep OpenCode on mainline, preserve its integrations, and make the development environment replaceable without losing the work.
A development environment the agent can actually use
Restricting an AI coding agent is useful, but development often requires installing packages, trying SDKs, running services, and changing configuration.
oc-box runs unmodified OpenCode inside a persistent rootless Podman container, alongside its MCP servers, formatters, language servers, plugins, and development tools.
The agent can install what the project needs inside that environment. The selected project directory stays available at the same path, including Git history, untracked files, and unfinished edits.
You can choose Tumbleweed, Leap, Ubuntu, Debian, Fedora, Arch, or Alpine. The container also matches the host’s installed OpenCode version, avoiding a separate fork or independently drifting client.
Credentials: encrypted storage without breaking the existing workflow
One of the biggest additions is an optional integrated credential vault.
My original workflow—sourcing an environment file before launching OpenCode—still works and remains the default. Upgrading does not introduce a password prompt or silently change credential forwarding.
For users who want encrypted storage, the vault uses AES-256-GCM and a memory-hard Scrypt key derivation function, provided by the maintained cryptography library.
Each workspace can explicitly select which credentials it receives, either from the sourced environment, the vault, or a combination of both.
The passphrase stays on the host. Workspace metadata stores selected credential names, not their values.
There is an important distinction here: the vault protects credentials at rest and before delivery. Once a credential is supplied to an unrestricted development container, its processes can access it. Encryption is not a substitute for scoped tokens and thoughtful access boundaries.
Small usability changes matter too
Typing a long token into a completely blank prompt is surprisingly error-prone.
Credential entry now shows masked characters and a live character count. Ctrl+R lets users deliberately show or hide a secret value while editing it. Each field starts masked, and vault passphrases cannot be revealed.
The prompt also supports cursor movement, deletion, paste handling, and cancellation with terminal restoration.
It sounds like a small feature, but making the secure path usable is part of making it practical.
Persistent work, recoverable environments
Containers should be disposable. Conversations and unfinished work should not be.
oc-box preserves installed tools and sessions between ordinary launches. It can import an existing host OpenCode conversation, continue it inside the container, and synchronize conversation archives back to the host on exit.
A reset rebuilds the container OS while retaining the project, private home, conversation history, and session IDs. System packages need reinstalling, but the development work remains.
Recent recovery improvements also address changed directory identities and missing workspace markers. The launcher detects ambiguous associations instead of silently creating duplicate environments. Generic Linux filesystem interfaces provide persistent identity where supported, with explicit repair when continuity cannot be verified.
Better visibility and maintenance
The command set now includes:
- Resource reporting: CPU, RAM, limits, processes, uptime, and separate project/container storage usage.
- Maintenance terminals: enter an existing container without launching OpenCode or forwarding host credentials.
- GPU/NPU passthrough: persistent device settings, with checks for common host permission and SELinux problems.
- Self-upgrades: GitHub-based updates, with optional automatic checks before normal launches.
Installation is also available through pipx and uv, alongside the original curl/source path. Each installation channel keeps its own appropriate upgrade mechanism.
Tested, documented, and still evolving
The latest release passes 266 regression tests on Python 3.10 and 3.13, with additional mainline integration, package-installation, documentation, and secret-scanning checks.
The project includes a complete CLI reference, man page, GNU Info manual, and documented security boundaries. It is GPL-3.0-or-later and developed with disclosed AI assistance.
Rootless containers still share the host kernel, and the mounted project remains writable. The value is a controlled, persistent development workspace—not an absolute security guarantee.
Source and documentation: github.com/groopcd/oc-box
PyPI: pypi.org/project/oc-box
I’d welcome feedback from people using different distributions, MCP setups, and hardware—particularly around making powerful AI development environments easier to manage without hiding their tradeoffs.
Leave a Reply