Upgrade base image from Debian bookworm to trixie (current stable)

Bookworm (Debian 12) reaches EOL June 2026. Trixie (Debian 13) has been
stable since August 2025 with support until 2028/LTS until 2030.

DOCKER_HUB.md

@@ -116,10 +116,22 @@ The entrypoint automatically detects the owner of `/workspace` and adjusts the c
 
 ## Initial Setup
 
-### 1. Create a project directory
+### 1. Create host directories
+
+Bind-mounted directories must exist on the host before starting the container. Docker creates missing directories as root-owned, which causes permission issues.
 
 ```bash
+# Required
 mkdir -p ~/projects
+
+# If mounting opencode config (recommended for persistent settings)
+mkdir -p ~/.config/opencode
+
+# If using AWS Bedrock
+# mkdir -p ~/.aws
+
+# If mounting neovim config
+# mkdir -p ~/.config/nvim
 ```
 
 ### 2. Create a `.env` file
@@ -187,6 +199,7 @@ Understanding what survives container restarts and what doesn't:
 | `/home/developer/.local/share/uv` | Named volume (if configured) | ✅ Yes — Docker volume | Python installs, uv tool installs |
 | `/home/developer/.rustup` | Named volume (if configured) | ✅ Yes — Docker volume | Rust toolchains |
 | `/home/developer/.cargo` | Named volume (if configured) | ✅ Yes — Docker volume | Cargo binaries, registry cache |
+| `/home/developer/.vscode-server` | Named volume (if configured) | ✅ Yes — Docker volume | VS Code server and extensions |
 | `/home/developer/.config/opencode` | Host bind mount (if configured) | ✅ Yes — lives on host | opencode.json, oh-my-opencode-slim.json, skills |
 
 ### Key points
@@ -305,6 +318,28 @@ bun run src/index.ts
 
 Node modules are stored in your project directory under `/workspace` and persist automatically.
 
+## VS Code Integration
+
+VS Code can connect directly to a running opencode-devbox container for a full IDE experience with IntelliSense, debugging, and extensions running inside the container.
+
+**Requirements:** Install the [Dev Containers](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers) extension. For remote Docker hosts, also install [Remote - SSH](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-ssh).
+
+**Steps:**
+
+1. Start the container: `docker compose up -d`
+2. In VS Code: `Ctrl+Shift+P` → "Dev Containers: Attach to Running Container" → select `opencode-devbox`
+
+For remote Docker hosts (e.g. connecting to a server via SSH), first connect to the remote host with Remote-SSH, then attach to the container from there.
+
+VS Code extensions installed inside the container persist as long as the container exists. For persistent extension storage across container recreations, add a named volume:
+
+```bash
+docker run -it --rm \
+  -v devbox-vscode:/home/developer/.vscode-server \
+  ... \
+  joakimp/opencode-devbox:latest
+```
+
 ## Using docker-compose
 
 Create a directory with a `docker-compose.yml` and a `.env` file:
@@ -347,6 +382,8 @@ services:
       # Optional: persist Rust toolchains and cargo data
       # - devbox-rustup:/home/developer/.rustup
       # - devbox-cargo:/home/developer/.cargo
+      # Optional: persist VS Code server and extensions
+      # - devbox-vscode:/home/developer/.vscode-server
       # Mount AWS config for Bedrock SSO (required for amazon-bedrock provider)
       # - ~/.aws:/home/developer/.aws
       # Optional: mount opencode config directory (persists config changes across restarts)
@@ -361,6 +398,7 @@ volumes:
   # devbox-uv:
   # devbox-rustup:
   # devbox-cargo:
+  # devbox-vscode:
 ```
 
 Docker Compose loads `.env` automatically from the same directory. All variables from `.env` are passed to the container via `env_file`. Do **not** hardcode provider settings in the `environment:` section — use `.env` instead.
@@ -390,7 +428,7 @@ docker compose run --rm devbox bash   # interactive shell
 
 ### Base image (`latest`)
 
-- **Debian bookworm-slim** — glibc, full terminal/PTY support
+- **Debian trixie-slim** — glibc, full terminal/PTY support
 - **opencode** — AI coding assistant
 - **Node.js 22** — for npx-based MCP servers
 - **AWS CLI v2** — SSO and Bedrock authentication

Dockerfile

@@ -1,7 +1,7 @@
 # opencode-devbox — portable AI dev environment
 # Debian-based container with opencode and configurable dev tools
 
-ARG DEBIAN_VERSION=bookworm-slim
+ARG DEBIAN_VERSION=trixie-slim
 FROM debian:${DEBIAN_VERSION} AS base
 
 ARG TARGETARCH

README.md

@@ -27,7 +27,7 @@ docker compose run --rm devbox
 
 ## Features
 
-- **Debian bookworm** base — glibc, full PTY/terminal support
+- **Debian trixie** base — glibc, full PTY/terminal support
 - **Configurable providers** — Anthropic, OpenAI, AWS Bedrock via env vars
 - **Host filesystem access** — bind mount any directory as `/workspace`
 - **SSH key forwarding** — git push/pull to private repos
@@ -42,6 +42,18 @@ docker compose run --rm devbox
 
 ## Usage
 
+### Prerequisites
+
+Bind-mounted directories must exist on the host before starting the container. Docker creates missing directories as root-owned, which causes permission issues.
+
+```bash
+# Required: workspace for your projects
+mkdir -p ~/projects
+
+# If mounting opencode config (recommended for persistent settings)
+mkdir -p ~/.config/opencode
+```
+
 ### Connecting to the container
 
 From your laptop, SSH into the remote server where Docker is running, then start the container:
@@ -228,6 +240,30 @@ bun run src/index.ts
 
 Node modules are stored in your project directory under `/workspace` and persist automatically.
 
+### VS Code integration
+
+VS Code can connect directly to a running opencode-devbox container for a full IDE experience with IntelliSense, debugging, and extensions running inside the container.
+
+**Local Docker (Docker running on your workstation):**
+
+1. Install the [Dev Containers](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers) extension
+2. Start the container: `docker compose up -d`
+3. In VS Code: `Ctrl+Shift+P` → "Dev Containers: Attach to Running Container" → select `opencode-devbox`
+
+**Remote Docker (Docker running on a remote server, e.g. via SSH):**
+
+1. Install the [Remote - SSH](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-ssh) and [Dev Containers](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers) extensions
+2. Connect to the remote host: `Ctrl+Shift+P` → "Remote-SSH: Connect to Host"
+3. On the remote host, start the container: `docker compose up -d`
+4. In VS Code (now connected to the remote): `Ctrl+Shift+P` → "Dev Containers: Attach to Running Container"
+
+VS Code extensions installed inside the container persist as long as the container exists (not removed with `docker compose down`). For persistent extension storage across container recreations, add a named volume:
+
+```yaml
+volumes:
+  - devbox-vscode:/home/developer/.vscode-server
+```
+
 ### Rebuilding the Image
 
 `docker compose run` and `docker compose up` use the existing image — they **do not rebuild** when you change the Dockerfile or build args (e.g. updating `OPENCODE_VERSION`). Rebuild explicitly:
@@ -397,7 +433,7 @@ Host Machine
 ├── ~/.aws             ──bind mount──▶  /home/developer/.aws (Bedrock SSO)
 └── .env               ──env vars───▶  provider config + API keys
 
-Container (Debian bookworm)
+Container (Debian trixie)
 ├── opencode binary
 ├── oh-my-opencode-slim (optional — multi-agent orchestration plugin, includes Bun)
 ├── AWS CLI v2 (SSO + Bedrock auth)
@@ -420,6 +456,7 @@ Container (Debian bookworm)
 | `/home/developer/.local/share/uv` | Named volume `devbox-uv` (if configured) | ✅ Yes | Python installs, uv tool installs |
 | `/home/developer/.rustup` | Named volume `devbox-rustup` (if configured) | ✅ Yes | Rust toolchains |
 | `/home/developer/.cargo` | Named volume `devbox-cargo` (if configured) | ✅ Yes | Cargo binaries, registry cache |
+| `/home/developer/.vscode-server` | Named volume `devbox-vscode` (if configured) | ✅ Yes | VS Code server and extensions |
 | `/home/developer/.config/opencode` | Host bind mount (if configured) | ✅ Yes | opencode.json, oh-my-opencode-slim.json, skills |
 
 **opencode config** (`opencode.json`) is auto-generated from `OPENCODE_PROVIDER` on each start. It sets provider and model only — no MCP servers. To persist config changes and use custom settings, mount the config directory from the host (see Custom opencode config above).

docker-compose.yml

@@ -54,6 +54,9 @@ services:
       # - devbox-rustup:/home/developer/.rustup
       # - devbox-cargo:/home/developer/.cargo
 
+      # Optional: persist VS Code server and extensions across container recreations
+      # - devbox-vscode:/home/developer/.vscode-server
+
       # Optional: AWS credentials/SSO config (not read-only — SSO writes token cache)
       # - ~/.aws:/home/developer/.aws
 
@@ -62,3 +65,4 @@ volumes:
   devbox-uv:
   # devbox-rustup:
   # devbox-cargo:
+  # devbox-vscode: