opencode-containerized

calendar May 12, 2026 · 3 min read · Computer Software AI  ·
Share on: linkedin copy

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

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

Target Description
help Show available targets
setup Initialize host directories
build Build container image
opencode Run opencode in restricted container
shell Enter container shell
rebuild Rebuild container image (no cache)
clean Remove container image

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/:

Host Path Container Path Contents
~/.opencode-containerized/home-dev/ /home/dev Entire home directory (dotfiles, Nix profile, configs, cache)
~/.opencode-containerized/nix/ /nix Nix store (derivations, packages)
Current working directory (via script) /home/dev/workspace/<relative-path> Your project files

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 Nix and persisted on the host, so the container image does not need to be rebuilt. To update to the latest version:

1make shell
2nix profile upgrade opencode

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