OpenCode in Docker on Ubuntu 24.04: a safe setup step by step

Introduction

This manual runs OpenCode with --auto, so without a single prompt, inside a Docker container on Ubuntu 24.04.

The container sees one git worktree of the project: container/src, the docroot of a PHP site, read-write; the instructions, the docs and container/tools read-only; nothing of your home folder. What the agent breaks, git restores. What it must not read is not there.

The repo layout used here, with the files of the setup; the two images with a language are optional.

The notes on the right say what the agent gets in the container:

site/ your repo ├── AGENTS.md read-only: the rules ├── .claude/skills/ read-only └── container/ ├── src/ read-write: the agent works here ├── docs/ read-only ├── tests/ read-only ├── containerfiles/ │ ├── Dockerfile.opencode the image │ ├── Dockerfile.erlang.opencode the image plus Erlang │ └── Dockerfile.ruby.opencode the image plus Ruby └── tools/ read-only └── ai/ ├── opencode-docker.sh the launcher └── docker/ ├── opencode.jsonc the model ├── CONTAINER.md notes for the agent └── masked an empty file

Step 1: Docker and the OpenCode image

The setup needs Docker on the host and the official OpenCode image in the version of OpenCode you run there: your own image of step 3 (the image) is built on top of it. Check all three:

docker --version

Docker version 29.1.3, build 29.1.3-0ubuntu3~24.04.2

opencode --version

opencode v2.1.4

docker image inspect --format '{{.RepoTags}}' ghcr.io/anomalyco/opencode:2.1.4

[ghcr.io/anomalyco/opencode:2.1.4]

The tag in the last command is the version that opencode --version printed.

If the image is not there, that command prints Error response from daemon: No such image and ends with exit code 1.

Read the article Docker and the OpenCode image to learn how to install Docker, run it without sudo and pull the image.

Step 2: a worktree for the agent

The agent does not work in your repo folder.

It gets a second checkout of the same repo, a git worktree, in a folder next to it. From the repo root:

git worktree add ../site-agent -b agent/alpine-menu

Nothing in your folder changes: not the files, not the branch, not the setup files from the tree of the introduction. There are now two checkouts:

git worktree list

/home/me/github/site 3dc8ba13 [main] /home/me/github/site-agent 3dc8ba13 [agent/alpine-menu]

FolderWho works thereWhat it holds
siteyou; the launcher runs from hereeverything: the setup files, ignored data, your uncommitted edits
site-agentthe agent, in the containerthe tracked files of the last commit

The launcher builds the image and reads the config from your folder, and mounts only the work from site-agent, so the setup files work before they are committed.

Check that nothing ignored is in the worktree. The command prints nothing:

git -C ../site-agent status --short --ignored

One branch per worktree, merged into main

The worktree is on its own branch: you commit to that branch and merge it into main.

Git does not let two worktrees use one branch, so a second worktree on main fails:

git worktree add ../site-claude main

fatal: 'main' is already used by worktree at '/home/me/github/site'

Inside a worktree you can create and switch branches as in any checkout, except to a branch another worktree holds:

git -C ../site-agent switch -c agent/alpine-menu-2

Switched to a new branch 'agent/alpine-menu-2'

git -C ../site-agent switch main

fatal: 'main' is already used by worktree at '/home/me/github/site'

Read the article Two agents: one branch each to learn how two agents work at once, each with its own worktree and branch, and what goes wrong when both work on main.

Step 3: the image

The official image runs OpenCode as root and has none of the programs the skills call: no PHP, no bash, no Python, no Perl.

What it writes into a mounted folder belongs to root on the host.

So you build your own image on top of it, with those programs and a user with your UID.

Its Dockerfile is in container/containerfiles:

vi container/containerfiles/Dockerfile.opencode

Read the section The default image of the image article to see the file line by line and why each line is there.

The script of step 5 (the launcher) builds it at every start.

To build it once yourself and check it:

docker build -t opencode-agent --build-arg HOST_UID=$(id -u) --build-arg HOST_GID=$(id -g) -f container/containerfiles/Dockerfile.opencode container/containerfiles

docker run --rm --entrypoint sh opencode-agent -c 'id; php -v | head -1; bash --version | head -1; python3 --version; perl -v | sed -n 2p'

uid=1000(agent) gid=1000(agent) groups=1000(agent) PHP 8.3.36 (cli) (built: Oct 21 2026 16:38:20) (NTS) GNU bash, version 5.3.9(1)-release (x86_64-alpine-linux-musl) Python 3.14.8 This is perl 5, version 42, subversion 2 (v5.42.2) built for x86_64-linux-thread-multi

The image is 354 MB, 94 MB more than the official one.

A task whose pages need another language gets an image with that language: a second Dockerfile, the same file with one more package.

The setup has two, for Erlang and Ruby, and the launcher picks them with --erlang and --ruby.

Build and check the Erlang one the same way:

docker build -t opencode-agent-erlang --build-arg HOST_UID=$(id -u) --build-arg HOST_GID=$(id -g) -f container/containerfiles/Dockerfile.erlang.opencode container/containerfiles

docker run --rm --entrypoint sh opencode-agent-erlang -c "erl -noshell -eval 'io:format(\"~s~n\", [erlang:system_info(otp_release)]), halt().'"

27

Read the section Another language of the image article to see both files and their checks, and to learn how to write a Dockerfile for another language, with Go as the example.

Step 4: the config and the container notes

mkdir -p container/tools/ai/docker

vi container/tools/ai/docker/opencode.jsonc

{ "$schema": "https://opencode.ai/config.json", // Inside the container only. opencode-docker.sh starts OpenCode with // --auto, which approves every ask; the limit is what the container // holds, not a rule list. "model": "opencode/deepseek-v4.1-flash-free", // Read after AGENTS.md: what differs in the container (no git, read-only // folders, what stays on the host). "instructions": ["CONTAINER.md"] }

AGENTS.md is written for the host. The notes below tell the agent what is different in the container:

vi container/tools/ai/docker/CONTAINER.md

# In the container You run in a Docker container with --auto: every command runs without a prompt. The container holds the tracked files of an agent worktree and nothing else, so these replace some rules of AGENTS.md here: - There is no git and no .git. Search with `grep -rn` or `rg` instead of `git grep`: there are no ignored files here for them to read. - container/src is writable, and so is any path the run was started with `--rw`. AGENTS.md, the skills, container/docs, container/tools and container/tests are read-only otherwise. - Files that read as empty and refuse writes (`*.env`, `*creds*`) are masked: say what should change in them, the edit is made on the host. - There are no credentials here. Test the deploy scripts with `--dry-run` and a dummy creds file in /tmp, never against a real host. - The local site, the tests that need it (`run-tests-venv.sh`) and commits are on the host. Do not try to reach them; list what is left to run on the host at the end of your answer. - Do not run generate-sitemap.sh, even after adding pages: it dates every page by its file time, and here every file has the time of the checkout. The sitemap is rebuilt on the host after the merge. - Scratch files go to /tmp.

Without the notes, the first search of the demo with the free model was git grep, as AGENTS.md says, and it failed with git: command not found.

With them the agent searched with grep -rn straight away and ended with a list of what to run on the host.

The sitemap line came later. After a task that added a course, the agent rebuilt the sitemap, as AGENTS.md says after new pages, and all 4,333 pages that were already there got the date of the checkout.

Step 5: the launcher

You do not start the container with a docker run of your own.

Every command in this manual that starts the agent goes through one script, the launcher container/tools/ai/opencode-docker.sh.

It builds the image, refuses a folder with ignored files, mounts the worktree, masks the secret files, drops every root power and then starts OpenCode with --auto, a shell or the TUI.

Read the article The launcher to see the whole script and what each part does, and to learn how to add a flag of your own.

vi container/tools/ai/opencode-docker.sh

chmod +x container/tools/ai/opencode-docker.sh

The empty file that takes the place of the masked ones:

touch container/tools/ai/docker/masked

How to call it, from the repo root of the main checkout.

Its own options go before the worktree, the options of opencode run after run:

Call or optionWhat it does
container/tools/ai/opencode-docker.sh ../site-agentthe TUI of OpenCode
container/tools/ai/opencode-docker.sh ../site-agent run "<task>"one task, then the container ends
container/tools/ai/opencode-docker.sh ../site-agent shella shell in the same container, as in step 6 (check what the container sees)
--rw <path>one more path writable for this run (when the task is in container/tools: --rw)
--openrouter-key <file>, --opencode-key <file>a key for this run only: an OpenRouter key (a paid model through OpenRouter) or an OpenCode Zen or Go key (keys for one run)
--erlang, --rubythe image with Erlang or Ruby (the image per run: --erlang and --ruby)

Step 6: check what the container sees

The check runs in two places. First, on the host, from the repo root, start the launcher with shell at the end:

container/tools/ai/opencode-docker.sh ../site-agent shell

It starts the same container the agent gets, with the same mounts, but instead of OpenCode it runs sh, the shell of the image. Your prompt changes to:

/work $

You are now inside the container: whatever you type runs there, not on the host.

/work is the folder the worktree is mounted in, and $ instead of # means you are not root.

Second, at this prompt, type the commands from the first column one at a time, press Enter after each, and compare what it prints with the second column:

CommandOutputMeans
iduid=1000(agent)your UID, not root
ls -A ~.ash_history .localno keys, no host configs; .ash_history holds the commands you typed and goes away with the container
ls container/src/services/user_profile/dataNo such file or directoryignored data is not in the worktree
wc -c container/tools/deploy/site.env0masked
echo note >> AGENTS.mdRead-only file systemthe rules stay as they are
touch container/tools/xRead-only file systemthe tools too
git statusgit: not foundno history to read
ls /var/run/docker.sockNo such file or directoryno way out through Docker
apk add curlPermission deniedno new packages
grep CapEff /proc/self/status0000000000000000no capabilities

When every row matches, leave the container shell:

exit

The host prompt comes back, and --rm in the launcher removes the container.

Only the sessions volume stays (what is mounted and what OpenCode can access).

What is mounted and what OpenCode can access

The mount list as the container reports it (grep ' /work' /proc/mounts).

The first five rows come from the worktree, the last three from your repo folder and from Docker:

In /workMode: why
container/srcread-write: the docroot, the work
AGENTS.md
.claude/skills
read-only: the rules and the skills
skill.md
_internal_ai_skill_for_files.md
container/docs
read-only: what the skills point to
container/toolsread-only: the checks the skills run
container/testsread-only: check-reflow.sh reads a test file
opencode.jsonc
CONTAINER.md
read-only: step 4 (the config and the container notes)
tracked *.env, *creds*read-only and empty: the masked file
~/.local/share/opencoderead-write: the sessions, a Docker volume

Not there at all, whatever a command does:

What it can still reach: the internet, which the model needs, and the ports of the host published on 0.0.0.0 (what the container reaches on the network).

container/tools, docs and tests

The skills tell the agent to check its work with the scripts in container/tools.

Mounted read-only from the worktree, they run in the container and cannot be changed.

Tested in the container with the image of step 3 (the image):

ToolIn the container
php -l, CLI render with DOCUMENT_ROOTworks
search/find_article.pyworks
check-sitemap.sh, htaccess_redirects.pyworks
generate-sitemap.shwrong dates: it dates every page by its file time, and in a new worktree every file has the time of the checkout; CONTAINER.md forbids it, and the sitemap is rebuilt after the merge
css/build-css.sh --checkworks
linters/check-reflow.shworks with the tests folder mounted
linters/check-php-header.sh, check-line-endings.shworks with Perl in the image
deploy/deploy-ftp.sh --dry-runworks with a dummy creds file
run-tests-venv.shstops: uv not found; the tests need the local site, so they run on the host
analyze_logs/download-logs.shstops: no creds file, by design

When the task is in container/tools: --rw

A task that fixes or updates a script needs its folder writable.

--rw makes one path writable for one run, and the rest stays read-only:

container/tools/ai/opencode-docker.sh --rw container/tools/deploy ../site-agent run "Add a --quiet option to container/tools/deploy/deploy-ftp.sh and test it with --dry-run."

Which writes work, checked with touch and echo > in the shell, paths under container/:

Write toWorks with
src/xalways
tools/deploy/x--rw container/tools/deploy or --rw container/tools
tools/x--rw container/tools
tools/deploy/site.envnever: masked

Do the tools reveal too much?

A mounted folder goes to the agent, and through it to the model provider, file by file.

Four checks before you mount one, from the repo root of the main checkout.

1. Secrets in tracked files.

git ls-files container | grep -E '\.env$|creds'

Here two files: the deploy settings and an example credentials file.

The launcher masks what this command lists, so a new one is masked too.

2. Tools that read secrets from outside the repo.

git grep -l -E '\.config/|hosting-access|PASSWORD' -- container/tools

The deploy and log download scripts. In the container there is no ~/.config, and they stop before they connect.

3. Tools that read ignored data.

git grep -l -E 'users\.db|access\.log|user_profile/data' -- container/tools

The log analysis scripts. Their databases and logs are ignored, so the worktree has none.

4. Personal data in tracked text.

git grep -c -E '[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[a-z]{2,}' -- container/docs container/tools

Every hit goes to the model with its file.

Here: the site's own address in two scripts, the authors of a bundled image library in its docs, and one personal address in a doc about a local Git server.

Decide whether that one stays in the repo.

No tool had to change. The worktree keeps the data out, the home folder is not mounted, and the masks cover the tracked settings.

What needs care is the other direction: code the agent wrote runs later on the host.

The CLI render, the local site and the tests execute PHP from container/src, and on the host that PHP runs as you, with your home folder.

Let the agent render in the container, as in the demo with the free model, and on the host run these checks only after the review and merge on the host.

Review and merge on the host

From the repo root of the main checkout:

git -C ../site-agent status --short

git -C ../site-agent diff

find ../site-agent/container -type l

Then the tests against the local site, which the container cannot run.

Commit in the worktree with explicit paths, then merge from the main checkout:

git -C ../site-agent add container/src/linux/_linux_menu_inc.php

git -C ../site-agent commit -m "Adds Alpine to the distributions of the Linux section"

git merge agent/alpine-menu

If the task added or removed pages, rebuild the sitemap now, in the main checkout, where every file has its real time.

The script keeps the old sitemap as sitemap.xml.bak-<time> next to it; that copy is not for the commit:

container/tools/generate-sitemap.sh

git add container/src/sitemap.xml

git commit -m "Adds the new pages to the sitemap"

Remove the worktree and its branch:

git worktree remove ../site-agent

git branch -d agent/alpine-menu

More pages of this manual

The rest of this manual is on pages of its own:

Day to day usage: start a task, a task from a file, the image per task, send an update while it runs, stop, continue, read the report again and merge.

Demo: a real task with the free model: one task from the command to the change in the worktree.

Two agents: one branch each: two agents at once, a merge conflict, and both on main.

Claude Code as supervisor: Claude Code gives the task to OpenCode in Docker, reviews it on the host and sends fixes into the same session.

A paid model through OpenRouter: a key of its own for the container, passed to one run.

A stored login: what it is, how to find out if there is one, how to use it, make one or remove it.

The network: what the container still reaches, and how to close the local site.

Can container/src itself be the volume?: the worktree, the main checkout or a named volume.

Problems met on real tasks: what went wrong on the first real tasks, and what to do instead.

Docker and the OpenCode image: step 1 (Docker and the OpenCode image) in full.

The image: step 3 (the image) in full, with Erlang, Ruby and another language.

The launcher: step 5 (the launcher) in full, with the script, its options and how to add a flag.

Select the model: where the model of a task comes from, the free OpenCode model, and an OpenCode Go or OpenRouter model for one run or for every run.

Checklist

Article author: Klavdiya Kondakova