opencode-container/README.md

OpenCode Development Container

This repository provides a Podman-based development container for running an AI coding agent in an isolated and reproducible environment.

The container includes common software development tools, Node.js, OpenCode, Python, Java, Maven, Git, Neovim, and other command-line utilities.

The host project directory and selected development caches/configuration directories are mounted into the container.

Requirements

• Linux
• Podman
• Bash
• A working internet connection when building the image
• CA certificates, if access to internal HTTPS services requires custom CAs

Files

• Dockerfile — builds the development image.
• build.sh — builds or updates the image.
• dev.sh — starts the development container.
• entrypoint.sh — initializes the runtime environment.

Build the image

Run:

./build.sh

The default image is:

localhost/opencode-dev

The build uses the current host UID and GID for the dev user, so files created in mounted directories normally belong to the host user.

Build without cache

./build.sh --no-cache

Update the base image and Ubuntu packages

./build.sh --update

Show the build command without running it

./build.sh --dry-run

Build arguments

The following environment variables can be used to customize the image:

UBUNTU_VERSION=26.04
NODE_VERSION=24.21.0
OPENCODE_VERSION=2.0.3
IMAGE_REPO=localhost/opencode-dev

For example:

NODE_VERSION=24.21.0 OPENCODE_VERSION=2.0.3 ./build.sh --no-cache

Custom CA certificates

Custom CA certificates must be placed in the repository certs/ directory before building the image. See certs/README.md for accepted formats and rules.

This directory is kept in git through a placeholder file, so a fresh clone builds without creating it first.

The Dockerfile copies this directory to:

/usr/local/share/ca-certificates

and runs:

update-ca-certificates

The resulting system CA bundle is also exposed through:

NODE_EXTRA_CA_CERTS=/etc/ssl/certs/ca-certificates.crt

This allows both system tools and Node.js applications to trust the additional certificates.

Important: CA certificates need to be present when the image is built. The runtime container does not install certificates from the host. After adding or removing a certificate, rebuild with ./build.sh --no-cache --update.

Run the container

Run:

./dev.sh

By default, the host directory is:

$HOME/opencode-dev

and projects are stored in:

$HOME/opencode-dev/projects

The container starts in /workspace.

To start in a specific project:

./dev.sh my-project

or:

./dev.sh /path/to/opencode-dev/projects/my-project

Absolute paths outside the projects directory are not accepted as the initial working directory.

Mounted directories

The following host directories are mounted into the container:

Host	Container	Purpose
projects/	/workspace	Source code
opencode-config/	/home/dev/.config/opencode	OpenCode configuration
opencode-data/	/home/dev/.local/share/opencode	OpenCode persistent data
opencode-cache/	/home/dev/.cache/opencode	OpenCode cache
m2/	/home/dev/.m2	Maven cache
npm-cache/	/home/dev/.npm	npm cache
pip-cache/	/home/dev/.cache/pip	pip cache
bash/	/host-bash	Host-provided Bash configuration
$HOME/.gitconfig	/home/dev/.gitconfig	Git configuration

All standard development directories are created automatically by dev.sh.

Additional mounts

Additional host directories can be mounted with --mount.

Example:

./dev.sh my-project --mount "$HOME/other:/extra"

Read-only mounts are also supported:

./dev.sh my-project --mount "$HOME/data:/data:ro"

Multiple mounts can be specified:

./dev.sh my-project \
  --mount "$HOME/data:/data:ro" \
  --mount "$HOME/tools:/tools:rw"

Environment variables

The main runtime paths can be customized:

OPENCODE_DEV_HOME
PROJECT_DIR
OPENCODE_CONFIG
OPENCODE_SHARE_DATA
OPENCODE_CACHE
M2_FOLDER
NPM_CACHE
PIP_CACHE
BASH_FOLDER
IMAGE_REPO

Example:

OPENCODE_DEV_HOME="$HOME/my-opencode" ./dev.sh

Git configuration

The host Git configuration is mounted read-only:

$HOME/.gitconfig -> /home/dev/.gitconfig

If the file does not exist, the script prints a warning and Git uses the container defaults.

SSH configuration and SSH agent forwarding are currently disabled in the script. They can be enabled by uncommenting the corresponding sections in dev.sh.

Security

The container runs with several restrictions:

• Runs as the dev user.
• Uses the host UID/GID.
• Drops all Linux capabilities.
• Uses no-new-privileges.
• Uses a temporary container (--rm).
• Does not run as root.
• Uses the default Podman network.

The project directory is mounted read/write because the AI agent needs to create and modify source files.

Locale

The host locale is passed to the container through:

HOST_LANG
HOST_LC_ALL

The entrypoint generates the requested UTF-8 locale when necessary.

For example, the host locale is automatically passed when running:

./dev.sh

Typical workflow

Build the image:

./build.sh

Start the development environment:

./dev.sh

Or start directly in a project:

./dev.sh my-project

Inside the container, the project is available under:

/workspace

OpenCode can then be started normally:

opencode

The container is removed when the shell exits, while source code, OpenCode data, configuration, and development caches remain on the host.

Customization

Most image versions are defined at the top of the Dockerfile:

ARG UBUNTU_VERSION=26.04
ARG NODE_VERSION=24.21.0
ARG OPENCODE_VERSION=2.0.3

Runtime paths and container options are defined in dev.sh.

This separation allows the image to contain the stable development environment while projects, configuration, caches, and other working data remain outside the container.