This release is a pre-release and may not be stable for production use.
oc-box
Persistent rootless Podman development environments for unmodified OpenCode.
Give OpenCode its own Linux environment for tools, packages and services while mounting only your selected project by default. Keep the environment and conversations between visits, without patching OpenCode or replacing its tools.
The main documentation targets OpenCode 2.x. OpenCode 1.x remains supported as legacy, with its own guide.
Get started · OpenCode 2.x docs · Legacy 1.x · Command reference · Security · Contributing
Release channels: stable is the default. The optional dashboard, host-file workflows and other 1.7 development features require explicit opt-in. A merged feature is not necessarily in a published package. Choose a channel · Development features and limitations
The experimental OpenCode 2.x dashboard, captured from the real interface with synthetic read-only sample data. Read the TUI guide.
Why oc-box?
- A persistent development machine per project. Install compilers, SDKs, databases and distro packages inside the container.
- Native OpenCode integrations. MCP servers, formatters and plugins run alongside OpenCode. See the 2.x capability reference for version-specific limits.
- Your choice of Linux. Tumbleweed, Leap, Ubuntu, Debian, Fedora, Arch or Alpine.
- Continuity without starting over. Resume conversations, import host history and rebuild the container OS while keeping the project and private home.
- Explicit resource and hardware choices. Set CPU/RAM/process ceilings and opt in to device access.
Rootless containers are not virtual machines: they share the host kernel, and your mounted project is writable. Read the trust boundary before using oc-box with sensitive projects.
Quick start
Run these commands on the Linux host as your regular user, not inside oc-box and not with sudo.
1. Install
You need Python 3.10+, host OpenCode 2.x, Git, curl, rootless Podman with pasta networking and delegated CPU/memory/process cgroup controllers. Initial setup needs network access. See installation and prerequisites for all methods.
First installation — recommended GitHub path with vault and TUI:
curl -fsSL --proto '=https' --tlsv1.2 https://raw.githubusercontent.com/groopcd/oc-box/master/install.sh | sh -s -- --devel --with-vault --with-tui
oc-box --version
oc-box doctor
This explicitly selects a published development release, because stable does not yet include the dashboard. Dependencies stay private to the GitHub installation. This does not initialize or unlock a vault, change credential policy, launch the dashboard or start a workspace. The command downloads and runs the public installer; review it first if preferred.
Already installed? Use the existing installation, without rerunning curl:
oc-box upgrade --devel --vault --tui # Add both extras and select development
# Or request either extra independently:
oc-box upgrade --devel --vault
oc-box upgrade --devel --tui
These upgrade flags require a launcher release that supports them and a published target supporting the requested extras. On an older channel-aware launcher, upgrade normally first, then request extras. A source merge does not make that release available. Requests are additive: omitted extras are not removed, the same release can gain extras, and repeating a satisfied request is a no-op. The command uses the verified existing installation owner; it does not create a second copy.
Prefer stable without the dashboard, or a Python tool manager? See the installation alternatives. Do not install a second copy just to enable optional features. Genuinely pre-channel launchers have a separate bootstrap compatibility route.
2. Choose how to supply credentials
Existing native OpenCode saved/OAuth authentication remains supported. If your provider or MCP needs environment-variable credentials, initialize the encrypted host vault before the first project launch:
oc-box secrets init
oc-box secrets set ANTHROPIC_API_KEY
Values are entered in masked host-terminal prompts, not command-line arguments. Default V2 workspaces receive all current vault entries on each new owning start; use an explicit credential policy when a project should receive less. Native saved/OAuth auth is independent of the vault.
3. Open a project
mkdir -p ~/devel/demo
oc-box --project ~/devel/demo
Initial setup installs the exact host OpenCode version and baseline development tools. Later launches reuse the container, private home, caches and conversation history. Your project stays at the same absolute path; the container home is a private volume, not your host home.
Exit OpenCode normally to synchronize history and stop the environment. Run the same command to return. Processes do not survive a stop.
Complete first-workspace walkthrough →
Everyday use
| I want to… | Command or guide |
|---|---|
| Resume the current project | oc-box |
| Start another conversation in the same environment | oc-box --new |
| List workspaces | oc-box list |
| Read resource and workspace status | oc-box --status |
| Stop a workspace | oc-box stop --project ~/devel/demo |
| Open the existing V2 session shell | oc-box terminal --project ~/devel/demo |
| Import history, repair identity or rebuild the OS | Manage workspaces |
| Protect a workspace before changing it | Back up and restore |
--status does not start or stop containers. Normal 2.x terminal attachment
requires an existing owner; --maintenance opens a restricted maintenance shell.
For 1.x behavior, use the legacy terminal guide.
Reset/purge have different preservation rules—read the
operation table before using destructive commands.
Explore the development features
These features have separate prerequisites and validation scopes; they are not all included in stable installations.
| Feature | Start here |
|---|---|
| Card-based workspace dashboard, sessions, logs and encrypted backups | Dashboard and concurrent clients |
| Native TUI, browser and persistent session shell together | Client workflows |
| Native TUI image/PDF imports, explicit image broker or live host-file tools | Choose a host-file workflow |
| Shared web tabs and optional browser-selected attachments | Web interface reference |
| Guarded history synchronization and recovery | Workspace history |
Disclosure matters: on supported development TUI clients, host importing is enabled by default. A qualifying path paste authorizes an image/PDF copy without per-file confirmation; disable it with the saved host-drop preference if that is not wanted. Sharing, importing and attachments can disclose data to model providers or history. Compare the workflows and consent rules.
Understand the boundaries
- The agent can modify or delete the mounted project. Rootless isolation does not remove network access or impose a disk quota.
- The container Build agent has broad tool permissions. Plan/child and explicit mandatory-policy boundaries are distinct; see configuration and permissions.
- Delivered credentials are readable by the agent and its tools. The vault protects storage before delivery, not against the recipient.
- The global host vault and outside env files are not included in workspace backups. Preserve the encrypted vault and its passphrase separately.
- Reset, purge and restore are not interchangeable. Restoring a launcher or selecting an older release does not roll back workspace/session state.
Security and reporting · Credentials · Backup boundaries
Documentation
The documentation hub organizes the project by what you need to do, rather than by development chronology.
| Learn or do | Read |
|---|---|
| Install, upgrade, enable extras or set up completion | Installation |
| Launch and return to your first workspace | Getting started |
| Manage environments, sessions, resources and recovery | Workspace guide |
| Supply credentials and choose policies | Credential guide |
| Create, inspect and restore encrypted backups | Backup guide |
| Find every command, option or troubleshooting entry | CLI reference |
| Understand storage, configuration and permissions | Concepts |
| Check OpenCode version compatibility | OpenCode 2.x guide |
| Operate an existing OpenCode 1.x installation | Legacy 1.x documentation |
| Evaluate release readiness and historical evidence | Project status |
Prebuilt man oc-box and info oc-box manuals are included in installations.
See manual locations if your reader does
not find them.
Development status
Development is active. The experimental manager's full restore returned zero
but its later integrity verifier refused manifest; portable UI/storage and
final preservation checks remain unaccepted. Publication does not declare those
gates passed. See current limitations and source-scoped evidence.
Want to contribute? Start with CONTRIBUTING.md and the test strategy. Ordinary offline tests are not live Podman isolation or security acceptance.
License
Copyright (C) 2026 Paulo Dias paulo.miguel.dias@gmail.com. Licensed GPL-3.0-or-later, without warranty. See NOTICE for attribution and acknowledgment of OpenAI coding-assistant contributions through OpenCode. Other invoked programs retain their own licenses.
Metadata
Release files for oc-box 1.7.243.dev0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| oc_box-1.7.243.dev0.tar.gz | 3.1 MB | With provenance | Details for oc_box-1.7.243.dev0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| oc_box-1.7.243.dev0-py3-none-any.whl | Python 3 | none | any | Details for oc_box-1.7.243.dev0-py3-none-any.whl |
Total release size: 4.1 MB
Release files / oc_box-1.7.243.dev0.tar.gz
| Download URL | oc_box-1.7.243.dev0.tar.gz |
|---|---|
| Size | 3.1 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
4bd01d434654cdb64b2e06a0374b37eb7f26886b73c1bbc7b64a9b9430e9e2fd
|
|
BLAKE2b-256 checksum How to use checksums |
58cdf21354b2cd02dc6b9b2a9f8910b5f6b737fc6eaf5d0566e2bc84064fbf94
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 18, 2026.
Transparency logRelease files / oc_box-1.7.243.dev0-py3-none-any.whl
| Download URL | oc_box-1.7.243.dev0-py3-none-any.whl |
|---|---|
| Size | 979.6 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
fb80e84c9b8cd7b5a5ee7d5ab3766fe248d17fc90c2ae129142b4f2fed90017e
|
|
BLAKE2b-256 checksum How to use checksums |
cb86f305dcfea62cdfc28907fbc1f22b19952e2cc4ffe1f6797d7ea0d898f3d4
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 18, 2026.
Transparency logSecurity for oc-box 1.7.243.dev0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for oc_box-1.7.243.dev0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 18, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.