opencode-docker

Docker wrapper for running opencode in server-client mode with proper workspace and configuration mounting.

Features

• Workspace mounting: Automatically mounts current directory to /workspace
• Config preservation: Uses your existing opencode configuration from ~/.config/opencode/opencode.json
• Custom kubeconfig: If ~/.kube/config-opencode exists, it's mounted as ~/.kube/config in the container
• Docker integration: Full Docker access from within the container via host Docker daemon
• Server-client mode: Runs opencode server in container, attaches from host for proper TTY handling
• Extra tools: Includes git, kubectl, helm, curl, and Docker CLI for full development workflow
• Easy wrapper: Simple shell script oc-container to launch and attach to the container

Setup

1. Install the oc-container script (optional)

Run the install script to install oc-container to your PATH:

./install.sh

The installer will ask whether to install system-wide to /usr/local/bin or per-user to ~/.local/bin.

2. Run using oc-container

oc-container

The wrapper starts the opencode server in a detached container and attaches to it from your host terminal. This provides proper TTY handling for keyboard shortcuts like Ctrl+P.

The wrapper will automatically pull the latest image from git.lukko.de/lukko.de/opencode-docker:latest if it's not already present.

The container listens on port 4096 and exposes it to your host machine.

Configuration

The opencode container uses your existing configuration from ~/.config/opencode/opencode.json. This file is automatically mounted into the container, so your settings, API keys, and preferences are preserved.

Note: The opencode.json in this repo is a boilerplate template only. Never commit your actual config file with real credentials to this repository.

If you need to modify the configuration, edit your local file:

nano ~/.config/opencode/opencode.json

Custom Kubeconfig

If you have a file named ~/.kube/config-opencode, it will be automatically mounted into the container as ~/.kube/config. This allows you to use a separate kubeconfig for opencode without affecting your default kubeconfig.

To set this up:

cp ~/.kube/config ~/.kube/config-opencode
# Edit as needed
nano ~/.kube/config-opencode

The file is mounted read-only to prevent accidental modifications.

Docker Integration

The container can access the host Docker daemon, allowing you to run Docker commands from within the opencode environment:

• Conditional socket mounting: /var/run/docker.sock is automatically mounted if available on the host
• Docker CLI access: The container includes Docker CLI for building and running containers
• No privileged mode required: Uses socket mounting instead of privileged mode for better security

This means you can run Docker containers, manage images, and execute Docker commands directly from opencode without needing to use the host terminal.

Note: Docker integration is only available if /var/run/docker.sock exists on your host system. The wrapper will silently skip the mount if the socket is not available.

Security

• Your API keys are stored locally in ~/.config/opencode/opencode.json
• The container mounts your config file as read-only to prevent modification
• Never commit your actual config file with real credentials to this repository
• The opencode.json in this repo is a template only

Available Tools

The container includes these tools:

• opencode: AI-powered development assistant
• git: Version control
• kubectl: Kubernetes management
• helm: Helm package manager
• curl: HTTP client
• docker: Docker CLI with access to host Docker daemon
• python3: Python runtime for Python projects

Troubleshooting

Image not found

The wrapper will automatically pull the image from git.lukko.de/lukko.de/opencode-docker:latest. If you need to pull it manually:

docker pull git.lukko.de/lukko.de/opencode-docker:latest

Docker access issues

If you're unable to run Docker commands from within the container:

• Verify that /var/run/docker.sock is mounted correctly
• Check that the container has proper permissions
• Ensure the host Docker daemon is running
• Try restarting the container with: docker restart $(docker ps --filter "name=opencode" -q)

Permission issues

If you encounter permission issues with the workspace, ensure the current directory is accessible:

ls -la $(pwd)

Config file not found

The wrapper will warn if your config file doesn't exist, but the container may still work with default settings.

Connection issues

If you have problems connecting to the backend server:

• Verify your config file has the correct baseURL and Authorization headers
• Check that the backend URL is accessible from your machine
• Ensure you have network connectivity to the backend

Image pull issues

The wrapper will automatically pull the image from git.lukko.de/lukko.de/opencode-docker:latest. If you need to pull it manually:

docker pull git.lukko.de/lukko.de/opencode-docker:latest

CI/CD Pipeline

This repository contains the Dockerfile that builds the opencode container. Your CI pipeline should:

1. Build the image:

   docker build -t git.lukko.de/lukko.de/opencode-docker:latest .
   

2. Push to registry:

   docker push git.lukko.de/lukko.de/opencode-docker:latest
   

3. Tag and push specific versions (optional):

   docker tag git.lukko.de/lukko.de/opencode-docker:latest git.lukko.de/lukko.de/opencode-docker:v1.0.0
   docker push git.lukko.de/lukko.de/opencode-docker:v1.0.0
   

Advanced Usage

Custom environment variables

Edit oc-container to add custom environment variables to the container:

docker run ... -e CUSTOM_VAR=value ...

Mount additional volumes

You can modify the docker run command in oc-container to mount additional directories:

-v "$(pwd):/workspace" \
-v "$HOME/.config/opencode/opencode.json:/root/.config/opencode/opencode.json:ro" \
-v ./another-folder:/another-folder

Docker access from opencode

Since the container has full Docker integration, you can run Docker commands directly from opencode:

# List running containers
docker ps

# Run a new container from inside opencode
docker run -it ubuntu bash

# Build and push images
docker build -t my-image:latest .
docker push git.lukko.de/lukko.de/my-image:latest

Versions

• Container base: ArchLinux with AUR
• opencode plugin: opencode-bin (latest from AUR)
• Tools: git, kubectl, helm, curl (latest available versions)
• Server port: 4096

Cleanup

The container is automatically removed when you detach from it due to the --rm flag in the oc-container script. If you need to remove the image:

docker rmi git.lukko.de/lukko.de/opencode-docker:latest

Manual Usage (Advanced)

If you need to manage the container manually:

Start server manually

docker run -d --rm \
  --name opencode-container \
  -p 4096:4096 \
  -v "$(pwd):/workspace" \
  -v "$HOME/.config/opencode/opencode.json:/root/.config/opencode/opencode.json:ro" \
  -w "$(pwd)" \
  git.lukko.de/lukko.de/opencode-docker:latest \
  opencode serve --host 0.0.0.0 --port 4096

Attach to server

docker exec -it opencode-container opencode attach --hostname localhost --port 4096