Skip to main content
Pre-release

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

oc-box OpenCode 2.x development dashboard with resource cards, workspace inventory and a selected-workspace inspector, using synthetic data

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. Clipboard imports are separately off by default: --host-clipboard saves the Ctrl+Y shortcut enabled for future workspace TUI clients; --no-host-clipboard or preferences --host-clipboard off saves disabled. Existing clients do not live-toggle, and only the shortcut reads the clipboard. 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.249.dev0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for oc-box 1.7.249.dev0
File Size Uploaded Provenance Actions
oc_box-1.7.249.dev0.tar.gz 3.2 MB With provenance Details for oc_box-1.7.249.dev0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for oc-box 1.7.249.dev0
File Interpreter ABI Platform Actions
oc_box-1.7.249.dev0-py3-none-any.whl Python 3 none any Details for oc_box-1.7.249.dev0-py3-none-any.whl

Total release size: 4.2 MB

Release files / oc_box-1.7.249.dev0.tar.gz

Download URL oc_box-1.7.249.dev0.tar.gz
Size 3.2 MB
Tags Source
SHA-256 checksum
How to use checksums
cc4d6e98b52f60bd6ed206300cc2a58b7223faf341fa0e752d814273cfe0b0a9
BLAKE2b-256 checksum
How to use checksums
bf58bb76c19d79de3b66b0cb25c32c73b4089d8a21e652cb853aafc9b545fdf6
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 19, 2026.

Transparency log

Release files / oc_box-1.7.249.dev0-py3-none-any.whl

Download URL oc_box-1.7.249.dev0-py3-none-any.whl
Size 1.0 MB
Tags Python 3
SHA-256 checksum
How to use checksums
dc749aef915441723f8eaba48ae7e1f4a4221212cf77976bc5ef8ed4df4b3063
BLAKE2b-256 checksum
How to use checksums
4bdbf24457c524c4ae78e04782b7c1ca899b719b6a6a99f22a18907391ed1929
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 19, 2026.

Transparency log

Security for oc-box 1.7.249.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.

Select from 2 files

Attestation for oc_box-1.7.249.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 19, 2026.

Transparency log

A 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.

Release history Release notifications | RSS feed

This release
Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page