fix: remap compose agent URLs for native backend runs

The Agent tab 503'd because native spring-boot:run sourced Compose DNS
(deepsql-agent:8788) which does not resolve on the host. Remap those
hosts to loopback in start-backend.sh, and let the agent container reach
a host-side Java backend via host.docker.internal.

Co-authored-by: Venkat SF <venkatesh.sakamuri@stayflexi.com>

Author: cursoragent

.env.example

@@ -141,6 +141,9 @@ EMBEDDING_FAIL_OPEN=false
 # AGENT_WEBUI_URL          Agent HTTP API. Compose default: http://deepsql-agent:8787
 # AGENT_PROVISIONER_URL   Per-user profile provisioner. Compose default:
 #                         http://deepsql-agent:8788/provision
+# DEEPSQL_API_BASE_URL    Where the agent container's MCP tools call the backend.
+#                         Compose default: http://backend:8080/api/
+#                         Native Java + Compose agent: http://host.docker.internal:8080/api/
 # AGENT_PROVISION_SECRET  Shared secret between backend and agent (required).
 # DEEPSQL_AGENT_PORT / DEEPSQL_AGENT_PROVISIONER_PORT — host port mappings
 # (compose binds these to 127.0.0.1 only; public path is nginx /agent-api).

AGENTS.md

@@ -264,9 +264,16 @@ only covers cloud-specific, non-obvious caveats.
   non-`public` schemas (`crm`, `sales`, `finance`, `hr`, `inventory`) for Brain /
   MCP cross-schema checks. Prefer schema-qualified SQL (`sales.orders`); bare
   names follow the role’s `search_path` (usually `public`).
-- **`AGENT_WEBUI_URL` for native runs.** Default is `http://deepsql-agent:8787`
-  (Compose DNS). Native local must set `AGENT_WEBUI_URL=http://127.0.0.1:8787` in
-  `.env` or CLI/Slack `AgentChatClient` cannot reach the agent API.
+- **`AGENT_WEBUI_URL` / `AGENT_PROVISIONER_URL` for native runs.** Compose
+  defaults (`http://deepsql-agent:8787` and `…:8788/provision`) do not resolve
+  on the host. Native local must point both at loopback
+  (`http://127.0.0.1:8787` and `http://127.0.0.1:8788/provision`) or the Agent
+  tab returns 503 `Could not provision the DeepSQL Agent for this user`.
+  `scripts/start-backend.sh` remaps those hostnames automatically when they
+  don't resolve. If the agent container is used with a host-side Java backend,
+  set `DEEPSQL_API_BASE_URL=http://host.docker.internal:8080/api/` so MCP
+  tools can reach the native process (compose publishes `host.docker.internal`
+  via `extra_hosts`).
 - **DeepSQL CLI (`deepsql`) for agent testing.** Install from the repo package:
   `cd mcp && DEEPSQL_SKIP_AGENT_SETUP=1 npm install -g .` (prefix
   `~/.npm-global`, keep that on `PATH`). Auth against local backend with an MCP

docker-compose.yml

@@ -140,8 +140,10 @@ services:
       DEEPSQL_CHAT_API_KEY: ${DEEPSQL_CHAT_API_KEY:-}
       DEEPSQL_CHAT_ENDPOINT: ${DEEPSQL_CHAT_ENDPOINT:-}
       DEEPSQL_CHAT_MODEL: ${DEEPSQL_CHAT_MODEL:-gpt-5.4}
-      # Reach the backend over the compose network (MCP tools + provisioner)
-      DEEPSQL_API_BASE_URL: http://backend:8080/api/
+      # Reach the backend over the compose network (MCP tools + provisioner).
+      # Override to http://host.docker.internal:8080/api/ when the Java backend
+      # runs on the host (native `mvn spring-boot:run`) instead of Compose.
+      DEEPSQL_API_BASE_URL: ${DEEPSQL_API_BASE_URL:-http://backend:8080/api/}
       # Shared secret with backend AgentBridgeService
       AGENT_PROVISION_SECRET: ${AGENT_PROVISION_SECRET:-}
       # Origins allowed by the agent API CSRF check
@@ -153,6 +155,8 @@ services:
       DEEPSQL_AGENT_TRUSTED_PROXY_CIDRS: ${DEEPSQL_AGENT_TRUSTED_PROXY_CIDRS:-10.0.0.0/8,172.16.0.0/12,192.168.0.0/16}
       HERMES_WEBUI_TRUSTED_PROXY_CIDRS: ${DEEPSQL_AGENT_TRUSTED_PROXY_CIDRS:-10.0.0.0/8,172.16.0.0/12,192.168.0.0/16}
       HERMES_WEBUI_TRUSTED_AUTH_HEADER: X-Remote-User
+    extra_hosts:
+      - "host.docker.internal:host-gateway"
     ports:
       - "127.0.0.1:${DEEPSQL_AGENT_PORT:-8787}:8787"
       - "127.0.0.1:${DEEPSQL_AGENT_PROVISIONER_PORT:-8788}:8788"

scripts/remap-compose-hosts-for-native.sh

@@ -0,0 +1,22 @@
+# Sourced by scripts/start-backend.sh (outer shell and the inner bash -lc).
+# Compose service hostnames only resolve on the compose network. Native
+# `mvn spring-boot:run` still sources a Compose-oriented .env, so rewrite
+# those hosts to loopback when they don't resolve.
+if ! getent hosts postgres >/dev/null 2>&1; then
+    if [ -n "${DB_URL:-}" ]; then
+        export DB_URL="${DB_URL//:\/\/postgres:/:\/\/127.0.0.1:}"
+    fi
+fi
+if ! getent hosts valkey >/dev/null 2>&1; then
+    case "${SPRING_DATA_REDIS_HOST:-}" in
+        valkey|"") export SPRING_DATA_REDIS_HOST=127.0.0.1 ;;
+    esac
+fi
+if ! getent hosts deepsql-agent >/dev/null 2>&1; then
+    if [ -n "${AGENT_WEBUI_URL:-}" ]; then
+        export AGENT_WEBUI_URL="${AGENT_WEBUI_URL//deepsql-agent/127.0.0.1}"
+    fi
+    if [ -n "${AGENT_PROVISIONER_URL:-}" ]; then
+        export AGENT_PROVISIONER_URL="${AGENT_PROVISIONER_URL//deepsql-agent/127.0.0.1}"
+    fi
+fi

scripts/start-backend.sh

@@ -9,6 +9,8 @@ ENV_FILE="$PROJECT_ROOT/.env"
 echo "Starting DBA Agent Backend..."
 echo "================================"
 
+REMAP_SCRIPT="$SCRIPT_DIR/remap-compose-hosts-for-native.sh"
+
 if [ -f "$ENV_FILE" ]; then
     echo "Loading environment from .env..."
     set -a
@@ -18,13 +20,16 @@ if [ -f "$ENV_FILE" ]; then
         echo "Local source-run startup ignores SPRING_PROFILES_ACTIVE=prod from .env"
         unset SPRING_PROFILES_ACTIVE
     fi
+    # shellcheck source=remap-compose-hosts-for-native.sh
+    source "$REMAP_SCRIPT"
+    echo "Agent provisioner: ${AGENT_PROVISIONER_URL:-unset}"
 fi
 
 build_backend_launch_command() {
     local mvn_command="$1"
     local env_snippet=""
     if [ -f "$ENV_FILE" ]; then
-        env_snippet="set -a && source \"$ENV_FILE\" && set +a && if [ \"\${SPRING_PROFILES_ACTIVE:-}\" = \"prod\" ]; then unset SPRING_PROFILES_ACTIVE; fi && "
+        env_snippet="set -a && source \"$ENV_FILE\" && set +a && if [ \"\${SPRING_PROFILES_ACTIVE:-}\" = \"prod\" ]; then unset SPRING_PROFILES_ACTIVE; fi && source \"$REMAP_SCRIPT\" && "
     fi
     printf '%s' "${env_snippet}cd \"$PROJECT_ROOT/backend\" && exec ${mvn_command} spring-boot:run"
 }