@opencode-cloud/core 1.0.10 → 3.1.1

package/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "opencode-cloud-core"
-version = "1.0.10"
+version = "3.1.1"
 edition = "2024"
 rust-version = "1.88"
 license = "MIT"
@@ -47,14 +47,14 @@ tokio-retry = "0.3"
 indicatif = { version = "0.17", features = ["tokio", "futures"] }
 http-body-util = "0.1"
 bytes = "1.9"
-reqwest = { version = "0.12", features = ["json"] }
+reqwest = { version = "0.12", default-features = false, features = ["rustls-tls", "json"] }
 
 # Platform service management (macOS)
 plist = "1.8"
 
 # Host management
 whoami = "1.5"
-ssh2-config = "0.6"
+ssh2-config-rs = "0.7.2"
 dirs = "6"
 
 [build-dependencies]

package/README.md

@@ -2,12 +2,13 @@
 
 [![CI](https://github.com/pRizz/opencode-cloud/actions/workflows/ci.yml/badge.svg)](https://github.com/pRizz/opencode-cloud/actions/workflows/ci.yml)
 [![crates.io](https://img.shields.io/crates/v/opencode-cloud.svg)](https://crates.io/crates/opencode-cloud)
-[![npm](https://img.shields.io/npm/v/opencode-cloud.svg)](https://www.npmjs.com/package/opencode-cloud)
+[![GHCR](https://img.shields.io/badge/ghcr.io-sandbox-blue?logo=github)](https://github.com/pRizz/opencode-cloud/pkgs/container/opencode-cloud-sandbox)
+[![Docker Hub](https://img.shields.io/docker/v/prizz/opencode-cloud-sandbox?label=docker&sort=semver)](https://hub.docker.com/r/prizz/opencode-cloud-sandbox)
 [![docs.rs](https://docs.rs/opencode-cloud/badge.svg)](https://docs.rs/opencode-cloud)
 [![MSRV](https://img.shields.io/badge/MSRV-1.85-blue.svg)](https://blog.rust-lang.org/2025/02/20/Rust-1.85.0.html)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-A production-ready toolkit for deploying [opencode](https://github.com/anomalyco/opencode) as a persistent cloud service.
+A production-ready toolkit for deploying and managing [opencode](https://github.com/anomalyco/opencode) as a persistent cloud service, **sandboxed inside a Docker container** for isolation and security.
 
 ## Quick install (cargo)
 
@@ -18,45 +19,65 @@ opencode-cloud --version
 
 ## Features
 
-- Cross-platform CLI (`opencode-cloud` / `occ`)
-- Docker container management
-- Service lifecycle commands (start, stop, status, logs)
-- Platform service integration (systemd/launchd)
-- XDG-compliant configuration
-- Singleton enforcement (one instance per host)
+- **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
 
-## Requirements
+## How it works
 
-### For npm installation
+opencode-cloud runs opencode inside a Docker container, providing:
 
-- **Node.js 20+**
-- **Rust 1.82+** (for compiling native bindings)
-  - Install via [rustup](https://rustup.rs): `curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh`
+- **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
 
-### For cargo installation
+The CLI manages the container lifecycle, so you don't need to interact with Docker directly.
 
-- **Rust 1.82+**
+## Docker Images
 
-## Installation
+The sandbox container image is named **`opencode-cloud-sandbox`** (not `opencode-cloud`) to clearly distinguish it from the CLI tool. The CLI (`opencode-cloud` / `occ`) deploys and manages this sandbox container.
+
+The image is published to both registries:
+
+| Registry | Image |
+|----------|-------|
+| GitHub Container Registry | [`ghcr.io/prizz/opencode-cloud-sandbox`](https://github.com/pRizz/opencode-cloud/pkgs/container/opencode-cloud-sandbox) |
+| Docker Hub | [`prizz/opencode-cloud-sandbox`](https://hub.docker.com/r/prizz/opencode-cloud-sandbox) |
 
-### Via npm (compiles from source)
+Pull commands:
 
+Docker Hub:
 ```bash
-npx opencode-cloud --version
+docker pull prizz/opencode-cloud-sandbox:latest
 ```
 
-Or install globally:
+GitHub Container Registry:
+```bash
+docker pull ghcr.io/prizz/opencode-cloud-sandbox:latest
+```
 
+**For most users:** Just use the CLI - it handles image pulling/building automatically:
 ```bash
-npm install -g opencode-cloud
-occ --version
+occ start  # Pulls or builds the image as needed
 ```
 
-### Via cargo
+## Requirements
+
+- **Rust 1.85+** - Install via [rustup](https://rustup.rs): `curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh`
+- **Docker** - For running the opencode container
+
+## Installation
+
+### Via cargo (recommended)
 
 ```bash
 cargo install opencode-cloud
-opencode-cloud --version
+occ --version
 ```
 
 ### From source
@@ -74,7 +95,7 @@ cargo run -p opencode-cloud -- --version
 # Show version
 occ --version
 
-# Start the service (builds image on first run)
+# Start the service (builds Docker container on first run, ~10-15 min)
 occ start
 
 # Start on a custom port
@@ -172,15 +193,13 @@ just lint
 ## Architecture
 
 This is a monorepo with:
-- `packages/core` - Rust core library with NAPI-RS bindings
-- `packages/cli-rust` - Rust CLI binary
-- `packages/cli-node` - Node.js CLI wrapper (calls into core via NAPI)
-
-The npm package compiles the Rust core on install (no prebuilt binaries).
+- `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. This is because when users install the npm package, they only get `packages/core/` without the workspace root `Cargo.toml`, so workspace inheritance would fail.
+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)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opencode-cloud/core",
-  "version": "1.0.10",
+  "version": "3.1.1",
   "description": "Core NAPI bindings for opencode-cloud (internal package)",
   "main": "index.js",
   "types": "index.d.ts",

package/src/config/schema.rs

@@ -100,6 +100,19 @@ pub struct Config {
     /// - No Cockpit web UI
     #[serde(default = "default_cockpit_enabled")]
     pub cockpit_enabled: bool,
+
+    /// Source of Docker image: 'prebuilt' (pull from registry) or 'build' (compile locally)
+    #[serde(default = "default_image_source")]
+    pub image_source: String,
+
+    /// When to check for updates: 'always' (every start), 'once' (once per version), 'never'
+    #[serde(default = "default_update_check")]
+    pub update_check: String,
+
+    /// Bind mounts to apply when starting the container
+    /// Format: ["/host/path:/container/path", "/host:/mnt:ro"]
+    #[serde(default)]
+    pub mounts: Vec<String>,
 }
 
 fn default_opencode_web_port() -> u16 {
@@ -146,6 +159,14 @@ fn default_cockpit_enabled() -> bool {
     false
 }
 
+fn default_image_source() -> String {
+    "prebuilt".to_string()
+}
+
+fn default_update_check() -> String {
+    "always".to_string()
+}
+
 /// Validate and parse a bind address string
 ///
 /// Accepts:
@@ -196,6 +217,9 @@ impl Default for Config {
             users: Vec::new(),
             cockpit_port: default_cockpit_port(),
             cockpit_enabled: default_cockpit_enabled(),
+            image_source: default_image_source(),
+            update_check: default_update_check(),
+            mounts: Vec::new(),
         }
     }
 }
@@ -276,6 +300,7 @@ mod tests {
         assert_eq!(config.rate_limit_attempts, 5);
         assert_eq!(config.rate_limit_window_seconds, 60);
         assert!(config.users.is_empty());
+        assert!(config.mounts.is_empty());
     }
 
     #[test]
@@ -330,6 +355,9 @@ mod tests {
             users: vec!["admin".to_string()],
             cockpit_port: 9090,
             cockpit_enabled: true,
+            image_source: default_image_source(),
+            update_check: default_update_check(),
+            mounts: Vec::new(),
         };
         let json = serde_json::to_string(&config).unwrap();
         let parsed: Config = serde_json::from_str(&json).unwrap();
@@ -619,4 +647,67 @@ mod tests {
         // cockpit_enabled defaults to false (requires Linux host)
         assert!(!config.cockpit_enabled);
     }
+
+    // Tests for image_source and update_check fields
+
+    #[test]
+    fn test_default_config_image_fields() {
+        let config = Config::default();
+        assert_eq!(config.image_source, "prebuilt");
+        assert_eq!(config.update_check, "always");
+    }
+
+    #[test]
+    fn test_serialize_deserialize_with_image_fields() {
+        let config = Config {
+            image_source: "build".to_string(),
+            update_check: "never".to_string(),
+            ..Config::default()
+        };
+        let json = serde_json::to_string(&config).unwrap();
+        let parsed: Config = serde_json::from_str(&json).unwrap();
+        assert_eq!(parsed.image_source, "build");
+        assert_eq!(parsed.update_check, "never");
+    }
+
+    #[test]
+    fn test_image_fields_default_on_missing() {
+        // Old configs without image fields should get defaults
+        let json = r#"{"version": 1}"#;
+        let config: Config = serde_json::from_str(json).unwrap();
+        assert_eq!(config.image_source, "prebuilt");
+        assert_eq!(config.update_check, "always");
+    }
+
+    // Tests for mounts field
+
+    #[test]
+    fn test_default_config_mounts_field() {
+        let config = Config::default();
+        assert!(config.mounts.is_empty());
+    }
+
+    #[test]
+    fn test_serialize_deserialize_with_mounts() {
+        let config = Config {
+            mounts: vec![
+                "/home/user/data:/workspace/data".to_string(),
+                "/home/user/config:/etc/app:ro".to_string(),
+            ],
+            ..Config::default()
+        };
+        let json = serde_json::to_string(&config).unwrap();
+        let parsed: Config = serde_json::from_str(&json).unwrap();
+        assert_eq!(parsed.mounts.len(), 2);
+        assert_eq!(parsed.mounts[0], "/home/user/data:/workspace/data");
+        assert_eq!(parsed.mounts[1], "/home/user/config:/etc/app:ro");
+    }
+
+    #[test]
+    fn test_mounts_field_default_on_missing() {
+        // Old configs without mounts field should get empty vec
+        let json = r#"{"version": 1}"#;
+        let config: Config = serde_json::from_str(json).unwrap();
+        assert!(config.mounts.is_empty());
+    }
 }

package/src/docker/Dockerfile

@@ -53,10 +53,6 @@ RUN apt-get update && apt-get install -y --no-install-recommends \
 # -----------------------------------------------------------------------------
 FROM ubuntu:24.04 AS runtime
 
-# Version passed at build time (must be after FROM to be available in this stage)
-# Default "dev" for local builds; CI sets actual version via --build-arg
-ARG OPENCODE_CLOUD_VERSION=dev
-
 # OCI Labels for image metadata
 LABEL org.opencontainers.image.title="opencode-cloud"
 LABEL org.opencontainers.image.description="AI-assisted development environment with opencode"
@@ -65,8 +61,6 @@ LABEL org.opencontainers.image.source="https://github.com/pRizz/opencode-cloud"
 LABEL org.opencontainers.image.vendor="pRizz"
 LABEL org.opencontainers.image.licenses="MIT"
 LABEL org.opencontainers.image.base.name="ubuntu:24.04"
-# Version label for CLI compatibility checks (set via --build-arg OPENCODE_CLOUD_VERSION)
-LABEL org.opencode-cloud.version="${OPENCODE_CLOUD_VERSION}"
 
 # Environment configuration
 ENV DEBIAN_FRONTEND=noninteractive
@@ -187,14 +181,17 @@ ENV PATH="/home/opencode/.local/bin:${PATH}"
 # Shell Setup: Zsh + Oh My Zsh + Starship
 # -----------------------------------------------------------------------------
 # Oh My Zsh - self-managing installer, trusted to handle versions
-RUN sh -c "$(curl -fsSL https://raw.githubusercontent.com/ohmyzsh/ohmyzsh/master/tools/install.sh)" "" --unattended
+# Disabled temporarily to reduce Docker build time.
+# RUN sh -c "$(curl -fsSL https://raw.githubusercontent.com/ohmyzsh/ohmyzsh/master/tools/install.sh)" "" --unattended
 
 # Starship prompt - self-managing installer, trusted to handle versions
-RUN curl -sS https://starship.rs/install.sh | sh -s -- --yes --bin-dir /home/opencode/.local/bin
+# Disabled temporarily to reduce Docker build time.
+# RUN curl -sS https://starship.rs/install.sh | sh -s -- --yes --bin-dir /home/opencode/.local/bin
 
 # Configure zsh with starship
-RUN echo 'eval "$(starship init zsh)"' >> /home/opencode/.zshrc \
-    && echo 'export PATH="/home/opencode/.local/bin:$PATH"' >> /home/opencode/.zshrc
+# Disabled temporarily to reduce Docker build time.
+# RUN echo 'eval "$(starship init zsh)"' >> /home/opencode/.zshrc \
+#     && echo 'export PATH="/home/opencode/.local/bin:$PATH"' >> /home/opencode/.zshrc
 
 # -----------------------------------------------------------------------------
 # mise: Universal Version Manager
@@ -265,39 +262,46 @@ RUN . /home/opencode/.cargo/env \
     && cargo install --locked ripgrep@15.1.0 eza@0.23.4
 
 # lazygit v0.58.1 (2026-01-12) - terminal UI for git
-RUN eval "$(/home/opencode/.local/bin/mise activate bash)" \
-    && go install github.com/jesseduffield/lazygit@v0.58.1
+# Disabled temporarily to reduce Docker build time.
+# RUN eval "$(/home/opencode/.local/bin/mise activate bash)" \
+#     && go install github.com/jesseduffield/lazygit@v0.58.1
 
 # -----------------------------------------------------------------------------
 # Additional Development Tools
 # -----------------------------------------------------------------------------
 # fzf v0.67.0 (2025-11-16) - fuzzy finder
-RUN git clone --branch v0.67.0 --depth 1 https://github.com/junegunn/fzf.git /home/opencode/.fzf \
-    && /home/opencode/.fzf/install --all --no-bash --no-fish
+# Disabled temporarily to reduce Docker build time.
+# RUN git clone --branch v0.67.0 --depth 1 https://github.com/junegunn/fzf.git /home/opencode/.fzf \
+#     && /home/opencode/.fzf/install --all --no-bash --no-fish
 
 # yq v4.50.1 (2025-12-14) - YAML processor
-RUN curl -sL https://github.com/mikefarah/yq/releases/download/v4.50.1/yq_linux_$(dpkg --print-architecture) -o /home/opencode/.local/bin/yq \
-    && chmod +x /home/opencode/.local/bin/yq
+# Disabled temporarily to reduce Docker build time.
+# RUN curl -sL https://github.com/mikefarah/yq/releases/download/v4.50.1/yq_linux_$(dpkg --print-architecture) -o /home/opencode/.local/bin/yq \
+#     && chmod +x /home/opencode/.local/bin/yq
 
 # Install direnv (2026-01-22)
-USER root
-RUN apt-get update && apt-get install -y --no-install-recommends direnv=2.32.* \
-    && rm -rf /var/lib/apt/lists/*
-USER opencode
-RUN echo 'eval "$(direnv hook zsh)"' >> /home/opencode/.zshrc
+# Disabled temporarily to reduce Docker build time.
+# USER root
+# RUN apt-get update && apt-get install -y --no-install-recommends direnv=2.32.* \
+#     && rm -rf /var/lib/apt/lists/*
+# USER opencode
+# RUN echo 'eval "$(direnv hook zsh)"' >> /home/opencode/.zshrc
 
 # Install HTTPie
-RUN eval "$(/home/opencode/.local/bin/mise activate bash)" \
-    && pipx install httpie
+# Disabled temporarily to reduce Docker build time.
+# RUN eval "$(/home/opencode/.local/bin/mise activate bash)" \
+#     && pipx install httpie
 
 # Install shellcheck (2026-01-22)
-USER root
-RUN apt-get update && apt-get install -y --no-install-recommends shellcheck=0.9.* \
-    && rm -rf /var/lib/apt/lists/*
-USER opencode
+# Disabled temporarily to reduce Docker build time.
+# USER root
+# RUN apt-get update && apt-get install -y --no-install-recommends shellcheck=0.9.* \
+#     && rm -rf /var/lib/apt/lists/*
+# USER opencode
 # shfmt v3.12.0 (2025-07-06) - shell formatter
-RUN eval "$(/home/opencode/.local/bin/mise activate bash)" \
-    && go install mvdan.cc/sh/v3/cmd/shfmt@v3.12.0
+# Disabled temporarily to reduce Docker build time.
+# RUN eval "$(/home/opencode/.local/bin/mise activate bash)" \
+#     && go install mvdan.cc/sh/v3/cmd/shfmt@v3.12.0
 
 # Install btop system monitor (2026-01-22)
 USER root
@@ -351,67 +355,77 @@ RUN mkdir -p /etc/cockpit && \
 USER opencode
 
 # -----------------------------------------------------------------------------
-# CI/CD Tools
+# CI/CD + tooling (disabled)
 # -----------------------------------------------------------------------------
-# act v0.2.84 (2026-01-01) - run GitHub Actions locally
-RUN curl -sL https://raw.githubusercontent.com/nektos/act/master/install.sh | sudo bash -s -- -b /home/opencode/.local/bin v0.2.84
-
-# -----------------------------------------------------------------------------
-# Rust Tooling - pinned versions (2026-01-22)
-# -----------------------------------------------------------------------------
-# cargo-nextest 0.9.122 - fast test runner
-# cargo-audit 0.22.0 - security audit
-# cargo-deny 0.19.0 - dependency linter
-RUN . /home/opencode/.cargo/env \
-    && cargo install --locked cargo-nextest@0.9.122 cargo-audit@0.22.0 cargo-deny@0.19.0
-
-# Install mold fast linker (2026-01-22)
-USER root
-RUN apt-get update && apt-get install -y --no-install-recommends mold=2.30.* \
-    && rm -rf /var/lib/apt/lists/*
-USER opencode
-
+# NOTE: Commented out because this section adds significant time in GitHub Actions
+# builds. We will reconsider re-adding these tools later, potentially in a more
+# templated/configured Docker image optimized for build tooling.
 # -----------------------------------------------------------------------------
-# Code Quality Tools
-# -----------------------------------------------------------------------------
-# JavaScript/TypeScript tools
-RUN eval "$(/home/opencode/.local/bin/mise activate bash)" \
-    && pnpm add -g \
-    prettier \
-    eslint \
-    @biomejs/biome
-
-# Python tools
-RUN eval "$(/home/opencode/.local/bin/mise activate bash)" \
-    && pipx install black \
-    && pipx install ruff
-
-# Test runners (commonly needed)
-RUN eval "$(/home/opencode/.local/bin/mise activate bash)" \
-    && pnpm add -g jest vitest
-
-# Python pytest via pipx
-RUN eval "$(/home/opencode/.local/bin/mise activate bash)" \
-    && pipx install pytest
-
-# -----------------------------------------------------------------------------
-# Protocol Buffers / gRPC (2026-01-22)
-# -----------------------------------------------------------------------------
-USER root
-RUN apt-get update && apt-get install -y --no-install-recommends protobuf-compiler=3.21.* \
-    && rm -rf /var/lib/apt/lists/*
-USER opencode
-
-# grpcurl v1.9.3 (2025-03-11) - gRPC debugging tool
-RUN eval "$(/home/opencode/.local/bin/mise activate bash)" \
-    && go install github.com/fullstorydev/grpcurl/cmd/grpcurl@v1.9.3
+# # CI/CD Tools
+# # -----------------------------------------------------------------------------
+# # act v0.2.84 (2026-01-01) - run GitHub Actions locally
+# RUN curl -sL https://raw.githubusercontent.com/nektos/act/master/install.sh | sudo bash -s -- -b /home/opencode/.local/bin v0.2.84
+#
+# # -----------------------------------------------------------------------------
+# # Rust Tooling - pinned versions (2026-01-22)
+# # -----------------------------------------------------------------------------
+# # cargo-nextest 0.9.122 - fast test runner
+# # cargo-audit 0.22.0 - security audit
+# # cargo-deny 0.19.0 - dependency linter
+# RUN . /home/opencode/.cargo/env \
+#     && cargo install --locked cargo-nextest@0.9.122 cargo-audit@0.22.0 cargo-deny@0.19.0
+#
+# # Install mold fast linker (2026-01-22)
+# USER root
+# RUN apt-get update && apt-get install -y --no-install-recommends mold=2.30.* \
+#     && rm -rf /var/lib/apt/lists/*
+# USER opencode
+#
+# # -----------------------------------------------------------------------------
+# # Code Quality Tools
+# # -----------------------------------------------------------------------------
+# # JavaScript/TypeScript tools
+# RUN eval "$(/home/opencode/.local/bin/mise activate bash)" \
+#     && pnpm add -g \
+#     prettier \
+#     eslint \
+#     @biomejs/biome
+#
+# # Python tools
+# RUN eval "$(/home/opencode/.local/bin/mise activate bash)" \
+#     && pipx install black \
+#     && pipx install ruff
+#
+# # Test runners (commonly needed)
+# RUN eval "$(/home/opencode/.local/bin/mise activate bash)" \
+#     && pnpm add -g jest vitest
+#
+# # Python pytest via pipx
+# RUN eval "$(/home/opencode/.local/bin/mise activate bash)" \
+#     && pipx install pytest
+#
+# # -----------------------------------------------------------------------------
+# # Protocol Buffers / gRPC (2026-01-22)
+# # -----------------------------------------------------------------------------
+# USER root
+# RUN apt-get update && apt-get install -y --no-install-recommends protobuf-compiler=3.21.* \
+#     && rm -rf /var/lib/apt/lists/*
+# USER opencode
+#
+# # grpcurl v1.9.3 (2025-03-11) - gRPC debugging tool
+# RUN eval "$(/home/opencode/.local/bin/mise activate bash)" \
+#     && go install github.com/fullstorydev/grpcurl/cmd/grpcurl@v1.9.3
 
 # -----------------------------------------------------------------------------
 # opencode Installation
 # -----------------------------------------------------------------------------
 # opencode - self-managing installer, trusted to handle versions
 # The script installs to ~/.opencode/bin/
-RUN curl -fsSL https://opencode.ai/install | bash \
+# Retry logic added because opencode.ai API can be flaky during parallel builds
+RUN for i in 1 2 3 4 5; do \
+        curl -fsSL https://opencode.ai/install | bash && break || \
+        echo "Attempt $i failed, retrying in 10s..." && sleep 10; \
+    done \
     && ls -la /home/opencode/.opencode/bin/opencode \
     && /home/opencode/.opencode/bin/opencode --version
 
@@ -422,7 +436,9 @@ ENV PATH="/home/opencode/.opencode/bin:${PATH}"
 # GSD Plugin Installation
 # -----------------------------------------------------------------------------
 # Install the GSD (Get Shit Done) plugin for opencode
-RUN git clone https://github.com/rokicool/gsd-opencode.git /home/opencode/.config/opencode/plugins/gsd-opencode
+# Note: If this fails in container builds due to "~" path resolution, retry with
+# OPENCODE_CONFIG_DIR=/home/opencode/.config/opencode set explicitly.
+RUN npx --yes get-shit-done-cc --opencode --global
 
 # -----------------------------------------------------------------------------
 # opencode systemd Service (2026-01-22)
@@ -552,10 +568,15 @@ HEALTHCHECK --interval=30s --timeout=10s --start-period=30s --retries=3 \
 # Version File
 # -----------------------------------------------------------------------------
 # Store version in file for runtime access (debugging, scripts)
+# Keep this near the end: changing the version invalidates the cache
+# and significantly slows down docker builds if placed earlier.
 USER root
 ARG OPENCODE_CLOUD_VERSION=dev
+LABEL org.opencode-cloud.version="${OPENCODE_CLOUD_VERSION}"
 RUN echo "${OPENCODE_CLOUD_VERSION}" > /etc/opencode-cloud-version
-USER opencode
+# Note: Stay as root - entrypoint.sh needs root to run either:
+# - /sbin/init (systemd mode)
+# - runuser (tini mode, which then drops privileges to opencode user)
 
 # -----------------------------------------------------------------------------
 # Final Configuration

package/src/docker/README.dockerhub.md

@@ -0,0 +1,39 @@
+# opencode-cloud-sandbox
+
+Opinionated container image for AI-assisted coding with opencode.
+
+## What is included
+
+- Ubuntu 24.04 (noble)
+- Non-root user with passwordless sudo
+- mise-managed runtimes (Node.js LTS, Python 3.12, Go 1.24)
+- Rust toolchain via rustup
+- Core CLI utilities (ripgrep, eza, jq, git, etc.)
+- Cockpit web console for administration
+- opencode preinstalled with the GSD plugin
+
+## Tags
+
+- `latest`: Most recent published release
+- `X.Y.Z`: Versioned releases (recommended for pinning)
+
+## Usage
+
+Pull the image:
+
+```
+docker pull ghcr.io/prizz/opencode-cloud-sandbox:latest
+```
+
+Run the container:
+
+```
+docker run --rm -it -p 3000:3000 -p 9090:9090 ghcr.io/prizz/opencode-cloud-sandbox:latest
+```
+
+The opencode web UI is available at `http://localhost:3000`. Cockpit runs on `http://localhost:9090`.
+
+## Source
+
+- Repository: https://github.com/pRizz/opencode-cloud
+- Dockerfile: packages/core/src/docker/Dockerfile