From b3cfe641bb4c47f6abd054adacbb4712e19da3f4 Mon Sep 17 00:00:00 2001
From: Joakim Persson <joakim.persson@icloud.com>
Date: Sun, 12 Apr 2026 23:52:59 +0200
Subject: [PATCH] Document required host directories to prevent root-owned bind
 mount issues

---
 DOCKER_HUB.md | 14 +++++++++++++-
 README.md     | 12 ++++++++++++
 2 files changed, 25 insertions(+), 1 deletion(-)

diff --git a/DOCKER_HUB.md b/DOCKER_HUB.md
index 94f294e..a57841b 100644
--- a/DOCKER_HUB.md
+++ b/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
diff --git a/README.md b/README.md
index 1ae749a..94be686 100644
--- a/README.md
+++ b/README.md
@@ -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: