opencode-containerized

A containerized development environment for OpenCode, running inside an isolated Docker container with Nix, tmux, and a curated set of development tools.

Overview

This project provides a reproducible, restricted container that runs OpenCode with all its dependencies. All state (Nix store, OpenCode config, shell settings) is persisted on the host via bind mounts, making the container image minimal and stateless.

Prerequisites

• Docker
• Docker Compose

Quick Start

Initialize host directories, build the image, and run OpenCode:

1make setup
2make build
3make opencode

Or enter the container shell directly:

1make shell

Usage

Via symlink (recommended)

Create a symlink to the helper script so you can invoke it from any directory. Your current working directory will be mounted into the container automatically under /home/dev/workspace/<relative-path>, preserving the directory structure relative to your home. This allows multiple project sessions to run in parallel without conflicts.

1ln -s "$(pwd)/bin/opencode-containerized" ~/bin/opencode-containerized

Now you can run containerized OpenCode from any project directory:

1cd ~/my-project
2opencode-containerized

Example: ~/projects/web-app mounts to /home/dev/workspace/projects/web-app inside the container.

Via Makefile

Container Contents

The image is based on Debian stable-slim and includes:

• apt packages: curl, git, tmux, vim-nox, ripgrep, silversearcher-ag, build-essential
• A non-root dev user

Nix and OpenCode are installed on first run and persisted on the host.

Persistent Data

All state is stored on the host under ~/.opencode-containerized/:

First Run

On first container start, an entrypoint script automatically:

1. Installs Nix (rootless)
2. Configures Nix flakes
3. Sets up shell environment (.bashrc, .bash_aliases)
4. Installs OpenCode via Nix

This takes 1-3 minutes depending on network speed. Subsequent runs are instant since all state is persisted.

Updating OpenCode

OpenCode is installed via its official install script and persisted on the host, so the container image does not need to be rebuilt.

Fresh Install (first run)

On first container start, the entrypoint automatically runs the OpenCode install script, which fetches the latest stable release. No action needed — you always get the latest stable out of the box.

Upgrade Existing Install

If you already have OpenCode installed (from a previous first-run), upgrade to the latest stable release from inside the container:

1opencode upgrade

Or via the Makefile target from the root of the cloned opencode-containerized repository on your host machine:

1make upgrade-opencode

The container image is not rebuilt — only the persisted OpenCode binary is updated.

Updating Debian and System Packages

The Debian base image and apt-installed packages are baked into the container image layers. To update them, rebuild the image:

1make rebuild

This pulls the latest debian:stable-slim base and reinstalls all packages at their current versions. Your persisted data in ~/.opencode-containerized/ (Nix store, OpenCode config, dotfiles, and project files) is stored in bind-mounted volumes and is not affected by rebuilding the image.

Security

The container runs with reduced privileges:

• Non-root dev user
• no-new-privileges security option enabled
• All capabilities dropped

Codeberg

This project is on Codeberg: photonsphere/opencode-containerized