diff --git a/docker-compose.shared.yml b/docker-compose.shared.yml
index 904b175..d4fc54f 100644
--- a/docker-compose.shared.yml
+++ b/docker-compose.shared.yml
@@ -51,8 +51,12 @@ services:
       # where the repo lives on the host. Set SKILLSET_PATH in .env.
       # - ${SKILLSET_PATH}:/home/developer/skillset
 
-      # Opencode config — per-user (persists settings across restarts)
-      - ${HOME}/${SIGNUM}/.config/opencode:/home/developer/.config/opencode
+      # Persist opencode config (opencode.jsonc, oh-my-opencode-slim.json,
+      # instructions, etc.) across container recreations. Auto-generated on
+      # first start from env vars by generate-config.py and the skillset
+      # deploy script. Using a named volume keeps the container's symlinks
+      # independent from the host.
+      - devbox-opencode-config:/home/developer/.config/opencode
 
       # Persist opencode data (auth, memory, session history)
       - devbox-data:/home/developer/.local/share/opencode
@@ -79,6 +83,7 @@ services:
       # - ${HOME}/${SIGNUM}/.aws:/home/developer/.aws
 
 volumes:
+  devbox-opencode-config:
   devbox-data:
   devbox-shell-history:
   devbox-zoxide:
diff --git a/docker-compose.yml b/docker-compose.yml
index 6398209..e09c1b0 100644
--- a/docker-compose.yml
+++ b/docker-compose.yml
@@ -48,13 +48,19 @@ services:
       # where the repo lives on the host. Set SKILLSET_PATH in .env.
       # - ${SKILLSET_PATH}:/home/developer/skillset
 
-      # Optional: mount opencode config directory (persists config changes across restarts)
-      # Includes opencode.json, oh-my-opencode-slim.json, skills, etc.
-      # When mounted, OPENCODE_PROVIDER auto-config is skipped if opencode.json exists.
-      # - ~/.config/opencode:/home/developer/.config/opencode
+      # Persist opencode config (opencode.jsonc, oh-my-opencode-slim.json,
+      # instructions, etc.) across container recreations. Auto-generated on
+      # first start from env vars by generate-config.py and the skillset
+      # deploy script. Using a named volume (not a host bind mount) keeps
+      # the container's skill/instruction symlinks independent from the host,
+      # allowing both native and containerized opencode on the same machine.
+      - devbox-opencode-config:/home/developer/.config/opencode
 
-      # Optional: mount opencode agent skills from host
-      # - ~/.agents/skills:/home/developer/.agents/skills:ro
+      # NOTE: Do NOT bind-mount ~/.agents/skills/ from the host. The
+      # container manages its own skills directory independently — the
+      # entrypoint deploys skills from the skillset repo on each start.
+      # Sharing it with the host causes symlink conflicts (relative paths
+      # differ between host and container filesystem namespaces).
 
       # Optional: mount neovim config from host (plugins auto-install on first start)
       # - ~/.config/nvim:/home/developer/.config/nvim:ro
@@ -114,6 +120,7 @@ services:
       # - ~/.aws:/home/developer/.aws
 
 volumes:
+  devbox-opencode-config:
   devbox-data:
   devbox-state:
   devbox-shell-history: