Required Environment Variables

The Docker stack works only when the required values in docker/.stack.env are set. This page is aligned with the current docker/.stack.env.example in this repo.

How to read this page

• Each section links to a deeper page for the variable family.
• docker/.stack.env is separate from the host-native .env used by make dev-all.
• Keep this file out of Git.

Frontend build /docs/required-environment-variables/frontend-env

Variable	Status	Notes
FRONTEND_BUILD_MODE	Required	Usually production for the stack build.
VITE_API_URL	Required	Browser-visible backend URL.
VITE_GOOGLE_CLIENT_ID	Optional	Browser OAuth surface.
VITE_STRIPE_PUBLISHABLE_KEY	Optional	Needed only when billing UI is enabled.
VITE_SENTRY_DSN	Optional	Browser telemetry.
VITE_DISABLE_CHAT_MODE	Optional	UI feature flag.

Networking and tunnels /docs/required-environment-variables/networking-tunnels

Variable	Status	Notes
NGROK_AUTHTOKEN	Optional in practice	Only required if you manually run the ngrok service.
NGROK_REGION	Required with ngrok	Region code for the tunnel agent.
NGROK_AGENT_EXTRA_ARGS	Optional	Extra flags when you need reserved domains or special headers.

Host paths /docs/required-environment-variables/host-paths

Variable	Status	Notes
GOOGLE_APPLICATION_CREDENTIALS	Required for GCP-backed stack usage	Absolute path to the mounted service-account JSON.

Models and auth /docs/required-environment-variables/llm-auth

Variable	Status	Notes
MODEL_CONFIGS	Required	JSON array describing the models available in the stack.
RESEARCHER_AGENT_CONFIG	Required placeholder	Specialized research roles; can stay minimal until you enable them.
JWT_SECRET_KEY	Required	Backend JWT signing secret.
SESSION_SECRET_KEY	Required	Session middleware secret.
AUTH_SECRET_KEY	Required	Shared auth secret for the tool-facing stack surfaces.
ACCESS_TOKEN_EXPIRE_MINUTES	Required	Access-token TTL.
GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET, GOOGLE_REDIRECT_URI	Optional	OAuth configuration.

Storage /docs/required-environment-variables/storage

Variable	Status	Notes
STORAGE_PROVIDER	Required	gcs in the current stack example.
STORAGE_PROJECT_ID	Required with GCS	GCP project that owns the bucket.
STORAGE_BUCKET_NAME	Required with GCS	Bucket for persisted assets.
STORAGE_CUSTOM_DOMAIN	Optional	External asset domain when applicable.
GOOGLE_CLOUD_PROJECT, GOOGLE_CLOUD_LOCATION	Optional but commonly paired	Useful when storage and model usage share GCP context.

Sandbox provider /docs/required-environment-variables/backend-sandbox

Variable	Status	Notes
SANDBOX_PROVIDER	Required	Current example uses e2b.
SANDBOX_E2B_API_KEY	Required for E2B	Provider auth key.
SANDBOX_E2B_TEMPLATE_ID	Required for E2B	Template or base image identifier.
SANDBOX_TIME_TIL_CLEAN_UP	Required	Idle timeout in seconds.

Tool server baseline /docs/required-environment-variables/tool-server-baseline

Variable	Status	Notes
STORAGE_CONFIG__GCS_BUCKET_NAME, STORAGE_CONFIG__GCS_PROJECT_ID	Required when the standalone tool server writes to GCS	ii_agent_tools reads these without the TOOL__ prefix.

Core infrastructure /docs/required-environment-variables/core-infra

Variable	Status	Notes
POSTGRES_USER, POSTGRES_PASSWORD, POSTGRES_DB, POSTGRES_PORT	Required	Local Postgres credentials and host mapping.
DATABASE_URL	Required	Async backend DB URL.
SANDBOX_DB_NAME, SANDBOX_DATABASE_URL	Required in the current stack example	Separate DB for sandbox-related services.
REDIS_PORT	Required	Host port for Redis.
TOOL_SERVER_URL	Required	Internal service URL the backend uses inside the stack.
BACKEND_PORT, FRONTEND_PORT, SANDBOX_SERVER_PORT, TOOL_SERVER_PORT, NGROK_METRICS_PORT, MCP_PORT	Required	Host-facing service ports.

Validation checklist

1. Copy docker/.stack.env.example to docker/.stack.env.
2. Fill the required values above.
3. Run make stack-build.
4. Verify http://localhost:8000/health, http://localhost:1236/health, and http://localhost:8100/health.