feat(vertex): route frontend traffic through the server proxy

Author: Xichun123

.dockerignore

@@ -0,0 +1,2 @@
+# Never send local cloud credentials to the Docker build context.
+secrets/

.env.aistudio.example

@@ -0,0 +1,15 @@
+# AI Studio server-managed mode: the API key stays in the API container.
+GEMINI_BACKEND=aistudio
+GEMINI_API_KEY=
+GEMINI_API_BASE=https://generativelanguage.googleapis.com
+GOOGLE_APPLICATION_CREDENTIALS_DIR=./docker/empty-secrets
+GOOGLE_APPLICATION_CREDENTIALS=
+
+WEB_PORT=127.0.0.1:8080
+RUNTIME_SERVER_MANAGED_API=true
+RUNTIME_USE_CUSTOM_API_CONFIG=true
+RUNTIME_USE_API_PROXY=true
+RUNTIME_API_PROXY_URL=/api/gemini
+RUNTIME_PYODIDE_BASE_URL=
+RUNTIME_BACKEND_FLAVOR=aistudio
+RUNTIME_ENFORCE_API_CONFIG=true

.env.byok.example

@@ -0,0 +1,15 @@
+# AI Studio BYOK mode: each browser supplies its own Gemini API key.
+GEMINI_BACKEND=aistudio
+GEMINI_API_KEY=
+GEMINI_API_BASE=https://generativelanguage.googleapis.com
+GOOGLE_APPLICATION_CREDENTIALS_DIR=./docker/empty-secrets
+GOOGLE_APPLICATION_CREDENTIALS=
+
+WEB_PORT=127.0.0.1:8080
+RUNTIME_SERVER_MANAGED_API=false
+RUNTIME_USE_CUSTOM_API_CONFIG=true
+RUNTIME_USE_API_PROXY=true
+RUNTIME_API_PROXY_URL=/api/gemini
+RUNTIME_PYODIDE_BASE_URL=
+RUNTIME_BACKEND_FLAVOR=aistudio
+RUNTIME_ENFORCE_API_CONFIG=true

.env.example

@@ -12,6 +12,21 @@ PORT=3001
 ENABLE_MCP_STDIO=false
 ENABLE_MCP_PRIVATE_HTTP=false
 
+# Vertex AI backend. Keep aistudio for the existing API-key flow.
+# For Docker, put the Service Account JSON at ./secrets/sa.json, set
+# GOOGLE_APPLICATION_CREDENTIALS_DIR=./secrets, and use the container path below.
+# AI Studio/BYOK profiles should keep the default empty credentials directory.
+GEMINI_BACKEND=aistudio
+GCP_PROJECT_ID=
+GCP_LOCATION=us-central1
+GOOGLE_APPLICATION_CREDENTIALS_DIR=./docker/empty-secrets
+GOOGLE_APPLICATION_CREDENTIALS=
+
+# Optional Gemini Files API -> GCS adapter for Vertex mode.
+GCS_BUCKET=
+GCS_OBJECT_PREFIX=amc-files/
+GCS_MAX_FILE_BYTES=2147483648
+
 # Web container
 WEB_PORT=8080
 
@@ -21,3 +36,6 @@ RUNTIME_USE_CUSTOM_API_CONFIG=true
 RUNTIME_USE_API_PROXY=true
 RUNTIME_API_PROXY_URL=/api/gemini
 RUNTIME_PYODIDE_BASE_URL=
+RUNTIME_BACKEND_FLAVOR=aistudio
+# Set true only for deployment profiles that must override stale browser API settings.
+RUNTIME_ENFORCE_API_CONFIG=false

.env.vertex.example

@@ -0,0 +1,23 @@
+# Vertex AI: the API container authenticates with a Google Cloud Service Account.
+GEMINI_BACKEND=vertex
+GEMINI_API_KEY=
+GEMINI_API_BASE=https://generativelanguage.googleapis.com
+
+GCP_PROJECT_ID=your-gcp-project-id
+GCP_LOCATION=global
+GOOGLE_APPLICATION_CREDENTIALS_DIR=./secrets
+GOOGLE_APPLICATION_CREDENTIALS=/run/secrets/sa.json
+
+# Optional: enables Gemini Files API compatibility through GCS.
+GCS_BUCKET=
+GCS_OBJECT_PREFIX=amc-files/
+GCS_MAX_FILE_BYTES=2147483648
+
+WEB_PORT=127.0.0.1:8080
+RUNTIME_SERVER_MANAGED_API=true
+RUNTIME_USE_CUSTOM_API_CONFIG=true
+RUNTIME_USE_API_PROXY=true
+RUNTIME_API_PROXY_URL=/api/gemini
+RUNTIME_PYODIDE_BASE_URL=
+RUNTIME_BACKEND_FLAVOR=vertex
+RUNTIME_ENFORCE_API_CONFIG=true

docker-compose.yml

@@ -8,8 +8,17 @@ services:
       GEMINI_API_KEY: ${GEMINI_API_KEY:-}
       GEMINI_API_BASE: ${GEMINI_API_BASE:-https://generativelanguage.googleapis.com}
       ALLOWED_ORIGINS: ${ALLOWED_ORIGINS:-}
+      GEMINI_BACKEND: ${GEMINI_BACKEND:-aistudio}
+      GCP_PROJECT_ID: ${GCP_PROJECT_ID:-}
+      GCP_LOCATION: ${GCP_LOCATION:-us-central1}
+      GOOGLE_APPLICATION_CREDENTIALS: ${GOOGLE_APPLICATION_CREDENTIALS:-}
+      GCS_BUCKET: ${GCS_BUCKET:-}
+      GCS_OBJECT_PREFIX: ${GCS_OBJECT_PREFIX:-amc-files/}
+      GCS_MAX_FILE_BYTES: ${GCS_MAX_FILE_BYTES:-2147483648}
       ENABLE_MCP_STDIO: ${ENABLE_MCP_STDIO:-false}
       ENABLE_MCP_PRIVATE_HTTP: ${ENABLE_MCP_PRIVATE_HTTP:-false}
+    volumes:
+      - ${GOOGLE_APPLICATION_CREDENTIALS_DIR:-./docker/empty-secrets}:/run/secrets:ro
     expose:
       - '3001'
     restart: unless-stopped
@@ -26,6 +35,8 @@ services:
       RUNTIME_USE_API_PROXY: ${RUNTIME_USE_API_PROXY:-true}
       RUNTIME_API_PROXY_URL: ${RUNTIME_API_PROXY_URL:-/api/gemini}
       RUNTIME_PYODIDE_BASE_URL: ${RUNTIME_PYODIDE_BASE_URL:-}
+      RUNTIME_BACKEND_FLAVOR: ${RUNTIME_BACKEND_FLAVOR:-aistudio}
+      RUNTIME_ENFORCE_API_CONFIG: ${RUNTIME_ENFORCE_API_CONFIG:-false}
     ports:
       - '${WEB_PORT:-8080}:80'
     restart: unless-stopped

docker/empty-secrets/.gitkeep

@@ -1,7 +1,7 @@
 // Minimal static + reverse-proxy server for the Docker web container (Dockerfile.web).
 // Serves the web container:
 //   - serves static files from /usr/share/nginx/html with SPA fallback to index.html
-//   - proxies /api/* to http://api:3001 (path preserved, body + response streamed)
+//   - proxies /api/* and /health to http://api:3001 (path preserved, body + response streamed)
 //   - generates /runtime-config.js at startup from RUNTIME_* env vars
 //   - long-cache headers for /assets/*, no-store for /runtime-config.js
 // Uses only Node built-ins (http, fs, path) so no npm install is needed in the image.
@@ -21,6 +21,7 @@ const jsonStringOrNull = (value) => {
   if (!trimmed) return 'null';
   return JSON.stringify(trimmed);
 };
+const normalizeBackendFlavor = (value) => (trim(value).toLowerCase() === 'vertex' ? 'vertex' : 'aistudio');
 
 function writeRuntimeConfig() {
   const config = {
@@ -29,6 +30,8 @@ function writeRuntimeConfig() {
     useApiProxy: toBool(process.env.RUNTIME_USE_API_PROXY ?? 'true'),
     apiProxyUrl: JSON.parse(jsonStringOrNull(process.env.RUNTIME_API_PROXY_URL ?? '/api/gemini')),
     pyodideBaseUrl: JSON.parse(jsonStringOrNull(process.env.RUNTIME_PYODIDE_BASE_URL)),
+    backendFlavor: normalizeBackendFlavor(process.env.RUNTIME_BACKEND_FLAVOR),
+    enforceApiConfig: toBool(process.env.RUNTIME_ENFORCE_API_CONFIG),
   };
   const content = `window.__AMC_RUNTIME_CONFIG__ = ${JSON.stringify({ ...(globalThis.__AMC_RUNTIME_CONFIG__ || {}), ...config }, null, 2)};`;
   fs.writeFileSync(path.join(ROOT, 'runtime-config.js'), content);
@@ -146,7 +149,7 @@ function serveStatic(req, res) {
 
 const server = http.createServer((req, res) => {
   const pathname = new URL(req.url, 'http://localhost').pathname;
-  if (pathname === '/api' || pathname.startsWith('/api/')) {
+  if (pathname === '/health' || pathname === '/api' || pathname.startsWith('/api/')) {
     return proxyApi(req, res);
   }
   return serveStatic(req, res);

docker/web-server.js

@@ -12,6 +12,7 @@
     "build:analyze": "vite build --mode analyze",
     "build:api": "tsc -p server/tsconfig.json",
     "build:docker": "npm run build && npm run build:api",
+    "backend:switch": "bash scripts/switch-backend.sh",
     "preview": "vite preview",
     "clean": "rm -rf dist server/dist coverage playwright-report test-results tmp-live-artifact-demo .playwright-visible-demo-profile .codex-dev-*",
     "lint": "eslint . --ext .ts,.tsx,.js,.mjs --max-warnings=0",

package.json

@@ -4,5 +4,7 @@ window.__AMC_RUNTIME_CONFIG__ = {
   useApiProxy: false,
   apiProxyUrl: '/api/gemini',
   pyodideBaseUrl: null,
+  backendFlavor: 'aistudio',
+  enforceApiConfig: false,
   ...(window.__AMC_RUNTIME_CONFIG__ || {}),
 };