Improve local Docker runner: auto-pick free port

docs/hf.md

@@ -32,6 +32,12 @@ Run the Docker image locally before pushing to HF:
 
 Then open `http://localhost:7860` and click **Start Conversation**.
 
+If `7860` is already in use locally, run:
+
+```bash
+HOST_PORT=7861 ./run_docker_local.sh
+```
+
 ## Deploy (push to Space repo)
 
 The Space is also configured as a git remote locally (`hf`).
@@ -55,4 +61,3 @@ git push --force hf main
   - Confirm `PORT` is being respected (HF sets it automatically; we bind to `0.0.0.0:$PORT`).
 - **OpenRouter errors**
   - Confirm `LLM_API_KEY` secret is set and `LLM_MODEL` is valid on OpenRouter.
-

run_docker_local.sh

@@ -10,6 +10,44 @@ ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 echo "Building Docker image: ${IMAGE_NAME}"
 docker build -t "${IMAGE_NAME}" "${ROOT_DIR}"
 
+port_in_use() {
+  local port="$1"
+  if command -v ss >/dev/null 2>&1; then
+    ss -ltn "sport = :${port}" 2>/dev/null | rg -q ":${port}\\b" && return 0 || return 1
+  fi
+  if command -v lsof >/dev/null 2>&1; then
+    lsof -nP -iTCP:"${port}" -sTCP:LISTEN >/dev/null 2>&1 && return 0 || return 1
+  fi
+  return 1
+}
+
+select_free_host_port() {
+  local start_port="$1"
+  local port="${start_port}"
+  local attempts=20
+
+  for _ in $(seq 1 "${attempts}"); do
+    if ! port_in_use "${port}"; then
+      echo "${port}"
+      return 0
+    fi
+    port=$((port + 1))
+  done
+
+  echo "${start_port}"
+  return 0
+}
+
+if port_in_use "${HOST_PORT}"; then
+  FREE_PORT="$(select_free_host_port "${HOST_PORT}")"
+  if [[ "${FREE_PORT}" != "${HOST_PORT}" ]]; then
+    echo "⚠️  Port ${HOST_PORT} is in use; using ${FREE_PORT} instead."
+    HOST_PORT="${FREE_PORT}"
+  else
+    echo "⚠️  Port ${HOST_PORT} appears to be in use; you can run with HOST_PORT=7861 ./run_docker_local.sh"
+  fi
+fi
+
 ENV_ARGS=()
 if [[ -f "${ROOT_DIR}/.env" ]]; then
   ENV_ARGS+=(--env-file "${ROOT_DIR}/.env")
@@ -21,4 +59,3 @@ exec docker run --rm -it \
   -e "PORT=${CONTAINER_PORT}" \
   "${ENV_ARGS[@]}" \
   "${IMAGE_NAME}"
-