diff --git a/.gitignore b/.gitignore
index e162c22d..92b39197 100644
--- a/.gitignore
+++ b/.gitignore
@@ -66,4 +66,4 @@ aipass_json/
 # Claude local settings (per-branch, not source code)
 .claude/
 
-setup-workspace.sh
+# setup-workspace.sh — tracked, needed for Docker build
diff --git a/setup-workspace.sh b/setup-workspace.sh
new file mode 100644
index 00000000..eb5a77a4
--- /dev/null
+++ b/setup-workspace.sh
@@ -0,0 +1,33 @@
+#!/bin/bash
+set -e
+
+WORKSPACE="/home/coder/workspace"
+PROJECT="$WORKSPACE/AIPass"
+FORK="git@github.com:Input-X/AIPass.git"
+UPSTREAM="git@github.com:AIOSAI/AIPass.git"
+
+export PATH="/opt/venv/bin:$PATH"
+
+# Ensure workspace directory exists and is writable
+mkdir -p "$WORKSPACE"
+if [ ! -w "$WORKSPACE" ]; then
+    echo "==> Fixing workspace permissions..."
+    sudo chown -R coder:coder "$WORKSPACE"
+fi
+
+# Clone repo if not already present
+if [ ! -d "$PROJECT/.git" ]; then
+    echo "==> First boot: cloning into AIPass/..."
+    git clone "$FORK" "$PROJECT"
+    cd "$PROJECT"
+    git remote add upstream "$UPSTREAM"
+    echo "==> Installing AIPass in editable mode..."
+    pip install -e .
+    echo "==> Workspace ready!"
+    echo "==> origin  = $FORK (your fork - push here)"
+    echo "==> upstream = $UPSTREAM (pull updates from here)"
+else
+    echo "==> Workspace exists, ensuring deps are installed..."
+    cd "$PROJECT"
+    pip install -e . 2>/dev/null || true
+fi