opencode-box

OpenCode Box is a secure, containerized development environment for AI-assisted coding with OpenCode.

It provides an isolated Docker environment where you can safely work with AI-powered development tools while keeping your host system secure.

Installation

Install OpenCode Box globally via npm:

npm install -g opencode-box

Quick Start

1. Navigate to any Git repository:

cd /path/to/your/git/project

2. Launch OpenCode Box:

opencodebox

OpenCode Box will automatically:

• Build the Docker image (if not already built)
• Securely forward your SSH/Git credentials to the container
• Copy OpenCode configurations (~/.local/share/opencode and ~/.config/opencode)
• Clone the current repository inside the container
• Checkout to the current branch from your host machine
• Start OpenCode in the isolated environment

Workspace Modes

OpenCode Box supports three workspace modes:

--gitcheckout (default)

Clones repository inside container.

opencodebox --gitcheckout

• Interactive terminal session
• SSH credentials required
• Dedicated workspace volume
• Automatic cleanup on exit

--mount-ro

Mount workspace as read-only.

opencodebox --mount-ro

• Code examination only
• No file modifications allowed
• No SSH requirements
• Direct workspace mounting

--mount-rw

Mount workspace as read-write.

opencodebox --mount-rw

• Direct file editing
• Changes saved to host filesystem
• No SSH requirements
• Direct workspace mounting

Advanced Usage

Interactive shell

opencodebox --gitcheckout --it

Force rebuild

opencodebox --gitcheckout --rebuild

Multiple instances

cd ~/project-a
opencodebox --mount-ro

cd ~/project-b
opencodebox --mount-rw

Command Reference

Modes

| Mode | Description | SSH Required | Interactive | |------|------------|-------------|------------| | --gitcheckout | Clone repository inside container | Yes | Yes | | --mount-ro | Mount workspace as read-only | No | No | | --mount-rw | Mount workspace as read-write | No | No |

Options

| Option | Description | |--------|------------| | --it | Interactive shell | | --rebuild | Force rebuild Docker image | | --help, -h | Show help | | --version, -v | Show version |

System Requirements

• Node.js 16+
• npm 7+
• Docker 20.10+
• Git 2.25+

SSH Setup

eval "$(ssh-agent -s)"
ssh-add ~/.ssh/id_rsa
ssh-add -l

Git Configuration

git config --global user.name
git config --global user.email

Docker Check

docker --version
docker info
docker run hello-world

Troubleshooting

SSH issues

ssh-add -l

Docker permissions

sudo usermod -aG docker $USER

Git auth

ssh -T [email protected]

Container Architecture

• Base image: node:20-alpine
• OpenCode CLI installed globally
• Non-root user
• Isolated environment
• Volume mounts for workspace

Roadmap

• Workspace modes (completed)
• Container management (completed)
• Interactive shell (completed)
• Volume mounting improvements
• Multi-platform support
• Performance improvements