diff --git a/.env.example b/.env.example
index cb45687..a3cd274 100644
--- a/.env.example
+++ b/.env.example
@@ -31,5 +31,9 @@ DEFAULT_EMBEDDING_DIM=0
 DEFAULT_EMBEDDING_REQUEST_TIMEOUT=60
 
 # === Frontend ===
-VITE_API_URL=http://localhost:8000
+# Vite dev-server proxy target — INSIDE the frontend container "localhost" is
+# the container itself, so docker-compose defaults this to http://backend:8000
+# (the service name). Override only if you run vite outside docker against a
+# host backend (in which case use http://localhost:8000).
+API_PROXY_TARGET=http://backend:8000
 FRONTEND_BUILD_TARGET=dev
diff --git a/docker-compose.yml b/docker-compose.yml
index b52a0f6..1f24054 100644
--- a/docker-compose.yml
+++ b/docker-compose.yml
@@ -129,7 +129,13 @@ services:
     depends_on:
       - backend
     environment:
-      VITE_API_URL: ${VITE_API_URL:-http://localhost:8000}
+      # Used by Vite's dev-server proxy (vite.config.ts) to forward /api calls.
+      # Inside the frontend container, "localhost" refers to the container itself,
+      # NOT the host — so we point at the docker-compose service name "backend".
+      # The host port (8000) is still published for direct browser/curl access.
+      # Deliberately NOT prefixed with `VITE_` so it cannot leak into the browser
+      # bundle (browser code uses relative "/api" URLs only — see src/api/index.ts).
+      API_PROXY_TARGET: ${API_PROXY_TARGET:-http://backend:8000}
     ports:
       - "5173:5173"
       - "8080:80"
diff --git a/frontend/vite.config.ts b/frontend/vite.config.ts
index 4b09196..7d401bc 100644
--- a/frontend/vite.config.ts
+++ b/frontend/vite.config.ts
@@ -14,7 +14,17 @@ export default defineConfig({
     port: 5173,
     proxy: {
       "/api": {
-        target: process.env.VITE_API_URL || "http://localhost:8000",
+        // NOTE: This URL is resolved INSIDE the vite dev-server container.
+        // `localhost` would refer to the container itself, not the host — so
+        // in docker-compose we set API_PROXY_TARGET=http://backend:8000 (the
+        // docker-compose service name). Outside docker (e.g. running vite
+        // locally against a backend on the host), leave it unset and the
+        // default http://localhost:8000 applies.
+        //
+        // Deliberately NOT prefixed with `VITE_` so it cannot leak into the
+        // browser bundle (browser code uses relative "/api" URLs only — see
+        // src/api/index.ts).
+        target: process.env.API_PROXY_TARGET || "http://localhost:8000",
         changeOrigin: true,
       },
     },