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.

Run OpenCode, MCP servers, formatters, plugins, and development tools together inside a container, with native language servers on OpenCode 1.x. Give the agent control of that environment while exposing only your selected project directory by default.

Copyright (C) 2026 Paulo Dias paulo.miguel.dias@gmail.com. Licensed GPL-3.0-or-later; see NOTICE for attribution and the acknowledgment of OpenAI coding-assistant contributions through OpenCode.

1.7 development channel (explicit opt-in): the series adds the optional Textual manager, temporary live host-file tools and guarded exit-history recovery, and retains the private-memory and Ubuntu CI fixes from 1.6.60. Stable 1.6.94 remains the default and does not include the manager. Development releases use 1.7.N.dev0; their publication does not declare unfinished dashboard restore/storage acceptance passed. See the channel guide and 1.7 release notes and known limitations.

Why oc-box?

oc-box grew out of wanting OpenCode to have more freedom without giving it unrestricted access to the host. A Bubblewrap-based host sandbox is useful for restricting commands, but installing system packages and experimenting with services can mean working around host restrictions. oc-box gives OpenCode its own persistent Linux development environment, where it can install tools, change system configuration, run services, and experiment.

The practical advantages for that workflow are:

  • Install what the project needs: compilers, SDKs, databases, and distro packages live inside the container rather than changing the host system.
  • Keep integrations working: OpenCode itself, MCP servers, formatters, and plugins run together inside the same environment. OpenCode 1.x also runs native language servers; upstream 2.2.6 does not provide native LSP.
  • Choose the project's distro: Tumbleweed, Leap, Ubuntu, Debian, Fedora, Arch, or Alpine, with dependencies specific to that project.
  • Pick up where you left off: installed tools, project files, and conversations persist. Run oc-box again to resume, or import an existing host OpenCode conversation and continue it inside the container.
  • Recover a broken environment: rebuild the container OS while retaining your project, private home, conversation history, and session IDs.
  • Control resources and hardware: set CPU/RAM/process ceilings and explicitly pass through GPU/NPU devices when the project needs them.

OpenCode stays on mainline without patches, and the container matches the host's installed OpenCode version. The goal is a more capable, replaceable development environment. Rootless containers still share the host kernel, and the mounted project remains fully writable; see SECURITY.md for the boundary and tradeoffs.

Requirements and installation

  • Linux, Python 3.10+, rootless Podman with pasta networking.
  • Delegated CPU, memory, and process cgroup controllers.
  • A host OpenCode 1.x or 2.x installation (2.x support requires oc-box 1.5+). Integration checks use 1.19.5 and 2.2.6; see 2.x compatibility.
  • Git on the host for installation from GitHub and self-updates; curl for the one-line installer.
  • Network access for initial image, package, and plugin downloads.

Check installed tools and get feature-specific installation commands:

oc-box doctor
oc-box doctor --feature private-output
oc-box doctor --feature backup --feature vault
oc-box doctor --feature backup-info --json

Missing optional dependencies identify the affected feature without disabling unrelated commands. A configured V2 vault requires crypto support and fails closed if it is missing; without a vault, env-file compatibility launches remain available. Native OpenCode saved/OAuth credential refresh and copying remain independent in every mode. Missing age on Tumbleweed suggests sudo zypper refresh && sudo zypper install age; Ubuntu/Debian use apt, Fedora dnf, Arch pacman, and Alpine apk. Commands are for the OS running doctor, not the workspace image. See the host dependency table for all seven distros and the distinction from automatically installed workspace tools. Doctor does not install packages, unlock secrets, start Podman, or change workspaces. Inside oc-box it reports container prerequisites only; run from the host terminal for host advice.

V2 launches need Linux anonymous-memory file support even with --no-vault. Older uv-managed Python builds without os.memfd_create use a compatible libc fallback; see private capture troubleshooting.

Install on the host as your regular user, without sudo. Choose an installation method; a new installation defaults to the stable release channel:

Method Install Update
pipx — isolated CLI from PyPI pipx install oc-box pipx upgrade oc-box
uv — isolated CLI from PyPI uv tool install oc-box uv tool upgrade oc-box
pip — inside an activated virtual environment python -m pip install oc-box python -m pip install --upgrade oc-box
GitHub — published stable/devel releases One-line installer below oc-box upgrade

Development is an explicit opt-in, not moving branch HEAD. Existing saved channel choices are retained. See update channels for upgrade --devel, --stable, nonmutating previews and older-launcher bootstrap.

Install from PyPI

For a standalone command, pipx keeps oc-box in its own Python environment:

pipx install oc-box
pipx ensurepath
oc-box --version

For the recommended V2 global vault workflow from your first project launch, install pipx install 'oc-box[vault]' or uv tool install 'oc-box[vault]' instead. The GitHub installer accepts sh -s -- --with-vault. Then initialize/populate the vault before launching the project, as shown below; no per-project registration is required. Standard installs do not automatically install the extra.

Alternatively, use uv's tool manager:

uv tool install oc-box
uv tool update-shell
oc-box --version

Open a new terminal if the tool manager has just added its bin directory to PATH. Both methods install published releases from pypi.org/project/oc-box.

For standard pip, create and activate a dedicated virtual environment first:

python3 -m venv ~/.venvs/oc-box
. ~/.venvs/oc-box/bin/activate
python -m pip install oc-box
oc-box --version

Use the activated environment or ~/.venvs/oc-box/bin/oc-box on later visits. Podman, host OpenCode, and Linux setup remain external requirements. There is no need for sudo pip or a system/user-site pip installation.

Install from GitHub or source

The one-line installer selects a published stable release by default, or reuses the saved GitHub channel:

curl -fsSL --proto '=https' --tlsv1.2 https://raw.githubusercontent.com/groopcd/oc-box/master/install.sh | sh

This downloads and runs the public installer; it trusts the published GitHub source. To inspect it first, download install.sh, review it, and run sh install.sh. The channel-aware bootstrap resolves the published release and verifies its tag/commit against the selected channel branch. Git fetches full history anonymously into a temporary directory for the accurate commit count. It does not use or save your GitHub/provider tokens.

Alternatively, install an explicitly reviewed source checkout (this installs that source, not necessarily a published release):

git clone https://github.com/groopcd/oc-box.git
cd oc-box
python3 install.py
oc-box --version

Upgrade PyPI installations

PyPI and GitHub are installation methods, each supporting stable/devel release choices. Direct package-manager updates remain available:

pipx upgrade oc-box
uv tool upgrade oc-box
# Inside the installation's virtual environment:
python -m pip install --upgrade oc-box

Channel-aware oc-box upgrade delegates to the verified pipx, uv tool or dedicated virtual environment owning the running CLI; unrecognized/custom installations receive manual guidance. It never uses the GitHub installer for a package-owned CLI or creates a competing launcher. Editable source installations must update their checkout separately. Package auto-update stays disabled; GitHub auto-update is opt-in. If both methods are installed, check command -v oc-box. Public development versions use 1.7.N.dev0; oc-box --version also records +gHASH for source provenance. Ordinary package installs still select stable unless prereleases are explicitly requested. Published PyPI releases are selected separately from ordinary GitHub commits. Packaged manuals are in the package's docs/ and the tool environment's share/man/share/info; those directories may need explicit reader paths.

Experimental workspace dashboard

The experimental development channel adds an optional Textual manager, separate from OpenCode's native conversation TUI:

oc-box tui
oc-box tui --workspace WORKSPACE_ID --read-only
oc-box tui --demo

Its seven tabs are Status, Settings, Sessions, Terminals, Logs, Storage, and Backup/restore. The first five shortcuts remain unchanged; 6 and 7 open the new tabs. Log search stays available across tabs (Ctrl+L opens Logs), including when follow is paused. Browsing never starts, resets, syncs, or unlocks a workspace. Native V2 session connections/actions are explicit; a host Connect may start the native host service, while workspace connections lease only an existing private owner. Compact aligned meters and fixed-scale CPU/RAM histories distinguish unavailable readings from zero. Status/followed-log refresh defaults to one second, with any whole-number interval from 1–60 seconds and no overlapping queries. Sessions stay an on-demand snapshot: background refresh does not reset table scrolling or selection. Delayed session queries show animated, source-specific progress and explicit cancellation; failed actions show fixed, actionable notifications rather than raw native errors. Lost acknowledgements leave the outcome unverified, not falsely reported as unchanged. s or F2 opens grouped, session-only dashboard settings with Apply, Cancel and Reset to defaults; these preferences cannot weaken CLI --read-only mode. Visible text is drag-selectable throughout the dashboard, including logs, graphs and control labels; releasing the mouse copies the selection immediately without activating the control. Graph bars use copyable text glyphs. There are no Copy/Paste buttons: Ctrl+Shift+C repeats a selection copy, Ctrl+Shift+Y copies the visible screen, and F1 explains the shortcuts. Paste copied (Ctrl+Shift+Insert) uses only text copied inside this dashboard; use your terminal's normal paste command for the desktop clipboard. Clipboard actions are explicit and never journal text. Embedded terminals are experimental and reuse the native persistent-session shell, not a new container shell. Storage management distinguishes host native session trees, one workspace, and all registered workspaces; there is no whole-host database wipe or unreviewed bulk removal. Reviewed workspace removal preserves project files and host history. Backup/restore supports existing encrypted full/ portable workspace archives and encrypted native session-tree history, with path-first controls, private masked prompts inside the dashboard, named stages, elapsed time and fresh-ID restoration. Optional recipient/identity controls live under Advanced; ordinary password backups need no key-file copying. Backups and restores do not silently overwrite existing files or start restored workspaces. CPU/RAM limit edits, quotas, resizes and storage moves remain deferred; resource settings are informational.

After a development package has been published, explicitly allow prereleases and opt in to the dashboard and, optionally, the independent vault extra:

uv tool install --prerelease allow 'oc-box[tui,vault]'
# Or: pipx install --pip-args='--pre' 'oc-box[tui,vault]'
oc-box tui --read-only

A channel-aware GitHub bootstrap accepts sh install.sh --devel --with-vault --with-tui (piped suffix: sh -s -- --devel --with-vault --with-tui). Vault support is independent and optional. Dependencies stay isolated; GitHub updates retain supported opt-ins in private releases. These instructions do not claim that the currently published stable PyPI package contains the dashboard.

Switching to --devel does not enable the TUI extra for the first time. If oc-box tui reports “Optional TUI dependencies are missing” after a GitHub upgrade, follow the first-time GitHub TUI setup. Do not install a second pipx/uv copy merely to repair the GitHub installation.

An ordinary installed launcher is appropriate for unrelated projects. To manage the oc-box checkout itself, run a non-editable isolated package from that checkout instead of --with-editable launcher code in the mounted project:

uv run --no-project --with '.[tui]' python -I -m oc_box tui

Keep the trusted-path validation enabled; see the self-workspace launch explanation. Normal mode requires a regular-user host TTY. Synthetic-only --demo uses fixed sample data and permits container preview without host service/registry/log access or actions. Demo and offline checks are not a new interactive/Podman host acceptance pass. The owner approved an experimental development release with the incomplete UI acceptance disclosed, not a stable manager release. A full restore returned 0, but a later integrity verifier refused manifest; portable/storage completion and final preservation/journal checks remain unaccepted. See the manager guide and manager release notes for the complete limitations, keys, source-specific actions and stable gate.

OpenCode 2.x shared clients

For plain host opencode --standalone outside oc-box, the original V1 plugins are not automatically adapted. The opt-in host plugin migration utility audits and ports known plugins to direct V2 implementations in your normal host configuration, retiring obsolete V1 workarounds. A separate compatibility profile is still optional. These are source-checkout tools, not installed oc-box commands; real host sandbox enforcement requires its documented acceptance checks. Plain host opencode --standalone uses the host's normal environment/auth and does not access the oc-box vault. It is not an oc-box flag; oc-box continues to own a private foreground V2 service per active workspace.

While a V2 workspace is running, open its same session from another host terminal:

oc-box web --project ~/devel/demo
oc-box terminal --project ~/devel/demo

The web UI and session shell terminal reuse the existing service/credentials without ending the TUI session. Web access is host-loopback-only with a native one-use pairing link; keep its foreground command open. The owner waits for attached clients before final sync/stop. Ctrl-] detaches from the session shell, preserving it for reattachment; exit closes that shell. terminal --maintenance retains the restricted shell, and 1.x retains its previous terminal behavior. See the V2 client guide.

Temporary live host-file access (experimental)

Share a specific outside folder or screenshot from a second host terminal:

oc-box share ~/Pictures/Screenshots --project ~/devel/demo

Read the disclosure warning and type share. OpenCode gets temporary list_directory, read_file, and read_image tools with a unique server name printed by the command. Reads are live and read-only; there is no mount, container restart, saved configuration, or clipboard access. Keep the command open; Ctrl-C ends further reads. This requires a running V2 workspace and its experimental client-MCP API. It does not expose a path to shell commands.

Shared data may be sent to a model provider or retained in history/copies. Read-only and later disconnect do not undo disclosure. Hidden files and future additions to a shared folder are included; prefer a single file when possible. See share for confirmation, protected-path refusals, size limits and lifecycle details. Its 37-check scripted host acceptance belongs to the earlier exact 5573965 source and native 2.2.6, not automatically to every later development build; see the evidence scope.

V2 conversation archives

History synchronization includes paginated root, fork, archived, and child/subagent conversations at the workspace's exact internal project directory. Each remains a separate host archive; parent/fork provenance is informational metadata, not restored permissions or native parent links. Missing sources retain their last archives without blocking later conversations. Automatic resume stays root-only.

Incomplete inventories, unsettled exports, and unverifiable imports leave sync pending rather than claiming success. Final owner shutdown checks native activity for up to 30 seconds after client leases drain; normal cleanup still stops the container on failure. Archives are mirrors, not bidirectional working copies or full backups of pending input and live execution. See the sync reference.

In 1.7, eligible V2 shell-only timeouts can trigger one bounded persisted-history snapshot after the old owner closes and a whole-container stop is verified. The same existing container restarts temporarily for an isolated history reader, without normal runtime preparation, credential refresh or requested model/tool execution, then stops again. Explicit stop intent suppresses recovery. Even when snapshots are saved, the original timeout remains nonzero and warns that work or completion notices may be missing; native job rows are not repaired. Unsafe or unsupported cases remain pending. See the recovery notes and validation scope.

An interrupted V1 assistant can remain unfinished after migration even when later turns have completed. In an inactive session, sync mirrors native OpenCode's export without those superseded assistants and records only their omitted count in archive metadata. An unfinished tail, running shell/compaction, or active superseded-assistant case stays pending; other sessions can still synchronize.

Stable v1.6.58 records reviewed external history/readiness, global-vault and V1/V2 lifecycle reports, including the migrated superseded-assistant correction. This is a reconciliation with the published release notes, not a fresh review of its raw reports or acceptance of the later Textual manager or post-stop recovery. Each integrated release must meet the final-source gates in the 1.7 publication checklist. Earlier reports do not validate a later revision; see test evidence and release boundaries.

Bash completion

Enable command and option completion in your current Bash shell:

source <(oc-box completion bash)

Add that line to ~/.bashrc after your PATH setup to enable future shells; this works with uv, pipx, and GitHub installations. GitHub/source installs also install an autoload file under ~/.local/share/bash-completion/completions/oc-box for hosts with the bash-completion framework enabled. Python packages ship the same script in their private environment. See the completion reference for autoload setup and paths. Completion includes command-specific options, distros, doctor features, and file/directory paths; it never queries Podman or unlocks credentials.

GitHub installation layout

The GitHub/curl installer copies the launcher to ~/.local/share/oc-box and creates ~/.local/bin/oc-box. Add that bin directory to PATH if needed. The default CLI requires no third-party Python/npm dependencies or documentation build tools; vault/TUI support is an explicit optional install. The installer stages a complete versioned copy under ~/.local/share/oc-box/releases/, then atomically switches the launcher. Existing sessions keep their original code until they exit; earlier installed copies are retained, not removed while they may be in use. For the first migration from an older flat installation, exit its active oc-box launchers before reinstalling. The pinned-release guarantee applies afterward.

Upgrade from GitHub

oc-box upgrade --check       # Preview the saved channel; do not change it
oc-box upgrade               # Install a published release from that channel
oc-box upgrade --devel       # Explicitly opt in and remember development
oc-box upgrade --stable      # Return to stable; warns if this downgrades code
oc-box upgrade --auto-update on
oc-box upgrade --auto-update off

oc-box upgrade --devel selects the development release, not every optional feature. If the GitHub installation has never enabled the dashboard, rerun the bootstrap on the host as your regular user:

curl -fsSL --proto '=https' --tlsv1.2 https://raw.githubusercontent.com/groopcd/oc-box/master/install.sh | sh -s -- --devel --with-tui --with-vault
oc-box tui

Keep --with-vault if you use the encrypted vault; otherwise omit it. This adds dependencies privately to the installed release, without resetting workspaces or deleting history. Later upgrades to TUI-supporting releases retain that opt-in.

Automatic updates are opt-in. When enabled, normal installed oc-box starts check the saved GitHub release channel before opening a workspace, install a changed version, and continue with the same arguments. Network/update failures print a message and continue with the installed version. There is no background daemon or update during an active session. Informational commands, maintenance terminals, reset/purge, and direct source-checkout launches do not perform automatic checks.

Upgrades replace only the installed launcher/modules/manuals. They do not pull into or change a source checkout, reset containers, delete workspaces, touch provider credentials, or change the host OpenCode version. A locally installed version newer than the channel release is retained unless an explicit channel switch selects an older release. That switch changes program files, not workspace/session state; it is not a rollback. --check saves nothing. No GitHub token is required; updates use the fixed public HTTPS upstream without global Git config, helpers, hooks, or forwarded environment secrets. Release identity checks are not a signed release or reproducible-build scheme; see SECURITY.md. Old pre-channel 1.7 launchers require the channel-aware bootstrap, not unsupported new flags; exact v1.6.60 needs one plain upgrade first. See bootstrap compatibility.

Quick start

For OpenCode 2.x, install vault support using the extra above (or curl --with-vault), then store credentials on the host before the first launch:

oc-box secrets init
oc-box secrets set ANTHROPIC_API_KEY
oc-box secrets set MCP_API_KEY
mkdir -p ~/devel/demo
oc-box --project ~/devel/demo

Values/passphrases are entered only in masked host-terminal prompts. V2 without an explicit workspace credential policy uses all current global vault entries on each new owning start/reset/import/web; no project registration or selection is needed. Use provider/MCP {env:NAME} references, never literal secret values in JSON; see the published V2 configuration examples. Without a vault, the same project launch retains env-file fallback and offers concise setup guidance, without automatic installation or config/JSON-secret import. An initialized empty vault unlocks and delivers no entries. V1's legacy env-file default is unchanged. Native OpenCode saved/OAuth credential refresh/copy remains independent in every credential mode, including global vault mode. Explicit workspace env/selected policies remain overrides.

On Tumbleweed the default image is registry.opensuse.org/opensuse/tumbleweed:latest. Initial setup installs Node/npm, Python/uv, Bash, Git, curl, ripgrep, PDF tools, and the exact host OpenCode version. Named startup stages show progress. Subsequent launches reuse the container, dependency caches, files, and last saved conversation.

Your project is mounted writable at the same absolute path. A private named volume provides the container home: it has your home pathname but is not your host home. You can install more system packages inside the container.

Exit OpenCode normally to synchronize conversation archives to the host and stop the environment. Running the same command resumes the original container session; stopped processes must be restarted.

Common commands

oc-box                              # Create/resume in the current directory
oc-box --new                        # New conversation, same environment
oc-box list                         # Workspace table and latest session IDs
oc-box --status                     # CPU, RAM, storage, state, limits, sessions
oc-box --status --project ~/devel/demo --json
oc-box tui --read-only              # Experimental optional workspace dashboard
oc-box distros                      # Supported images and host default
oc-box stop --project ~/devel/demo
oc-box terminal --project ~/devel/demo # V2 session shell; V1 maintenance shell
oc-box terminal --maintenance --project ~/devel/demo # Clean maintenance shell
oc-box sync --project ~/devel/demo   # Retry host history sync after a crash
oc-box repair --project ~/devel/demo # Accept a verified directory identity change
oc-box reset --project ~/devel/demo --cpus 8 --memory 16g
oc-box start --project ~/devel/demo --no-vault # One owning V2 compatibility launch
oc-box purge --project ~/devel/demo  # Remove environment; retain source files
oc-box --about
oc-box upgrade --check

--workspace ID selects a registered workspace from any directory. It also allows cleanup after a project directory was deleted. --status does not start or stop containers and can run while OpenCode is active.

Persistence and deletion

Operation Project and unfinished edits Private home/session IDs Container OS
Exit or stop Kept Kept Kept, stopped
sync Kept Kept; host archive refreshed Kept, stopped
terminal (V1/maintenance) Kept Kept; no history sync Kept, prior run state restored
terminal (V2 attach) Kept Shared current session Kept; owner controls stop
reset Kept Kept Rebuilt
purge Kept Deleted Deleted
purge --all Deleted Deleted Deleted

Reset removes system packages and files outside the project/private home. Home-installed dependencies, Git history, and session IDs remain. CPU/RAM/process limits and device mappings are create-time settings in oc-box; changing them for an existing container requires reset, not purge. CPU and RAM limits are ceilings, not reservations. Defaults are 4 CPU cores, 8 GiB RAM, and 2048 processes.

Purge asks for an ID-prefix confirmation. --delete-sessions additionally deletes recorded host archive copies; --all includes that action and deletes the project directory. Shared image caches and unrelated resources remain.

Maintenance and debugging

After exiting the workspace's OpenCode client, enter its existing container:

oc-box terminal --maintenance --project ~/devel/demo
# Or, from another directory:
oc-box terminal --maintenance --workspace WORKSPACE_ID

This opens a clean interactive shell at the project path, with the same mounts, devices, limits, and rootless permissions. Type exit or Ctrl-D to leave. A container started by this command is stopped on exit; one already running is left running. No OpenCode launch, configuration refresh, dependency install, session import/sync, or environment recreation occurs.

Host tokens, API keys, custom pass_env, proxies, and agent variables are not forwarded. The shell's environment is cleared, startup files are skipped, and history persistence is disabled. Credentials already stored in the container's files or held by its other processes remain accessible: a maintenance shell is not isolation from the existing container. It requires a real terminal and the workspace's exclusive lock, so exit an active OpenCode launcher first.

Directory recovery and duplicate detection

Clearing host ~/.cache does not delete workspace registrations or private session volumes. Workspace identity uses generic Linux VFS interfaces, not filesystem-specific tools or branches: the canonical path and marker select the workspace, while the filesystem ID, opaque persistent directory handle, and inode verify its identity. Device numbers can change after reboot without changing the directory; a matching recorded stable baseline accepts that change automatically. The same algorithm is used for ext4, XFS, Btrfs, bcachefs, ZFS, and other drivers that expose these capabilities. It also works when the private oc-box registry is on a different filesystem from the project.

Existing registrations are upgraded at a normal verified launch, or by repair. If an old registration already has a device-number mismatch and no stable baseline, it needs one explicit repair: an unchanged inode alone cannot prove the filesystem is the same. Driver/kernel support varies: filesystems that do not provide a usable persistent handle/filesystem ID retain the conservative device/inode check and explicit repair when it changes. There is no universal physical-directory identifier on every Linux filesystem. Relying on only a UUID marker would accept copied/restored directories indistinguishably, so oc-box does not claim that as replacement detection. Install the updated launcher before the next reboot, then normally resume each healthy workspace to record its baseline. No container reset or session import is needed.

For a genuine or unverifiable identity change, keep the marker and use oc-box repair after checking the project and stopping its launcher. If the marker is missing, the launcher detects existing registrations instead of silently creating a duplicate:

oc-box --status
oc-box repair --workspace WORKSPACE_ID
oc-box --workspace WORKSPACE_ID --resume

Repair restores a missing marker or accepts the current identity while retaining the container, settings, and session IDs. It never replaces another workspace's marker. If several records reference the same path, select the intended ID. list/status distinguish identity changes, missing markers, and marker mismatches, with specific recovery or cleanup guidance.

For a stale duplicate left by an older launcher, first recover any needed work, then run plain oc-box purge --workspace STALE_ID, without --all or --delete-sessions. It leaves the current project/marker and host histories intact and retains private archive provenance under the state directory's retired/ folder. This is saved recovery data, not a third active workspace.

Continue an existing host session

Exit the host OpenCode client first, then import once:

oc-box --project ~/devel/demo --import-session ses_HOST_SESSION_ID

The source session must belong to that project. oc-box saves a private recovery export, verifies the imported transcript, and resumes the same session ID. Your original host conversation is unchanged. Later launches need no import flag. See session recovery for retry behavior. The same flag can recover an oc-box host archive into a fresh environment after its marker was replaced; keep the original registry and saved history export. After plain purge with a current launcher, the retained private retired/ provenance can verify the old host archive instead. Older already-purged records cannot be reconstructed automatically; the imported live session is unaffected.

Select a distro or map hardware

oc-box --project ~/devel/demo --distro ubuntu
oc-box reset --project ~/devel/demo --distro fedora
oc-box reset --project ~/devel/demo --device /dev/accel/accel0
oc-box reset --project ~/devel/demo --podman-arg=--shm-size=1g

Choices: Tumbleweed, Leap, Ubuntu, Debian, Fedora, Arch, and Alpine. Distro and device settings persist per workspace. Repeat --device/--podman-arg for multiple settings; clear old values with --clear-devices/--clear-podman-args. Podman arguments are literal long-option tokens, not shell snippets.

Rootless device access may require crun with --group-add=keep-groups, host ACLs, and SELinux's container_use_devices setting. oc-box checks these prerequisites and prints advisory warnings before device-enabled creation. See device troubleshooting for exact host commands; oc-box never changes host policy automatically.

Integrations and permissions

Global OpenCode configuration, skills, agents, plugins, MCP settings, and auth are copied into private storage at startup. MCPs, formatters, and language servers run natively inside the container. Host-only executables must be installed there too. Changes to host configuration apply on the next launch.

On V2, ordinary copied Build/global tool permission rules are overridden by the existing final Build-agent wildcard, including their configured denies, as before. Final permission asks for the actual container Build agent are auto-allowed without prompting, but explicit session/mandatory-policy denials and managed-rule denials applying after the private overlay remain denied. Unknown-agent requests retain native ask/deny outcomes and are never treated as Build. All non-Build/Plan/child rules and V1 behavior are unchanged. The existing Bubblewrap plugin is disabled for the container launch. HTTP service endpoints using localhost in global config are mapped to host.containers.internal, including the host Lemonade endpoint. Plain host OpenCode retains its normal configuration and permissions.

The V2 helper changes only a final ask to allow, never a deny passed to it: an explicit event agent wins, otherwise it resolves the current session's agent and then the native configured default, never the parent's agent. A Build parent does not grant allowances to Plan/child requests. Session permission arrays are not overwritten; question and MCP elicitation prompts remain separate and may still need input. The final private OPENCODE_CONFIG_CONTENT overlay reenables only the generated Build helper against lower-priority project plugin removals; managed policy still wins. oc-box clients receive no --auto or client-wide autoaccept setting. New native evaluator/import/reload fixtures are offline checks, not accepted live host permission validation.

If you explicitly want native V2 ask autoapproval for a one-off host launch, opencode --auto --standalone is an optional choice, using normal host env/auth and not the oc-box vault. It approves asks, not explicit denials, including plain host configured denies. The already- running TUI equivalent is Ctrl+P → Open settings → Sessions → Permissions → autoaccept (cli.json session.permissions); that broader preference can persist and is not enabled by oc-box. Do not use a global all-agent client setting as a substitute for oc-box's container Build-only default. New live interactive TUI permission-prompt/reload validation remains pending. The separate scripted rootless-Podman global-vault fixture has passed native Build tools, scoped permission checks and reload; see its accepted scope in the V2 guide.

V2 without an explicit credential policy is global vault-first: when the host vault is present, all current entries replace ambient automatic token/API-key and pass_env forwarding, including legacy OPENCODE_AUTH_CONTENT overrides. Ordinary native OpenCode saved/OAuth credential refresh and copying continue in every mode: vault env entries do not replace structured OAuth refresh-token records. V1, an explicit env override, or a V2 launch without a vault retain legacy env forwarding; selected mode restricts credential names. Delivered credentials remain readable by the agent/tools, and copied config/auth may already contain secrets. Global use deliberately exposes every stored entry to each default V2 workspace; use selected mode when a project should receive less. Forwarded vault values never enter Podman argv, host os.environ, config or registry. The vault/passphrase are never mounted into the container.

Read SECURITY.md for the trust boundary and reporting guidance. Rootless containers share the host kernel, have network access, and do not have a disk quota. Snapshots/archives are not backups against disk or volume loss.

Global V2 vault and explicit workspace credential overrides

V2 defaults to global vault-first without an explicit workspace policy. This includes existing V2 workspaces with no policy; saved env/selected policies remain intentional overrides. V1 retains its legacy env-file default. Global mode uses all current entries on each normal new owner, including the first launch, rather than saving a frozen automatic name list. Additions/removals and updated values apply on the next new owner, not to attached TUI/web/session-shell clients.

For encrypted storage on the host, enable the optional vault support:

# New isolated Python-tool installation:
pipx install 'oc-box[vault]'
# Existing pipx installation:
pipx inject oc-box 'cryptography>=44'
# Or uv (install/reinstall with the extra):
uv tool install --force 'oc-box[vault]'
# GitHub/source installer:
python3 install.py --with-vault
# Or one-line GitHub installer:
curl -fsSL --proto '=https' --tlsv1.2 https://raw.githubusercontent.com/groopcd/oc-box/master/install.sh | sh -s -- --with-vault

The GitHub option installs cryptography in the versioned launcher's private runtime directory using a temporary virtual environment; it never installs packages into system Python or user site-packages. GitHub upgrades preserve this opt-in. There is no password-manager daemon or desktop keyring requirement; the host needs a controlling terminal and normal private Unix file permissions, including under WSL. Do not put the vault on an exposed project mount or a Windows-shared path that cannot enforce those permissions.

Create the vault and store secrets before your first V2 project launch through interactive masked prompts (names only in argv). Global use needs no per-project registration, exit/configure/relaunch step, or selection command:

oc-box secrets init
oc-box secrets set ANTHROPIC_API_KEY
oc-box secrets set MCP_API_KEY
oc-box secrets set PERSONAL_GITHUB_TOKEN
oc-box secrets set BRAVE_API_KEY
oc-box secrets list            # Unlocks; prints names, never values
oc-box secrets remove OLD_TOKEN
oc-box secrets passwd          # Change the vault passphrase

When no vault exists, default V2 launches keep the env-file fallback and concise setup guidance. They do not automatically install crypto, create a vault, modify config, or import JSON secrets. An empty initialized vault still unlocks and delivers no vault entries, with guidance to run oc-box secrets set NAME. A present corrupt vault, wrong passphrase, or missing crypto support aborts before container setup/reset deletion, without silently falling back. OpenCode's native saved/OAuth credential refresh and copying remain independent in every mode, including global vault mode. A vault containing only a search API key does not disable an existing Copilot OAuth account. Vault env entries do not replace structured OAuth refresh-token records, and no plaintext OpenCode JSON secrets are imported or rewritten. Existing copied/container auth/config values remain independent; no revocation is implied.

Typing/pasting shows * characters and a live character count. At secret value and confirmation prompts, press Ctrl+R to switch between masked and visible input; each prompt starts masked. Vault passphrases always stay masked and cannot be revealed. Use Backspace/Delete and arrow/Home/End keys to correct input, Ctrl+U to clear, Enter to accept, or Ctrl+C to cancel. Bracketed multiline/control-character or oversized pastes are rejected rather than silently truncated. The input field scrolls horizontally for long values.

Revealed text is cleared when leaving the prompt, but explicitly showing a key can expose it in terminal recordings, screenshots, scrollback/reflow, or screen sharing. Masked feedback reveals length, not content. There is still no plaintext value command-line argument, saved history, or change to the encrypted format.

The host vault is normally ~/.local/share/oc-box/credentials/vault.json ($XDG_DATA_HOME/oc-box/credentials/vault.json when set), outside project and container storage. Credentials and their names are encrypted with AES-256-GCM; Scrypt derives the key from a passphrase (default minimum 8 characters). The private file is 0600 and its directory 0700. There is no saved key, unlock cache, passphrase environment variable, plaintext export, or recovery mechanism for a forgotten passphrase. Back up the encrypted vault and keep its passphrase safe.

Set separate minimum lengths in ~/.config/oc-box/config.json (or its XDG equivalent), retaining any existing settings:

{
  "vault_min_passphrase_length": 12,
  "backup_min_passphrase_length": 16
}

Both default to 8 and accept integers from 8 to 1024; passwords can be longer than the selected minimum, up to 1024 UTF-8 bytes. Override for one operation with oc-box secrets init --min-passphrase-length 8, oc-box secrets passwd --min-passphrase-length 8, or oc-box backup ... --min-passphrase-length 8. These rules apply to new/changed passwords; existing vaults/backups still unlock with their original passwords.

As an intentional override, select only the credentials an existing workspace needs, after exiting its active launcher. These commands do not start/reset a container or read values:

oc-box credentials --project ~/devel/demo
oc-box credentials --project ~/devel/demo --credential-mode selected \
  --clear-credentials --vault-secret PERSONAL_GITHUB_TOKEN --vault-secret BRAVE_API_KEY
oc-box --project ~/devel/demo

Selected mode replaces automatic _TOKEN/_API_KEY and custom pass_env forwarding with those explicit names. It permits mixing sourced environment credentials and selected vault entries, but not selecting the same name from both. Normal owning start/reset/import/web prompts once to unlock selected vault names; the passphrase and vault file never enter the container. A missing selected env variable, wrong passphrase, or missing vault entry aborts before container setup or reset deletion. terminal, list/status, repair, stop, upgrade, and explicit history sync never unlock the vault. Delivered credentials are still environment variables accessible to OpenCode, its tools, and other permitted processes.

Selections persist in the host registry as names only, independent of the project and vault. Repeating options appends names; replace them with --clear-credentials. The accepted modes are env, selected, and vault. Vault mode uses all current entries, refuses nonempty per-name selections, and does not save an automatic list. To switch an old selection back to global V2:

oc-box credentials --project ~/devel/demo --credential-mode vault --clear-credentials

For a deliberate persistent legacy env override:

oc-box credentials --project ~/devel/demo --credential-mode env --clear-credentials

Env mode can also add selected vault names without restricting existing env forwarding. A selected vault value wins over an inherited same-named env value in that mode. Switching mode does not remove old secrets from the private home, copied OpenCode auth/config, raw Podman --env settings, other running processes, source files, session history, swap, or backups. The vault protects storage before delivery; it does not hide a delivered key from the agent. See the complete credential reference and security notes before migrating sensitive credentials.

V1 with saved vault mode returns to legacy env forwarding without unlocking all-global entries; explicit old env/selected vault selections still work as before. V2-only --no-vault skips vault entries for one owning start/reset/web invocation, without saving policy. Global mode uses legacy env forwarding for that invocation; explicit env/selected modes retain their env constraints. Attached clients reject it and never unlock/refresh. Information, maintenance, sync, backup/restore, credential management and other unrelated commands reject the flag too. For one-off env-file compatibility only:

. ~/.config/provider-credentials.env
oc-box --project ~/devel/demo --no-vault
# Or plain host OpenCode, which never consumes the oc-box vault:
opencode --standalone

Sourcing a file is not the recommended primary V2 workflow. The next normal oc-box owner uses its saved/default policy again.

Backup and restore

Version 1.0.0 adds encrypted full and portable workspace backups. Both modes passed the disposable Linux host/rootless-Podman fixture, including project/Git edits, private-home database bytes, session IDs, internal paths, rootless ownership, and stopped restores. See the validation details.

Install the optional host age package (provides age and age-keygen). Then exit the source workspace's OpenCode launcher and keep host editors/builds idle:

# Complete project, private home/session DB, registry evidence, and OS image:
oc-box backup --project ~/devel/demo --output /backup/demo.ocbox
# Smaller backup; rebuild the distro OS on first restored launch:
oc-box backup --project ~/devel/demo --portable --output /backup/demo-portable.ocbox
# Both prompt for a masked backup passphrase, separate from the credential vault.
oc-box backup-info /backup/demo.ocbox
oc-box restore /backup/demo.ocbox --project ~/devel/demo-restored

Backups are always encrypted with the standard age format. Project/home/registry archive and image bytes stream directly into encryption; only ciphertext is temporarily staged. Native age public recipients can replace the passphrase for unattended backups using --recipient age1...; restore/info use the matching private --identity FILE. The host-wide credential vault is not included; back up its encrypted file separately and retain its own passphrase. Outside env files are excluded too; files inside the project are ordinary project data.

Restore is non-overwriting and creates fresh workspace/container/volume IDs. It preserves conversation IDs, full live database/subagent history, source/Git edits, private home, and resource/credential modes and names-only policies. A restored default/global V2 workspace uses the restoring host's current vault, not the original vault or old host privileges. It keeps the old in-container project/home paths and maps the new host project there, rather than rewriting database paths. Thus the host directory may move while the agent still sees the original internal path. It leaves the new container stopped; devices and extra Podman settings are recorded but not activated. Reconfigure required hardware explicitly. Full backups keep the OS image; portable restores need system packages reinstalled. Compatible CPU architecture is required.

The initial format refuses extra bind mounts/volumes and nested project mounts, does not copy ACLs/xattrs/SELinux labels, and is not a running-process checkpoint. Source symlinks are stored, not followed. Restores reject path traversal, device nodes/FIFOs, duplicate paths, hardlink/symlink escapes, unbounded archive metadata, and elevated permission bits. Previously stored credentials/auth/history are included in private home/project/OS files: treat the encrypted backup and its key as sensitive. Deleting a backup does not revoke those credentials.

See backup commands and limitations and host fixture validation.

Documentation

The complete CLI reference covers every command and option, including defaults, examples, persistence, crash recovery, expected failures, configuration, resource metrics, and troubleshooting. The channel guide explains stable/devel selection.

The installer includes prebuilt man and GNU Info pages:

man oc-box
info oc-box

If local documentation directories are not searched automatically:

man "$HOME/.local/share/man/man1/oc-box.1"
info --file "$HOME/.local/share/info/oc-box.info"

Readers are host packages (man and info on openSUSE). See CONTRIBUTING.md to regenerate the manuals from docs/cli.md. Development oc-box --version uses 1.7.N.dev0+gHASH; a final stable release uses no .dev0. The 1.5, 1.6 and 1.7 series retain N's original 1.0.0 baseline (full-history commit count minus 29), so commits continue advancing N automatically rather than restarting at zero. Installed copies retain their source version until upgraded or reinstalled. Existing 0.1/1.0/1.5/1.6 installations upgrade through their usual channel; no workspace reset or history migration is needed for the version-series change.

Development status

The project is under active development. Tumbleweed host/container launch, warm resume, host-session import, MCP connection, and mapped NPU access have been exercised. The automated mainline test uses temporary databases and local model/MCP/LSP/formatter fixtures; it does not prove Podman isolation or certify every distro/runtime/device combination. The earlier selected-vault probes and separate full scripted global-vault run on 1.5.38+g0611104 remain accepted at their documented scopes. Reviewed new-layout host reports now also pass global-vault/Build/full restore on clean 1.6.42+ge66fb39, and selected-vault V1/V2 full/portable restore, reset and downgrade/return on 1.6.43+ge06896f. The latter changes only delegation instructions from 1.6.42; keep their execution versions distinct. These are synthetic scripted host tests, not new interactive UI acceptance, real-provider inference or real-project backups. See the test strategy.

A separate operator-observed run on clean 1.6.44+ga043049 now accepts the bounded native Build TUI/resize, browser/persistent-shell coexistence, detach/reattach, independent web closure and owner lease-drain workflow. It uses synthetic credentials and --no-vault, not interactive vault/Plan/reload testing, real-provider inference or a real-project backup. Keep this interactive evidence separate from the scripted lifecycle reports above.

Focused scripted vault-edge host checks also passed on clean 1.6.46+gacddbd8: live/new-owner entry removal, initialized-empty/absent vaults, and wrong-password, corrupt-vault and genuinely missing-crypto refusals for start/reset with protected state retained. All ten case reports passed. This provider-free run adds no inference, backup, OAuth-refresh or interactive-UI claim.

A separate image-free shared home-component probe passed on clean 1.6.48+g7df5074: measured rootless UID/GID 0/1, modes/content, source preservation and matching destination fingerprints through the production encrypted stream. All six checks and 30 audited hashes agree. This is component evidence, not a new per-kind container lifecycle or first-mount pass.

Runtime code lives in src/oc_box/, with tests/tools/docs in their conventional top-level directories. Root installer/build entrypoints remain for compatibility. Run the source CLI without installing into project/system/user Python:

uv run --no-project --with-editable . oc-box --version
uv run --no-project --with-editable . --with cryptography python -B -m unittest discover -s tests -v
python3 -B tests/smoke_mainline.py
python3 -B tools/build_docs.py --check

Other invoked programs retain their own licenses. oc-box is provided without warranty under the GPL; see LICENSE and NOTICE.

Metadata

Release files for oc-box 1.7.173.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.173.dev0
File Size Uploaded Provenance Actions
oc_box-1.7.173.dev0.tar.gz 1.5 MB With provenance Details for oc_box-1.7.173.dev0.tar.gz

Built distribution (wheel)

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

Total release size: 2.4 MB

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

Download URL oc_box-1.7.173.dev0.tar.gz
Size 1.5 MB
Tags Source
SHA-256 checksum
How to use checksums
318abd0dc8b8649c9f55fcfbe7ba34ffe60623f4c96d152de5ea0f929f9d59bd
BLAKE2b-256 checksum
How to use checksums
0fb389cef3dd1655d0d601c9910d4ebd89adc0f5f185aa770f83eef51809ac4d
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 16, 2026.

Transparency log

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

Download URL oc_box-1.7.173.dev0-py3-none-any.whl
Size 802.4 kB
Tags Python 3
SHA-256 checksum
How to use checksums
3e276911528178f06ca3467ebea988c56a75055a11b1449ffbecf1c63deaeb0a
BLAKE2b-256 checksum
How to use checksums
437c3122ec70ce0a26f625a0a59e5a115815246221a98441530ebae018154904
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 16, 2026.

Transparency log

Security for oc-box 1.7.173.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.173.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 16, 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