From bf459c7887881e223b97d72f3499b81b122f68ab Mon Sep 17 00:00:00 2001
From: Xubin Ren <xubinrencs@gmail.com>
Date: Mon, 6 Apr 2026 13:15:40 +0000
Subject: [PATCH] fix(docker): fix volume mount path and add permission error
 guidance

---
 Dockerfile    |  5 ++++-
 README.md     | 11 ++++++-----
 entrypoint.sh | 15 +++++++++++++++
 3 files changed, 25 insertions(+), 6 deletions(-)
 create mode 100755 entrypoint.sh

diff --git a/Dockerfile b/Dockerfile
index 141a6f9b3..45fea1f6f 100644
--- a/Dockerfile
+++ b/Dockerfile
@@ -37,11 +37,14 @@ RUN useradd -m -u 1000 -s /bin/bash nanobot && \
     mkdir -p /home/nanobot/.nanobot && \
     chown -R nanobot:nanobot /home/nanobot /app
 
+COPY entrypoint.sh /usr/local/bin/entrypoint.sh
+RUN chmod +x /usr/local/bin/entrypoint.sh
+
 USER nanobot
 ENV HOME=/home/nanobot
 
 # Gateway default port
 EXPOSE 18790
 
-ENTRYPOINT ["nanobot"]
+ENTRYPOINT ["entrypoint.sh"]
 CMD ["status"]
diff --git a/README.md b/README.md
index 0bf05625c..a2ea20f8c 100644
--- a/README.md
+++ b/README.md
@@ -1813,7 +1813,8 @@ print(resp.choices[0].message.content)
 ## 🐳 Docker
 
 > [!TIP]
-> The `-v ~/.nanobot:/root/.nanobot` flag mounts your local config directory into the container, so your config and workspace persist across container restarts.
+> The `-v ~/.nanobot:/home/nanobot/.nanobot` flag mounts your local config directory into the container, so your config and workspace persist across container restarts.
+> The container runs as user `nanobot` (UID 1000). If you get **Permission denied**, fix ownership on the host first: `sudo chown -R 1000:1000 ~/.nanobot`, or pass `--user $(id -u):$(id -g)` to match your host UID. Podman users can use `--userns=keep-id` instead.
 
 ### Docker Compose
 
@@ -1836,17 +1837,17 @@ docker compose down                                      # stop
 docker build -t nanobot .
 
 # Initialize config (first time only)
-docker run -v ~/.nanobot:/root/.nanobot --rm nanobot onboard
+docker run -v ~/.nanobot:/home/nanobot/.nanobot --rm nanobot onboard
 
 # Edit config on host to add API keys
 vim ~/.nanobot/config.json
 
 # Run gateway (connects to enabled channels, e.g. Telegram/Discord/Mochat)
-docker run -v ~/.nanobot:/root/.nanobot -p 18790:18790 nanobot gateway
+docker run -v ~/.nanobot:/home/nanobot/.nanobot -p 18790:18790 nanobot gateway
 
 # Or run a single command
-docker run -v ~/.nanobot:/root/.nanobot --rm nanobot agent -m "Hello!"
-docker run -v ~/.nanobot:/root/.nanobot --rm nanobot status
+docker run -v ~/.nanobot:/home/nanobot/.nanobot --rm nanobot agent -m "Hello!"
+docker run -v ~/.nanobot:/home/nanobot/.nanobot --rm nanobot status
 ```
 
 ## 🐧 Linux Service
diff --git a/entrypoint.sh b/entrypoint.sh
new file mode 100755
index 000000000..ab780dc96
--- /dev/null
+++ b/entrypoint.sh
@@ -0,0 +1,15 @@
+#!/bin/sh
+dir="$HOME/.nanobot"
+if [ -d "$dir" ] && [ ! -w "$dir" ]; then
+    owner_uid=$(stat -c %u "$dir" 2>/dev/null || stat -f %u "$dir" 2>/dev/null)
+    cat >&2 <<EOF
+Error: $dir is not writable (owned by UID $owner_uid, running as UID $(id -u)).
+
+Fix (pick one):
+  Host:   sudo chown -R 1000:1000 ~/.nanobot
+  Docker: docker run --user \$(id -u):\$(id -g) ...
+  Podman: podman run --userns=keep-id ...
+EOF
+    exit 1
+fi
+exec nanobot "$@"