If you want to give your coding tool maximal freedom but you fear for the safety of your computer (you should), then letting it run in a Docker container is a good idea. If your coding tool goes rogue, it only damages your Docker container, which you can restore in an instant rather than destroying your work computer.

I will show you how to

• build a Docker image based on Ubuntu with Opencode and necessary tools installed and configured
• authenticate your LLM for Opencode and use this auth in your Docker container
• mount your local Opencode config files into your container (agents, plugins, …)
• bundle all of that in a bash script for quick access

I assume you have Docker Desktop installed and running. I also assume you are working on a coding project and have it checked out locally using git.

Create a Dockerfile in your coding project

First, you need to create a Dockerfile describing your container.

Let’s walk through it step-by-step.

# Start from the latest official Ubuntu release
FROM ubuntu:latest

# Set common environment variables
ENV DEBIAN_FRONTEND=noninteractive

# Install core tools
RUN apt-get update && apt-get install -y --no-install-recommends \
    # Core utilities needed for setup and the curl install script
    wget \
    vim \
    ca-certificates \
    curl \
    unzip \
    gnupg \
    sudo

We need to be able to interact with GitHub:

# Install GitHub CLI (gh)
 RUN curl -fsSL https://cli.github.com/packages/githubcli-archive-keyring.gpg | gpg --dearmor -o /usr/share/keyrings/githubcli-archive-keyring.gpg \
    && echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/githubcli-archive-keyring.gpg] https://cli.github.com/packages stable main" | tee /etc/apt/sources.list.d/github-cli.list > /dev/null \
    && apt-get update \
    && apt-get install -y gh \
    # Clean up APT lists
    && rm -rf /var/lib/apt/lists/*

Time to set up the local user in our container and enable it to connect to the GitHub servers:

# Add the 'ubuntu' user to the sudo group and allow passwordless sudo
RUN usermod -aG sudo ubuntu \
    && echo "ubuntu ALL=(ALL) NOPASSWD: ALL" > /etc/sudoers.d/ubuntu \
    && chmod 0440 /etc/sudoers.d/ubuntu

# Set the existing non-root 'ubuntu' user as the default user
USER ubuntu

# Set the working directory to the user's home folder
WORKDIR /home/ubuntu

# 1. Create the .ssh directory
RUN mkdir -p /home/ubuntu/.ssh

# 2. Add GitHub to the known_hosts file so git commands work non-interactively
# We use ssh-keyscan to fetch GitHub's public key and save it.
RUN ssh-keyscan github.com >> /home/ubuntu/.ssh/known_hosts

Next, we enable OpenCode to use the local config you have on your work computer inside the container. This will give it all the agents, plugins, etc you have configured locally:

# Create the directory structure for the auth file and fix ownership
# This prevents Docker from creating it as 'root' when the volume is mounted.
# This is important to be able to mount the OpenCode auth on docker run
#    -v ~/.local/share/opencode/auth.json:/home/ubuntu/.local/share/opencode/auth.json
RUN mkdir -p /home/ubuntu/.local/share/opencode \
    && chown -R ubuntu:ubuntu /home/ubuntu/.local/share/opencode
  
RUN mkdir -p /home/ubuntu/.config/opencode \
    && chown -R ubuntu:ubuntu /home/ubuntu/.config/opencode

There are multiple ways to get your development project into your container: copy it in, git pull it or link it from your local box into the container. I show the copy method here. You can use . in the copy command as the Dockerfile lives in your project root. Replace “ below.

# copy the project dir into the VM    
COPY --chown=ubuntu:ubuntu . /home/ubuntu/

And last but not least, we install OpenCode AI:

# Install OpenCode AI (Native Binary Method
# https://opencode.ai/docs/
RUN curl -fsSL https://opencode.ai/install | bash

Build and run the Docker container

Simply run docker build -t ubuntu-opencode . in your project root to build your container.

To be able to run it, you need to have a few things set up:

1. You need a GitHub token in your environment (e.g. export GH_TOKEN=). You generate that in the Developer Settings on GitHub.
2. You need your SSH key to be able to mount it into your container. Mine is id_ed25519
3. You need to have your local OpenCode authenticated for the model you want to use by using opencode auth login. This will generate the $HOME/.local/share/opencode/auth.json file, which we mount into our container as well.

Instead of opencode-1 you can use any name for the instance you want to spin up. -h sets it as the hostname so that your bash prompts will show it. Replace “ below.

docker run -dit --name opencode-1 \
    -h opencode-1 \
    -e GH_TOKEN \
    -w /home/ubuntu/ \
    -v "$HOME/.ssh/id_ed25519":/home/ubuntu/.ssh/id_ed25519:ro \
    -v "$HOME/.config/opencode":/home/ubuntu/.config/opencode \
    -v "$HOME/.local/share/opencode/auth.json":/home/ubuntu/.local/share/opencode/auth.json \
    ubuntu-opencode /bin/bash

Bundle Docker handling in a handy shell script

You need to change “ in the script below.

Create a file called run-opencode-docker.sh in your project dir. chmod a+x run-opencode-docker.sh to make it executable and run either directly or with the parameter rebuild if you want to re-create the container after changing your Dockerfile.

#!/bin/bash

# Configuration
CONTAINER_NAME="opencode-1"
IMAGE_NAME="ubuntu-opencode"
DOCKERFILE="Dockerfile"

PROJECT_DIR=""

LOCAL_AUTH_FILE="$HOME/.local/share/opencode/auth.json"

# Function to handle building
build_image() {
    echo "🔨 Building image from $DOCKERFILE..."
    
    if [ -z "$GH_TOKEN" ]; then
        echo "❌ Error: GH_TOKEN is not set. Cannot build."
        exit 1
    fi

    docker build -t $IMAGE_NAME -f $DOCKERFILE .
    
    if [ $? -ne 0 ]; then
        echo "❌ Docker build failed. Exiting."
        exit 1
    fi
    echo "✅ Build successful."
}

# ---------------------------------------------------------
# 0. Check for "rebuild" parameter
# ---------------------------------------------------------
if [ "$1" == "rebuild" ]; then
    echo "Force rebuild requested..."
    build_image
    exit 0
fi

# ---------------------------------------------------------
# 1. Check if Container Exists (Running or Stopped)
# ---------------------------------------------------------
if [ "$(docker ps -q -f name=$CONTAINER_NAME)" ]; then
    echo "🔄 Container '$CONTAINER_NAME' is already running."
    echo "🔗 Connecting to OpenCode..."
    exec docker exec -it -w /home/ubuntu/$PROJECT_DIR $CONTAINER_NAME /bin/bash -c "/home/ubuntu/.opencode/bin/opencode ."
elif [ "$(docker ps -aq -f name=$CONTAINER_NAME)" ]; then
    echo "🔄 Container '$CONTAINER_NAME' exists but is stopped."
    echo "🗑️  Removing old container..."
    docker rm $CONTAINER_NAME
fi

# ---------------------------------------------------------
# 4. Auto-Build Image (if missing)
# ---------------------------------------------------------
if [[ "$(docker images -q $IMAGE_NAME 2> /dev/null)" == "" ]]; then
    echo "⚠️  Image '$IMAGE_NAME' not found locally."
    build_image
fi

# ---------------------------------------------------------
# 5. Run New Container
# ---------------------------------------------------------
echo "🚀 Starting OpenCode..."

docker run -dit --name $CONTAINER_NAME \
    -h $CONTAINER_NAME \
    -e GH_TOKEN \
    -w /home/ubuntu/$PROJECT_DIR \
    -v "$HOME/.ssh/id_ed25519":/home/ubuntu/.ssh/id_ed25519:ro \
    -v "$HOME/.config/opencode":/home/ubuntu/.config/opencode \
    -v "$LOCAL_AUTH_FILE":/home/ubuntu/.local/share/opencode/auth.json \
    $IMAGE_NAME /bin/bash

echo "🔗 Connecting to OpenCode..."
exec docker exec -it -w /home/ubuntu/$PROJECT_DIR $CONTAINER_NAME /bin/bash -c "/home/ubuntu/.opencode/bin/opencode ."

Now you can run OpenCode on your project inside of your Docker container without risking the AI bricking your work computer. Make sure to always git pull when you start working and git push before you stop the container. You can instruct OpenCode to do this for you by putting this as instructions into your AGENTS.md file.