OpenCode Portal supports running OpenCode in Docker containers, providing isolation and easier deployment management.
Overview OpenPortal can run OpenCode in a Docker container while keeping the web UI as a host process. This provides:
Isolated OpenCode environment
Consistent runtime across different systems
Easy cleanup and management
No need to install OpenCode locally
Prerequisites
Install Docker
Ensure Docker is installed and running on your system. Ubuntu/Debian
macOS
Windows
# Install Docker curl -fsSL https://get.docker.com -o get-docker.sh sudo sh get-docker.sh # Add your user to docker group sudo usermod -aG docker $USER # Log out and back in for group changes to take effect
Verify Docker installation: docker --version docker ps
Install Bun
OpenPortal requires Bun to run the web UI: curl -fsSL https://bun.sh/install | bash
Install OpenPortal
Install OpenPortal globally: bun install -g openportal
You do NOT need to install OpenCode when using Docker mode - the container includes it.
Running with Docker Start OpenCode + Web UI in Docker Mode Use the --docker flag to run OpenCode in a container:
cd /path/to/your/project openportal --docker
This will:
Pull the OpenCode Docker image (if not already available)
Create and start a container with your project directory mounted
Start the web UI on the host
Start Only OpenCode Server in Docker This starts only the OpenCode server in a Docker container without the web UI.
Docker Configuration Default Docker Image By default, OpenPortal uses:
ghcr.io/anomalyco/opencode:1.1.3
Custom Docker Image You can specify a custom OpenCode Docker image using the OPENCODE_DOCKER_IMAGE environment variable:
OPENCODE_DOCKER_IMAGE = ghcr.io/anomalyco/opencode:latest openportal --docker
Or export it for persistent use:
export OPENCODE_DOCKER_IMAGE = ghcr . io / anomalyco / opencode : latest openportal --docker
Remote Docker Host To connect to a remote Docker daemon, use the DOCKER_HOST environment variable:
# TCP connection export DOCKER_HOST = tcp :// 192 . 168 . 1 . 100 : 2375 openportal --docker # Unix socket (default) export DOCKER_HOST = unix :/// var / run / docker . sock # Windows named pipe export DOCKER_HOST = npipe :////./ pipe / docker_engine
CLI Options with Docker All standard OpenPortal options work with Docker mode:
Custom Ports # Custom web UI and OpenCode ports openportal --docker --port 8080 --opencode-port 5000
Custom Directory # Run in specific directory openportal --docker -d /path/to/project
Custom Instance Name # Name your container instance openportal --docker --name my-project
Hostname Binding # Bind to specific hostname openportal --docker --hostname 0.0.0.0
Managing Docker Instances List Running Instances Output includes Docker container information:
ID NAME TYPE PORT OPENCODE STATUS DIRECTORY abc123 my-project docker 3000 4000 running /home/user/project
Stop Docker Instances # Stop instance in current directory openportal stop # Stop specific instance openportal stop --name my-project
This will:
Stop the Docker container
Remove the container (auto-cleanup)
Stop the web UI process
Clean Up Stale Entries Removes stopped containers and cleans up configuration entries.
Volume Mounts OpenPortal automatically mounts your project directory into the container:
/path/to/your/project -> /path/to/your/project (read-write)
The container’s working directory is set to your project path, so OpenCode operates on your files directly.
For security, OpenPortal prevents mounting sensitive system directories like /, /etc, /usr, etc.
Port Mapping The OpenCode server port is exposed from the container:
Container Port -> Host Port 4000 (or custom) -> 4000 (or custom)
The web UI runs on the host and connects to the containerized OpenCode server via the exposed port.
Container Lifecycle Container Naming Containers are automatically named:
openportal-{instance-name}-{random-id}
Example: openportal-my-project-a1b2c3d4
Auto-Removal Containers are created with the AutoRemove flag, meaning they’re automatically removed when stopped.
Container Logs View container logs directly:
# Get container ID from openportal list openportal list # View logs docker logs < container-i d > # Follow logs docker logs -f < container-i d >
Advanced Docker Usage Multiple Projects Run multiple projects simultaneously:
# Terminal 1 cd /path/to/project-a openportal --docker --port 3000 --opencode-port 4000 # Terminal 2 cd /path/to/project-b openportal --docker --port 3001 --opencode-port 4001
Server-Only Mode with Docker Run only the OpenCode server in Docker:
This is useful when:
You want to use a different UI
You’re integrating with external tools
You only need the OpenCode API
Inspecting Containers # List all OpenPortal containers docker ps -a | grep openportal # Inspect a specific container docker inspect < container-i d > # Execute commands in the container docker exec -it < container-i d > /bin/bash
Environment Variables OPENCODE_DOCKER_IMAGE Specify the OpenCode Docker image to use:
export OPENCODE_DOCKER_IMAGE = ghcr . io / anomalyco / opencode : 1 . 1 . 3
DOCKER_HOST Specify the Docker daemon connection:
# TCP connection export DOCKER_HOST = tcp :// localhost : 2375 # Unix socket (default on Linux/macOS) export DOCKER_HOST = unix :/// var / run / docker . sock # Named pipe (Windows) export DOCKER_HOST = npipe :////./ pipe / docker_engine
DEBUG Enable debug output for troubleshooting:
export DEBUG = 1 openportal --docker
Troubleshooting Docker Image Pull Issues If the image fails to pull:
# Manually pull the image docker pull ghcr.io/anomalyco/opencode:1.1.3 # Verify the image exists docker images | grep opencode
Container Won’t Start Check container logs:
# List all containers (including stopped) docker ps -a | grep openportal # View logs docker logs < container-i d >
Port Already in Use Specify different ports:
openportal --docker --port 8080 --opencode-port 5000
Volume Mount Errors Ensure the path is absolute:
# Bad - relative path openportal --docker -d ./my-project # Good - absolute path openportal --docker -d /home/user/my-project
Permission Issues On Linux, ensure your user is in the docker group:
sudo usermod -aG docker $USER # Log out and back in
Container Not Stopping Manually stop and remove:
# List containers docker ps | grep openportal # Force stop docker stop < container-i d > # Force remove docker rm < container-i d > # Clean up config openportal clean
Connection Refused Verify the container is running and port is exposed:
# Check container status docker ps | grep openportal # Check port mapping docker port < container-i d >
Benefits of Docker Mode Isolation
OpenCode runs in an isolated environment
No interference with host system packages
Clean separation of concerns
Consistency
Same OpenCode version across all environments
Reproducible builds and deployments
Easy version management via image tags
Easy Cleanup
Containers auto-remove when stopped
No residual files on host system
Simple instance management
No Local Installation
No need to install OpenCode on host
No dependency conflicts
Works on any system with Docker
Next Steps