opencode-cloud

A production-ready toolkit for deploying and managing opencode as a persistent cloud service, sandboxed inside a Docker container for isolation and security.

Quick install (cargo)

cargo install opencode-cloud
opencode-cloud --version

Features

• Sandboxed execution - opencode runs inside a Docker container, isolated from your host system
• Persistent environment - Your projects, settings, and shell history persist across restarts
• Cross-platform CLI (opencode-cloud / occ) - Works on Linux and macOS
• Service lifecycle commands - start, stop, restart, status, logs
• Platform service integration - systemd (Linux) / launchd (macOS) for auto-start on boot
• Remote host management - Manage opencode containers on remote servers via SSH
• Web-based admin - Cockpit integration for container administration

How it works

opencode-cloud runs opencode inside a Docker container, providing:

• Isolation - opencode and its AI-generated code run in a sandbox, separate from your host system
• Reproducibility - The container includes a full development environment (languages, tools, runtimes)
• Persistence - Docker volumes preserve your work across container restarts and updates
• Security - Network exposure is opt-in; by default, the service only binds to localhost

The CLI manages the container lifecycle, so you don't need to interact with Docker directly.

Requirements

• Rust 1.85+ - Install via rustup: curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
• Docker - For running the opencode container

Installation

Via cargo (recommended)

cargo install opencode-cloud
occ --version

From source

git clone https://github.com/pRizz/opencode-cloud.git
cd opencode-cloud
just build
cargo run -p opencode-cloud -- --version

Usage

# Show version
occ --version

# Start the service (builds Docker container on first run, ~10-15 min)
occ start

# Start on a custom port
occ start --port 8080

# Start and open browser
occ start --open

# Check service status
occ status

# View logs
occ logs

# Follow logs in real-time
occ logs -f

# Stop the service
occ stop

# Restart the service
occ restart

# Install as a system service (starts on login/boot)
occ install

# Uninstall the system service
occ uninstall

# View configuration
occ config show

Rebuilding the Docker Image

When developing locally or after updating opencode-cloud, you may need to rebuild the Docker image to pick up changes in the embedded Dockerfile:

# Rebuild using Docker cache (fast - only rebuilds changed layers)
occ start --cached-rebuild

# Rebuild from scratch without cache (slow - for troubleshooting)
occ start --full-rebuild

--cached-rebuild (recommended for most cases):

• Uses Docker layer cache for fast rebuilds
• Only rebuilds layers that changed (e.g., if only the CMD changed, it's nearly instant)
• Stops and removes any existing container before rebuilding

--full-rebuild (for troubleshooting):

• Ignores Docker cache and rebuilds everything from scratch
• Takes 10-15 minutes but guarantees a completely fresh image
• Use when cached rebuild doesn't fix issues

When to rebuild:

• After pulling updates to opencode-cloud → use --cached-rebuild
• When modifying the Dockerfile during development → use --cached-rebuild
• When the container fails to start due to image issues → try --cached-rebuild first, then --full-rebuild
• When you want a completely fresh environment → use --full-rebuild

Configuration

Configuration is stored at:

• Linux/macOS: ~/.config/opencode-cloud/config.json

Data (PID files, etc.) is stored at:

• Linux/macOS: ~/.local/share/opencode-cloud/

Development

# Install dependencies
pnpm install

# Configure git hooks (once after cloning)
git config core.hooksPath .githooks

# Build everything
just build

# Compile and run occ (arguments automatically get passed to the binary)
just run --version

# Run tests
just test

# Format and lint
just fmt
just lint

Note: The git hooks automatically sync README.md to npm package directories on commit.

Architecture

This is a monorepo with:

• packages/core - Rust core library
• packages/cli-rust - Rust CLI binary (recommended)
• packages/cli-node - Node.js CLI (deprecated, directs users to cargo install)

Cargo.toml Sync Requirement

The packages/core/Cargo.toml file must use explicit values rather than workspace = true references.

When updating package metadata (version, edition, rust-version, etc.), keep both files in sync:

• Cargo.toml (workspace root)
• packages/core/Cargo.toml

Use scripts/set-all-versions.sh <version> to update versions across all files automatically.

License

MIT