diff --git a/.gitignore b/.gitignore
index 3ff195fbf..f10130cc8 100644
--- a/.gitignore
+++ b/.gitignore
@@ -18,6 +18,7 @@ cmd/**/workspace
 .picoclaw/
 config.json
 sessions/
+docker/data/
 build/
 
 # Coverage
diff --git a/README.fr.md b/README.fr.md
index c452b71ac..946e6daf8 100644
--- a/README.fr.md
+++ b/README.fr.md
@@ -190,17 +190,17 @@ docker compose -f docker/docker-compose.yml --profile gateway down
 
 ```bash
 # Poser une question
-docker compose -f docker/docker-compose.yml run --rm picoclaw-agent -m "Combien font 2+2 ?"
+docker compose -f docker/docker-compose.yml --profile agent run --rm picoclaw-agent -m "Combien font 2+2 ?"
 
 # Mode interactif
-docker compose -f docker/docker-compose.yml run --rm picoclaw-agent
+docker compose -f docker/docker-compose.yml --profile agent run --rm picoclaw-agent
 ```
 
 ### Mettre à jour
 
 ```bash
-docker compose -f docker/docker-compose.yml pull
-docker compose -f docker/docker-compose.yml --profile gateway up -d
+git pull
+docker compose -f docker/docker-compose.yml --profile gateway up --build -d
 ```
 
 ### 🚀 Démarrage Rapide
diff --git a/README.ja.md b/README.ja.md
index 6d5d09451..0349a555f 100644
--- a/README.ja.md
+++ b/README.ja.md
@@ -152,17 +152,17 @@ docker compose -f docker/docker-compose.yml --profile gateway down
 
 ```bash
 # 質問を投げる
-docker compose -f docker/docker-compose.yml run --rm picoclaw-agent -m "What is 2+2?"
+docker compose -f docker/docker-compose.yml --profile agent run --rm picoclaw-agent -m "What is 2+2?"
 
 # インタラクティブモード
-docker compose -f docker/docker-compose.yml run --rm picoclaw-agent
+docker compose -f docker/docker-compose.yml --profile agent run --rm picoclaw-agent
 ```
 
 ### アップデート
 
 ```bash
-docker compose -f docker/docker-compose.yml pull
-docker compose -f docker/docker-compose.yml --profile gateway up -d
+git pull
+docker compose -f docker/docker-compose.yml --profile gateway up --build -d
 ```
 
 ### 🚀 クイックスタート（ネイティブ）
diff --git a/README.md b/README.md
index b040d0605..cf7c98f9b 100644
--- a/README.md
+++ b/README.md
@@ -198,17 +198,17 @@ docker compose -f docker/docker-compose.yml --profile gateway down
 
 ```bash
 # Ask a question
-docker compose -f docker/docker-compose.yml run --rm picoclaw-agent -m "What is 2+2?"
+docker compose -f docker/docker-compose.yml --profile agent run --rm picoclaw-agent -m "What is 2+2?"
 
 # Interactive mode
-docker compose -f docker/docker-compose.yml run --rm picoclaw-agent
+docker compose -f docker/docker-compose.yml --profile agent run --rm picoclaw-agent
 ```
 
 ### Update
 
 ```bash
-docker compose -f docker/docker-compose.yml pull
-docker compose -f docker/docker-compose.yml --profile gateway up -d
+git pull
+docker compose -f docker/docker-compose.yml --profile gateway up --build -d
 ```
 
 ### 🚀 Quick Start
diff --git a/README.pt-br.md b/README.pt-br.md
index 61663e363..90994ac65 100644
--- a/README.pt-br.md
+++ b/README.pt-br.md
@@ -191,17 +191,17 @@ docker compose -f docker/docker-compose.yml --profile gateway down
 
 ```bash
 # Fazer uma pergunta
-docker compose -f docker/docker-compose.yml run --rm picoclaw-agent -m "Quanto e 2+2?"
+docker compose -f docker/docker-compose.yml --profile agent run --rm picoclaw-agent -m "Quanto e 2+2?"
 
 # Modo interativo
-docker compose -f docker/docker-compose.yml run --rm picoclaw-agent
+docker compose -f docker/docker-compose.yml --profile agent run --rm picoclaw-agent
 ```
 
 ### Atualizar
 
 ```bash
-docker compose -f docker/docker-compose.yml pull
-docker compose -f docker/docker-compose.yml --profile gateway up -d
+git pull
+docker compose -f docker/docker-compose.yml --profile gateway up --build -d
 ```
 
 ### 🚀 Início Rápido
diff --git a/README.vi.md b/README.vi.md
index f8ece7eda..d0840e908 100644
--- a/README.vi.md
+++ b/README.vi.md
@@ -171,17 +171,17 @@ docker compose -f docker/docker-compose.yml --profile gateway down
 
 ```bash
 # Đặt câu hỏi
-docker compose -f docker/docker-compose.yml run --rm picoclaw-agent -m "2+2 bằng mấy?"
+docker compose -f docker/docker-compose.yml --profile agent run --rm picoclaw-agent -m "2+2 bằng mấy?"
 
 # Chế độ tương tác
-docker compose -f docker/docker-compose.yml run --rm picoclaw-agent
+docker compose -f docker/docker-compose.yml --profile agent run --rm picoclaw-agent
 ```
 
 ### Cập nhật
 
 ```bash
-docker compose -f docker/docker-compose.yml pull
-docker compose -f docker/docker-compose.yml --profile gateway up -d
+git pull
+docker compose -f docker/docker-compose.yml --profile gateway up --build -d
 ```
 
 ### 🚀 Bắt đầu nhanh
diff --git a/README.zh.md b/README.zh.md
index 7c9351cb4..df89511d4 100644
--- a/README.zh.md
+++ b/README.zh.md
@@ -192,17 +192,17 @@ docker compose -f docker/docker-compose.yml --profile gateway down
 
 ```bash
 # 提问
-docker compose -f docker/docker-compose.yml run --rm picoclaw-agent -m "2+2 等于几？"
+docker compose -f docker/docker-compose.yml --profile agent run --rm picoclaw-agent -m "2+2 等于几？"
 
 # 交互模式
-docker compose -f docker/docker-compose.yml run --rm picoclaw-agent
+docker compose -f docker/docker-compose.yml --profile agent run --rm picoclaw-agent
 ```
 
 ### 更新镜像
 
 ```bash
-docker compose -f docker/docker-compose.yml pull
-docker compose -f docker/docker-compose.yml --profile gateway up -d
+git pull
+docker compose -f docker/docker-compose.yml --profile gateway up --build -d
 ```
 
 ### 🚀 快速开始
diff --git a/docker/Dockerfile b/docker/Dockerfile
index 480244127..f0678caeb 100644
--- a/docker/Dockerfile
+++ b/docker/Dockerfile
@@ -24,20 +24,23 @@ RUN apk add --no-cache ca-certificates tzdata curl
 
 # Health check
 HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \
-  CMD wget -q --spider http://localhost:18790/health || exit 1
+  CMD curl -fsS http://localhost:18790/health >/dev/null || exit 1
 
 # Copy binary
 COPY --from=builder /src/build/picoclaw /usr/local/bin/picoclaw
+COPY docker/entrypoint.sh /entrypoint.sh
 
 # Create non-root user and group
 RUN addgroup -g 1000 picoclaw && \
-    adduser -D -u 1000 -G picoclaw picoclaw
+    adduser -D -u 1000 -h /home/picoclaw -G picoclaw picoclaw && \
+    mkdir -p /home/picoclaw/.picoclaw && \
+    chown -R picoclaw:picoclaw /home/picoclaw && \
+    chmod +x /entrypoint.sh
+
+ENV HOME=/home/picoclaw
 
 # Switch to non-root user
 USER picoclaw
 
-# Run onboard to create initial directories and config
-RUN /usr/local/bin/picoclaw onboard
-
-ENTRYPOINT ["picoclaw"]
+ENTRYPOINT ["/entrypoint.sh"]
 CMD ["gateway"]
diff --git a/docker/docker-compose.yml b/docker/docker-compose.yml
index 9ec71abab..982b4d0d6 100644
--- a/docker/docker-compose.yml
+++ b/docker/docker-compose.yml
@@ -1,10 +1,29 @@
 services:
+  # ─────────────────────────────────────────────
+  # PicoClaw Init (one-shot bootstrap)
+  #   docker compose -f docker/docker-compose.yml --profile init run --rm picoclaw-init
+  # ─────────────────────────────────────────────
+  picoclaw-init:
+    image: picoclaw-local:dev
+    build:
+      context: ..
+      dockerfile: docker/Dockerfile
+    container_name: picoclaw-init
+    profiles:
+      - init
+    volumes:
+      - ./data:/home/picoclaw/.picoclaw
+    command: ["onboard"]
+
   # ─────────────────────────────────────────────
   # PicoClaw Agent (one-shot query)
-  #   docker compose -f docker/docker-compose.yml run --rm picoclaw-agent -m "Hello"
+  #   docker compose -f docker/docker-compose.yml --profile agent run --rm picoclaw-agent -m "Hello"
   # ─────────────────────────────────────────────
   picoclaw-agent:
-    image: docker.io/sipeed/picoclaw:latest
+    image: picoclaw-local:dev
+    build:
+      context: ..
+      dockerfile: docker/Dockerfile
     container_name: picoclaw-agent
     profiles:
       - agent
@@ -12,17 +31,20 @@ services:
     #extra_hosts:
     #  - "host.docker.internal:host-gateway"
     volumes:
-      - ./data:/root/.picoclaw
-    entrypoint: ["picoclaw", "agent"]
+      - ./data:/home/picoclaw/.picoclaw
+    entrypoint: ["/entrypoint.sh", "agent"]
     stdin_open: true
     tty: true
 
   # ─────────────────────────────────────────────
   # PicoClaw Gateway (Long-running Bot)
-  #   docker compose -f docker/docker-compose.yml up picoclaw-gateway
+  #   docker compose -f docker/docker-compose.yml --profile gateway up picoclaw-gateway
   # ─────────────────────────────────────────────
   picoclaw-gateway:
-    image: docker.io/sipeed/picoclaw:latest
+    image: picoclaw-local:dev
+    build:
+      context: ..
+      dockerfile: docker/Dockerfile
     container_name: picoclaw-gateway
     restart: on-failure
     profiles:
@@ -31,4 +53,4 @@ services:
     #extra_hosts:
     #  - "host.docker.internal:host-gateway"
     volumes:
-      - ./data:/root/.picoclaw
+      - ./data:/home/picoclaw/.picoclaw
diff --git a/docker/entrypoint.sh b/docker/entrypoint.sh
index b6fc724b5..a870918c3 100644
--- a/docker/entrypoint.sh
+++ b/docker/entrypoint.sh
@@ -1,15 +1,22 @@
 #!/bin/sh
 set -e
 
-# First-run: neither config nor workspace exists.
-# If config.json is already mounted but workspace is missing we skip onboard to
-# avoid the interactive "Overwrite? (y/n)" prompt hanging in a non-TTY container.
-if [ ! -d "${HOME}/.picoclaw/workspace" ] && [ ! -f "${HOME}/.picoclaw/config.json" ]; then
-    picoclaw onboard
-    echo ""
-    echo "First-run setup complete."
-    echo "Edit ${HOME}/.picoclaw/config.json (add your API key, etc.) then restart the container."
-    exit 0
+if [ "$#" -eq 0 ]; then
+    set -- gateway
 fi
 
-exec picoclaw gateway "$@"
+# First-run bootstrap for non-interactive Docker execution.
+# We key off config.json because `picoclaw onboard` only prompts when the config
+# already exists. This also repairs partial states where the workspace exists
+# but config.json was never created.
+if [ "$1" = "gateway" ] || [ "$1" = "agent" ]; then
+    if [ ! -f "${HOME}/.picoclaw/config.json" ]; then
+        picoclaw onboard
+        echo ""
+        echo "First-run setup complete."
+        echo "Edit ${HOME}/.picoclaw/config.json (add your API key, etc.) then restart the container."
+        exit 0
+    fi
+fi
+
+exec picoclaw "$@"