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
- ../site-agent is the new folder, next to the repo folder.
- -b agent/alpine-menu is a new branch for the task, made from the last commit and checked out in that folder.
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]
| Folder | Who works there | What it holds |
|---|---|---|
| site | you; the launcher runs from here | everything: the setup files, ignored data, your uncommitted edits |
| site-agent | the agent, in the container | the 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
- Commit first. The worktree starts from the last commit. Uncommitted edits and untracked files, new docs included, stay in the main checkout.
- You commit in it as in the main checkout. It shares the history, the branches and the git hooks of the repo, and any path can be committed in it, container/tools as well as container/src. The commits go to its branch, and git merge in the main checkout brings them to main (review and merge on the host).
- Ignored helpers are not in it either: the .venv of the tests, the node_modules of the CSS build, the images. Run what needs them in the main checkout, after the merge.
- Your uncommitted edits can block the merge. If they touch a file the branch changed, git merge stops with Your local changes to the following files would be overwritten by merge.
- One worktree per task. After the merge it is removed (review and merge on the host), and the next task starts from the new main.
- Only folders of it are mounted, never its root. The .git file there holds the path of the main repo.
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"] }
- No permission list. Under --auto every ask becomes an allow. The limit is the mount list of the script in step 5 (the launcher).
- The model is the current free OpenCode model, the first choice of this setup: it needs no key, so the container holds no key. A free tier may keep what it is sent: mount only what you are ready to send. Read the article Select the model to learn how to check which model a task uses, and how to switch to an OpenCode Go or OpenRouter model.
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 option | What it does |
|---|---|
| container/tools/ai/opencode-docker.sh ../site-agent | the 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 shell | a 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, --ruby | the 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:
| Command | Output | Means |
|---|---|---|
| id | uid=1000(agent) | your UID, not root |
| ls -A ~ | .ash_history .local | no keys, no host configs; .ash_history holds the commands you typed and goes away with the container |
| ls container/src/services/user_profile/data | No such file or directory | ignored data is not in the worktree |
| wc -c container/tools/deploy/site.env | 0 | masked |
| echo note >> AGENTS.md | Read-only file system | the rules stay as they are |
| touch container/tools/x | Read-only file system | the tools too |
| git status | git: not found | no history to read |
| ls /var/run/docker.sock | No such file or directory | no way out through Docker |
| apk add curl | Permission denied | no new packages |
| grep CapEff /proc/self/status | 0000000000000000 | no 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 /work | Mode: why |
|---|---|
| container/src | read-write: the docroot, the work |
| AGENTS.md .claude/skills | read-only: the rules and the skills |
| skill.md _internal_ai_skill_ container/docs | read-only: what the skills point to |
| container/tools | read-only: the checks the skills run |
| container/tests | read-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/ | read-write: the sessions, a Docker volume |
Not there at all, whatever a command does:
- .git and the whole history, deleted files included.
- Ignored files: visitor records, logs, databases, backups.
- Untracked files and your uncommitted edits.
- Your home folder: ~/.ssh, ~/.config, and the auth.json and sessions of OpenCode on the host.
- The Docker socket and the rest of the disk.
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):
| Tool | In the container |
|---|---|
| php -l, CLI render with DOCUMENT_ROOT | works |
| search/ | works |
| check-sitemap.sh, htaccess_redirects.py | works |
| generate-sitemap.sh | wrong 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 --check | works |
| linters/ | works with the tests folder mounted |
| linters/ | works with Perl in the image |
| deploy/ | works with a dummy creds file |
| run-tests-venv.sh | stops: uv not found; the tests need the local site, so they run on the host |
| analyze_logs/ | stops: no creds file, by design |
- A script that writes into its own folder fails on a read-only mount: point its output to /tmp or into container/src.
- The .venv of the host does not work here. It is not tracked, and Alpine uses musl instead of glibc. Tools that need more than the Python standard library run on the host, or their packages go into the image.
- Another folder goes into ro=( ) of the launcher.
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 to | Works with |
|---|---|
| src/x | always |
| tools/deploy/x | --rw container/ |
| tools/x | --rw container/tools |
| tools/deploy/ | never: masked |
- Masked files stay masked. The agent can neither read nor change them; it says what should change, and you make that edit on the host.
- No credentials in the container. The container notes of step 4 (the config and the container notes) send the agent to --dry-run with a dummy creds file in /tmp. Tested: dry-run: no connection, nothing uploaded.
- The review is stricter. A deploy script runs on the host with your real credentials. Read every line of its diff before the first real run: a new host, a URL, curl, wget, nc, base64 or eval is a stop.
- --rw AGENTS.md or --rw .claude/skills lets the agent rewrite its own rules: only for a task about them, and read the diff.
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
- New files are not in git diff until they are added; status lists them with ??.
- Symlinks. The last command must print nothing. A link to ~/.config/… points to nothing in the container, and to the real file on the host, where an upload script or an editor follows it.
- .htaccess line by line: it decides what the site serves.
- PHP that reads files or opens connections, and every script changed under --rw: every line.
- A changed sitemap.xml or a new sitemap.xml.bak-… means the agent rebuilt the sitemap anyway. Restore the one and delete the other: git -C ../site-agent restore container/src/sitemap.xml
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
- docker.io and docker-buildx installed, you are in the docker group.
- The image tag matches opencode --version of the host.
- Committed first; the worktree check with --ignored prints nothing.
- The config names the current free OpenCode model, or a paid model with a key made for it.
- The shell of step 6 (check what the container sees) shows the mounts, the masks and no capabilities.
- --rw only for the path the task changes.
- The local site and every other local service published on 127.0.0.1.
- After the run: status, diff, no symlinks, then the checks on the host; commit, merge, the sitemap if pages were added, remove the worktree.
- Before the commit: the worktree up to date with main, and no other agent working in the main checkout (main moved on while the agent worked, another agent in your folder while you commit).
Article author: Klavdiya Kondakova