Bump opencode to v1.4.6

Users can set LANG, LANGUAGE, LC_ALL in .env to override the default
en_US.UTF-8 locale (e.g. sv_SE.UTF-8 for Swedish).

.env.example

@@ -31,6 +31,11 @@ WORKSPACE_PATH=~/projects
 # Path to SSH keys on host
 SSH_KEY_PATH=~/.ssh
 
+# ── Locale (defaults to en_US.UTF-8) ─────────────────────────────────
+# LANG=sv_SE.UTF-8
+# LANGUAGE=sv_SE:sv
+# LC_ALL=sv_SE.UTF-8
+
 # ── oh-my-opencode-slim (multi-agent orchestration) ──────────────────
 # Requires image built with INSTALL_OMOS=true
 # ENABLE_OMOS=false

.gitea/workflows/docker-publish.yml

@@ -105,21 +105,21 @@ jobs:
 
       - name: Update Docker Hub description
         run: |
-          TOKEN=$(curl -s -X POST https://hub.docker.com/v2/users/login/ \
+          TOKEN=$(curl -s -X POST https://hub.docker.com/v2/auth/token \
             -H "Content-Type: application/json" \
-            -d '{"username":"${{ vars.DOCKERHUB_USERNAME }}","password":"${{ secrets.DOCKERHUB_TOKEN }}"}' \
+            -d '{"identifier":"${{ vars.DOCKERHUB_USERNAME }}","secret":"${{ secrets.DOCKERHUB_TOKEN }}"}' \
-            | jq -r .token)
+            | jq -r .access_token)
           if [ "$TOKEN" = "null" ] || [ -z "$TOKEN" ]; then
             echo "::error::Failed to authenticate with Docker Hub API"
             exit 1
           fi
           HTTP_CODE=$(jq -n \
             --rawfile full DOCKER_HUB.md \
-            --arg short "Portable AI dev environment for opencode. Debian-based with git, Node.js, AWS CLI, and SSH support. Available in base and omos (multi-agent) variants." \
+            --arg short "Portable AI dev environment for opencode. Debian-based with git, Node.js, AWS CLI, and SSH support." \
             '{"full_description": $full, "description": $short}' | \
             curl -s -o /tmp/hub-response.txt -w "%{http_code}" -X PATCH \
               "https://hub.docker.com/v2/repositories/${{ vars.DOCKERHUB_USERNAME }}/opencode-devbox/" \
-              -H "Authorization: JWT $TOKEN" \
+              -H "Authorization: Bearer $TOKEN" \
               -H "Content-Type: application/json" \
               -d @-)
           echo "Docker Hub API returned: $HTTP_CODE"

AGENTS.md

@@ -0,0 +1,47 @@
+# AGENTS.md
+
+## Project overview
+
+Docker image packaging [opencode](https://opencode.ai) into a production-ready dev container. Two image variants (base and omos) are published to Docker Hub via Gitea Actions CI. Not a library or application — this is infrastructure (Dockerfile, entrypoint scripts, docker-compose, documentation).
+
+## File roles
+
+- `Dockerfile` — single multi-stage build for both variants. OMOS variant is controlled by `INSTALL_OMOS=true` build arg. All GitHub-sourced binaries are pinned with version ARGs.
+- `entrypoint.sh` — runs as root: UID/GID adjustment, SSH permissions, volume ownership fixes. Then drops to developer via gosu.
+- `entrypoint-user.sh` — runs as developer: git config, opencode.json generation from env vars, OMOS setup.
+- `DOCKER_HUB.md` — pushed to Docker Hub description via CI API call. Must stay under 25KB. Short description field must be ≤100 bytes.
+- `README.md` — source repo documentation. Must stay in sync with DOCKER_HUB.md (both describe the same features but for different audiences).
+- `.gitea/workflows/docker-publish.yml` — CI pipeline: three parallel jobs (build-base, build-omos, update-description). Triggered by tag push only.
+
+## Versioning scheme
+
+Tags follow `v{opencode_version}{letter}` — e.g. `v1.4.3k`. The number matches the opencode npm version. The letter suffix increments for container-level changes (tooling, docs, CVE fixes) on the same opencode version. CI produces four Docker Hub tags per release: `vX.Y.Zn`, `latest`, `vX.Y.Zn-omos`, `latest-omos`.
+
+## Critical conventions
+
+- **entrypoint.sh volume ownership loop** — when adding a new named volume mount point, add it to the `for dir in ...` loop in `entrypoint.sh` so root-owned volumes get chowned on startup.
+- **Three docs to keep in sync** — Dockerfile changes that add tools or features must be reflected in `README.md`, `DOCKER_HUB.md`, and `.env.example`. The docker-compose examples in both docs must match the source `docker-compose.yml` pattern.
+- **GitHub-sourced binaries** — fzf, gosu, git-lfs, neovim, bat, eza, zoxide, uv, rustup are installed from upstream releases (not apt) with pinned versions. Use the same `ARCH` case-switch pattern for multi-arch support (amd64/arm64).
+- **Shell scripts use `set -euo pipefail`** — both entrypoints are strict. Errors in volume chown or SSH permission operations are intentionally suppressed with `|| true`.
+- **Docker Hub description update** — uses `/v2/auth/token` endpoint (not the deprecated `/v2/users/login`). Auth uses `identifier`/`secret` fields, returns `access_token`, sent as `Bearer`. Short description must be ≤100 bytes.
+
+## CI quirks
+
+- Both build jobs include an IPv4 preference step (`gai.conf` + `driver-opts: network=host` for buildx) to work around intermittent IPv6 failures on the Gitea runners.
+- `update-description` job runs only when both builds succeed (`needs: [build-base, build-omos]`).
+- Tags must be pushed to trigger CI. Pushing to `main` alone does not build images.
+
+## Testing changes
+
+No test suite. Verify by:
+1. Building locally: `docker compose build`
+2. Running: `docker compose run --rm devbox bash`
+3. Checking tool availability inside container: `nvim --version`, `bat --version`, `uv --version`, etc.
+4. For entrypoint changes: test with a non-1000 UID workspace to verify UID adjustment and volume ownership fixes.
+
+## Commit style
+
+Imperative mood, first line summarizes the change. Multi-line body explains "why" when non-obvious. Examples from history:
+- `Fix ownership of named volume mount points in entrypoint`
+- `Add uv package manager to base image for on-demand Python support`
+- `Upgrade base image from Debian bookworm to trixie (current stable)`

DOCKER_HUB.md

@@ -114,12 +114,43 @@ The entrypoint automatically detects the owner of `/workspace` and adjusts the c
 | `USER_UID` | Container user UID | Auto-detect from `/workspace` owner |
 | `USER_GID` | Container user GID | Auto-detect from `/workspace` owner |
 
-## Initial Setup
+### Locale and Editor
 
-### 1. Create a project directory
+The container defaults to English (`en_US.UTF-8`) and neovim as the editor. Override via environment variables:
+
+| Variable | Description | Default |
+|---|---|---|
+| `LANG` | System locale | `en_US.UTF-8` |
+| `LANGUAGE` | Language priority list | `en_US:en` |
+| `LC_ALL` | Override all locale settings | `en_US.UTF-8` |
+| `EDITOR` | Default text editor | `nvim` |
+
+All common UTF-8 locales are pre-generated in the image. Example for Swedish:
 
 ```bash
+LANG=sv_SE.UTF-8
+LANGUAGE=sv_SE:sv
+LC_ALL=sv_SE.UTF-8
+```
+
+## Initial Setup
+
+### 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
@@ -145,7 +176,7 @@ GIT_USER_EMAIL=you@example.com
 **AWS Bedrock (SSO):**
 ```bash
 OPENCODE_PROVIDER=amazon-bedrock
-OPENCODE_MODEL=amazon-bedrock/anthropic.claude-sonnet-4-5-v1
+OPENCODE_MODEL=amazon-bedrock/eu.anthropic.claude-opus-4-6-v1
 AWS_REGION=eu-west-1
 AWS_PROFILE=your-profile-name
 GIT_USER_NAME=Your Name
@@ -184,6 +215,10 @@ Understanding what survives container restarts and what doesn't:
 | `/home/developer/.ssh` | Host bind mount (ro) | ✅ Yes — lives on host | SSH keys |
 | `/home/developer/.aws` | Host bind mount | ✅ Yes — lives on host | AWS credentials/SSO cache |
 | `/home/developer/.local/share/opencode` | Named volume (if configured) | ✅ Yes — Docker volume | Session history, memory, auth tokens |
+| `/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
@@ -191,6 +226,8 @@ Understanding what survives container restarts and what doesn't:
 - **Project files** (`/workspace`) are always safe — they're your host filesystem.
 - **opencode config** is auto-generated from `OPENCODE_PROVIDER` env var on each start if no existing config is found. To persist config changes, mount the config directory from the host (see Custom opencode Config below).
 - **opencode data** (session history, memory) is lost with `--rm` unless you add a named volume.
+- **Python installs** via `uv python install` are lost unless you add the `devbox-uv` named volume.
+- **Rust toolchains** via `rustup-init` are lost unless you add the `devbox-rustup` and `devbox-cargo` named volumes.
 - **AWS SSO tokens** persist across restarts when `~/.aws` is mounted (recommended for Bedrock users).
 
 ## Custom opencode Config
@@ -217,6 +254,114 @@ docker run -it --rm \
   joakimp/opencode-devbox:latest
 ```
 
+## Python Development with uv
+
+The image includes Python 3.13 (from Debian Trixie) and [uv](https://docs.astral.sh/uv/), a fast Python package manager that replaces pip, venv, and pyenv:
+
+```bash
+# Python 3.13 is available out of the box
+python3 --version
+
+# Use uv for package management
+uv venv
+uv pip install -r requirements.txt
+
+# Or use uv's project workflow (reads pyproject.toml)
+uv sync
+
+# Run a Python script
+uv run python script.py
+
+# Install standalone Python tools
+uvx ruff check .
+
+# Install a newer Python version (persists with devbox-uv volume)
+uv python install 3.14
+```
+
+To persist Python installs across container restarts, add a named volume:
+
+```bash
+docker run -it --rm \
+  -v devbox-uv:/home/developer/.local/share/uv \
+  ... \
+  joakimp/opencode-devbox:latest
+```
+
+Project virtual environments (`.venv`) are stored in your workspace directory and persist automatically via the `/workspace` bind mount.
+
+## Rust Development with rustup
+
+The image includes `rustup-init`, the Rust toolchain installer. Rust is not pre-installed but can be bootstrapped on demand:
+
+```bash
+# One-time setup: install Rust toolchain (~300MB, persists with volumes)
+rustup-init -y
+source ~/.cargo/env
+
+# Now use Rust normally
+cargo new my-project
+cargo build
+cargo run
+```
+
+To persist Rust toolchains and cargo data across container restarts, add named volumes:
+
+```bash
+docker run -it --rm \
+  -v devbox-rustup:/home/developer/.rustup \
+  -v devbox-cargo:/home/developer/.cargo \
+  ... \
+  joakimp/opencode-devbox:latest
+```
+
+## JavaScript and TypeScript
+
+The base image includes **Node.js 22** and **npm** — sufficient for most JavaScript and TypeScript development:
+
+```bash
+# Initialize a new project
+npm init -y
+
+# Install dependencies
+npm install
+
+# Run TypeScript (via tsx, ts-node, etc.)
+npx tsx src/index.ts
+```
+
+The OMOS image variant also includes **Bun**, a faster JavaScript runtime and package manager:
+
+```bash
+bun init
+bun install
+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:
@@ -229,7 +374,7 @@ mkdir opencode-devbox && cd opencode-devbox
 
 ```bash
 OPENCODE_PROVIDER=amazon-bedrock
-OPENCODE_MODEL=amazon-bedrock/anthropic.claude-sonnet-4-5-v1
+OPENCODE_MODEL=amazon-bedrock/eu.anthropic.claude-opus-4-6-v1
 AWS_REGION=eu-west-1
 AWS_PROFILE=your-profile-name
 GIT_USER_NAME=Your Name
@@ -254,6 +399,13 @@ services:
       - ~/projects:/workspace
       - ~/.ssh:/home/developer/.ssh:ro
       - devbox-data:/home/developer/.local/share/opencode
+      # Optional: persist Python/uv installs across restarts
+      # - devbox-uv:/home/developer/.local/share/uv
+      # 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)
@@ -265,6 +417,10 @@ services:
 
 volumes:
   devbox-data:
+  # 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.
@@ -294,11 +450,11 @@ 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
-- **Dev tools** — git, git-lfs, ssh, ripgrep, fd, fzf, bat, eza, zoxide, jq, make, curl, wget, neovim 0.12, tmux, htop, tree
+- **Dev tools** — git, git-lfs, ssh, ripgrep, fd, fzf, bat, eza, zoxide, uv, rustup, jq, make, curl, wget, neovim 0.12, tmux, htop, tree
 - **Non-root user** — runs as `developer` with UID auto-matched to workspace owner (sudo available)
 
 ### OMOS image (`latest-omos`)

Dockerfile

@@ -1,11 +1,11 @@
 # 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
-ARG OPENCODE_VERSION=1.4.3
+ARG OPENCODE_VERSION=1.4.6
 
 LABEL maintainer="joakimp"
 LABEL description="Portable opencode developer container"
@@ -90,12 +90,30 @@ RUN ARCH=$(case "${TARGETARCH}" in amd64) echo "x86_64" ;; arm64) echo "aarch64"
     curl -fsSL "https://github.com/ajeetdsouza/zoxide/releases/download/v${ZOXIDE_VERSION}/zoxide-${ZOXIDE_VERSION}-${ARCH}-unknown-linux-musl.tar.gz" | tar -xz -C /usr/local/bin zoxide && \
     zoxide --version
 
-# Set locale
+# uv — fast Python package manager (replaces pip, venv, pyenv)
-RUN sed -i '/en_US.UTF-8/s/^# //g' /etc/locale.gen && locale-gen
+ARG UV_VERSION=0.11.6
+RUN ARCH=$(case "${TARGETARCH}" in amd64) echo "x86_64" ;; arm64) echo "aarch64" ;; *) echo "x86_64" ;; esac) && \
+    curl -fsSL "https://github.com/astral-sh/uv/releases/download/${UV_VERSION}/uv-${ARCH}-unknown-linux-musl.tar.gz" | tar -xz -C /tmp && \
+    install /tmp/uv-${ARCH}-unknown-linux-musl/uv /usr/local/bin/uv && \
+    install /tmp/uv-${ARCH}-unknown-linux-musl/uvx /usr/local/bin/uvx && \
+    rm -rf /tmp/uv-* && \
+    uv --version
+
+# rustup — Rust toolchain manager
+# Installs the rustup-init binary only. Users bootstrap Rust with:
+#   rustup-init -y && source ~/.cargo/env
+# Toolchains persist via devbox-rustup and devbox-cargo volumes.
+RUN ARCH=$(case "${TARGETARCH}" in amd64) echo "x86_64" ;; arm64) echo "aarch64" ;; *) echo "x86_64" ;; esac) && \
+    curl -fsSL "https://static.rust-lang.org/rustup/dist/${ARCH}-unknown-linux-gnu/rustup-init" -o /usr/local/bin/rustup-init && \
+    chmod +x /usr/local/bin/rustup-init
+
+# Set locale — generate common UTF-8 locales (override via LANG/LC_ALL env vars)
+RUN sed -i '/\.UTF-8/s/^# //g' /etc/locale.gen && locale-gen
 ENV LANG=en_US.UTF-8
 ENV LANGUAGE=en_US:en
 ENV LC_ALL=en_US.UTF-8
 ENV EDITOR=nvim
+ENV PATH="/home/developer/.local/bin:/home/developer/.cargo/bin:${PATH}"
 
 # ── Node.js (required for opencode v1.x install + MCP servers) ──────
 ARG NODE_VERSION=22

README.md

@@ -27,19 +27,33 @@ 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
 - **MCP server support** — Node.js included for `npx`-based MCP servers
 - **Non-root user** — runs as `developer` with UID auto-matched to workspace owner (sudo available)
-- **Optional runtimes** — Python, Go via build args (Node.js always included — required for opencode v1.x)
+- **Python via uv** — `uv` package manager included; install Python on demand with `uv python install`
+- **Rust via rustup** — `rustup-init` included; bootstrap Rust on demand with `rustup-init -y`
+- **Optional runtimes** — Python (apt), Go via build args (Node.js always included — required for opencode v1.x)
 - **Multi-agent orchestration** — optional [oh-my-opencode-slim](https://github.com/alvinunreal/oh-my-opencode-slim) integration via build arg
 - **AWS CLI v2** — built-in SSO/Bedrock authentication with headless device-code flow
 - **Multi-arch** — amd64 and arm64
 
 ## 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:
@@ -103,6 +117,10 @@ docker compose exec -u developer devbox aws --version
 | `SSH_KEY_PATH` | Host SSH key directory | `~/.ssh` |
 | `USER_UID` | Override container user UID | Auto-detect from `/workspace` |
 | `USER_GID` | Override container user GID | Auto-detect from `/workspace` |
+| `LANG` | System locale | `en_US.UTF-8` |
+| `LANGUAGE` | Language priority list | `en_US:en` |
+| `LC_ALL` | Override all locale settings | `en_US.UTF-8` |
+| `EDITOR` | Default text editor | `nvim` |
 | `ENABLE_OMOS` | Enable oh-my-opencode-slim multi-agent orchestration | `false` |
 | `OMOS_TMUX` | Enable tmux pane integration for OMOS | `false` |
 | `OMOS_SKILLS` | Install OMOS recommended skills on first run | `true` |
@@ -137,6 +155,122 @@ volumes:
   - ~/.config/nvim:/home/developer/.config/nvim:ro
 ```
 
+### Python development with uv
+
+The image includes Python 3.13 (from Debian Trixie) and [uv](https://docs.astral.sh/uv/), a fast Python package manager that replaces pip, venv, and pyenv:
+
+```bash
+# Python 3.13 is available out of the box
+python3 --version
+
+# Use uv for package management
+uv venv
+uv pip install -r requirements.txt
+
+# Or use uv's project workflow (reads pyproject.toml)
+uv sync
+
+# Run a Python script
+uv run python script.py
+
+# Install standalone Python tools
+uvx ruff check .
+
+# Install a newer Python version (persists with devbox-uv volume)
+uv python install 3.14
+```
+
+Python installations are stored in `~/.local/share/uv/`. To persist them across container restarts, add the `devbox-uv` named volume to your `docker-compose.yml`:
+
+```yaml
+volumes:
+  - devbox-uv:/home/developer/.local/share/uv
+
+volumes:
+  devbox-uv:
+```
+
+Project virtual environments (`.venv`) are stored in your workspace directory and persist automatically via the `/workspace` bind mount.
+
+### Rust development with rustup
+
+The image includes `rustup-init`, the Rust toolchain installer. Rust is not pre-installed but can be bootstrapped on demand:
+
+```bash
+# One-time setup: install Rust toolchain (~300MB, persists with volumes)
+rustup-init -y
+source ~/.cargo/env
+
+# Now use Rust normally
+cargo new my-project
+cargo build
+cargo run
+```
+
+To persist Rust toolchains and cargo data across container restarts, add named volumes to your `docker-compose.yml`:
+
+```yaml
+volumes:
+  - devbox-rustup:/home/developer/.rustup
+  - devbox-cargo:/home/developer/.cargo
+
+volumes:
+  devbox-rustup:
+  devbox-cargo:
+```
+
+### JavaScript and TypeScript
+
+The base image includes **Node.js 22** and **npm** — sufficient for most JavaScript and TypeScript development:
+
+```bash
+# Initialize a new project
+npm init -y
+
+# Install dependencies
+npm install
+
+# Run TypeScript (via tsx, ts-node, etc.)
+npx tsx src/index.ts
+
+# Use npx for one-off tools
+npx tsc --init
+```
+
+The OMOS image variant also includes **Bun**, a faster JavaScript runtime and package manager:
+
+```bash
+bun init
+bun install
+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:
@@ -306,11 +440,11 @@ 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)
-├── neovim 0.12, tmux, htop, bat, eza, zoxide, make
+├── neovim 0.12, tmux, htop, bat, eza, zoxide, uv, rustup, make
 ├── git, ssh, ripgrep, fd, fzf, jq, curl, tree
 ├── Node.js (for MCP servers)
 ├── Bun (optional — included with oh-my-opencode-slim)
@@ -326,6 +460,10 @@ Container (Debian bookworm)
 | `/home/developer/.ssh` | Host bind mount (ro) | ✅ Yes | SSH keys |
 | `/home/developer/.aws` | Host bind mount (if configured) | ✅ Yes | AWS credentials/SSO cache |
 | `/home/developer/.local/share/opencode` | Named volume `devbox-data` | ✅ Yes | Session history, memory |
+| `/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

@@ -45,8 +45,24 @@ services:
       # Optional: persist opencode data (auth, memory, etc.)
       - devbox-data:/home/developer/.local/share/opencode
 
+      # Optional: persist uv data (Python installs, tool installs)
+      # Without this, 'uv python install' must be re-run after container removal.
+      - devbox-uv:/home/developer/.local/share/uv
+
+      # Optional: persist Rust toolchains and cargo data
+      # Without this, 'rustup-init' must be re-run after container removal.
+      # - 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
 
 volumes:
   devbox-data:
+  devbox-uv:
+  # devbox-rustup:
+  # devbox-cargo:
+  # devbox-vscode:

entrypoint-user.sh

@@ -48,7 +48,8 @@ EOF
   "provider": {
     "amazon-bedrock": {
       "options": {
-        "region": "${AWS_REGION:-us-east-1}"
+        "region": "${AWS_REGION:-us-east-1}",
+        "profile": "${AWS_PROFILE:-default}"
       }
     }
   }

entrypoint.sh

@@ -46,5 +46,24 @@ if [ -d "/home/$USER_NAME/.ssh" ] && [ "$(ls -A "/home/$USER_NAME/.ssh" 2>/dev/n
   fi
 fi
 
+# ── Fix ownership of named volume mount points ──────────────────────
+# Named volumes are created as root on first use. Fix ownership so the
+# developer user can write to them.
+FINAL_UID="${TARGET_UID:-$CURRENT_UID}"
+FINAL_GID="${TARGET_GID:-$CURRENT_GID}"
+for dir in \
+  /home/"$USER_NAME"/.local/share/opencode \
+  /home/"$USER_NAME"/.local/share/uv \
+  /home/"$USER_NAME"/.rustup \
+  /home/"$USER_NAME"/.cargo \
+  /home/"$USER_NAME"/.vscode-server \
+  /home/"$USER_NAME"/.config/opencode \
+  /home/"$USER_NAME"/.config/nvim \
+  /home/"$USER_NAME"/.agents/skills; do
+  if [ -d "$dir" ] && [ "$(stat -c '%u' "$dir" 2>/dev/null)" != "$FINAL_UID" ]; then
+    chown -R "$FINAL_UID":"$FINAL_GID" "$dir" 2>/dev/null || true
+  fi
+done
+
 # ── Drop to developer user for remaining setup ──────────────────────
 exec gosu "$USER_NAME" /usr/local/bin/entrypoint-user.sh "$@"