Environment variables

The app and runtime integration respect the following environment variables. Set them in your system environment or in a project .env file (if supported).

Desktop app (AI / runtime)

Variable	Description	Default
VITE_DEPLOYED_WEB_API_BASE	Explicit override for the apps/web API base. When unset, the shared resolver uses: local flags → local; staging / preview → https://staging.web.ssscript.app; built app → https://web.ssscript.app; dev default → https://staging.web.ssscript.app. Local is never implicit.	—
VITE_CLERK_PUBLISHABLE_KEY	Clerk publishable key (inlined at build). Set in apps/app/.env or CI to override. If unset, @repo/config uses packages/config/src/desktop-clerk.json: dev (vite / tauri dev) → test key, production build → live key (aligned with apps/web).	—
VITE_USE_LOCAL_WEB_API	Same intent as VITE_AI_GATEWAY_DEV_MODE: route AI to local apps/web (true) or use the shared branch/build resolver (false). Prefer this name in .env.	false
VITE_AI_GATEWAY_DEV_MODE	Alias for the AI base URL switch (or with USE_LOCAL_WEB_API).	false
VITE_LOCAL_WEB_API_BASE	Optional override for local web origin (default http://127.0.0.1:3001).	—
VITE_AGENT_RUNTIME_BASE_URL	Optional override for the Bun agent runtime (default http://127.0.0.1:4096).	—
VITE_LOCAL_DOCS_BASE	Optional local docs origin when using local web stack (default http://127.0.0.1:4321).	—
VITE_ACCOUNT_DEV_MODE	Route entitlements/checkout requests to local web API (true) or deployed API (false).	false
VITE_CLOUDFLARE_DEV_MODE	Route publish proxy requests to local web API (true) or deployed API (false).	false
VITE_CLERK_AI_TOKEN_TEMPLATE	Optional Clerk JWT template for AI token retrieval.	—

Web (apps/web): Anything safe to expose to the browser (if you add client-side Clerk or similar) belongs in .env / Vercel using your bundler’s public naming (often VITE_* for Vite). CLERK_SECRET_KEY and other secrets stay server-only — see apps/web/.env.example.

Web API (server-only)

Variable	Description	Default
AI_GATEWAY_API_KEY	Vercel AI Gateway API key used by /api/ai proxy routes.	—
AI_GATEWAY_BASE_URL	Optional override for AI Gateway base URL.	https://ai-gateway.vercel.sh/v1

The desktop app keeps runtime local, and sends model traffic through the web /api/ai proxy so provider keys stay server-side.

Agent runtime — Langfuse tracing (optional)

The Bun agent runtime drives every LLM call through the Vercel AI SDK. When the keys below are present it arms a Langfuse OpenTelemetry exporter at startup and tags each streamText / generateText call with experimental_telemetry, so traces (model name, token usage, tool calls, multi-step spans) appear in Langfuse. With the keys unset, tracing is a no-op. Traces are grouped by the runtime session id (Langfuse Sessions view) and tagged with the agent, workflow, and route for filtering.

Production-only: traces are emitted only when the runtime is pointed at the production web backend (web.ssscript.app) — i.e. real users. Local dev and staging (which the desktop app routes to localhost / staging.web.ssscript.app) never send traces. The check is dynamic (the AI base is synced after auth), and tracing is fully non-blocking: spans are batched and exported on a background timer, dropping rather than blocking if Langfuse is slow.

These are read by the spawned Bun process — set them in apps/app/.env (or repo-root .env) and restart dev. Keys come from the Langfuse UI → Settings → API Keys.

Variable	Description	Default
LANGFUSE_PUBLIC_KEY	Langfuse public key (pk-lf-…). Required to enable tracing.	—
LANGFUSE_SECRET_KEY	Langfuse secret key (sk-lf-…). Required to enable tracing.	—
LANGFUSE_BASE_URL	Langfuse host. EU: https://cloud.langfuse.com; US: https://us.cloud.langfuse.com; or self-hosted. LANGFUSE_HOST is also accepted.	https://cloud.langfuse.com
LANGFUSE_FORCE_ENABLE	Testing only — set to 1 to emit traces even when not on the production backend (e.g. local dev).	—
LANGFUSE_DEBUG	Set to 1 for verbose exporter logging while wiring it up.	—

Notes

• Staging web (A1): The backend can be deployed at https://staging.web.ssscript.app with PUBLIC_APP_OR_DOCS_URL set to that origin (separate Turso + Polar sandbox recommended). Turso: use TURSO_URL / TURSO_TOKEN with staging DB values on Preview/Development and production DB values on Vercel Production (same names, scoped per environment).
• For lightweight tasks, runtime may use a smaller model for plan mode while build uses the main edit model. In the UI, you choose these with the / mode picker (for example, /plan / /build).
• For local desktop development, run a :local dev script (pnpm dev:local / pnpm dev:app:local, or apps/app pnpm dev:local) or set VITE_USE_LOCAL_WEB_API=true (or VITE_AI_GATEWAY_DEV_MODE=true) so AI calls use http://127.0.0.1:3001/api/ai. With local flags off, dev defaults to staging (deployed, never localhost by accident); built apps target production unless built from staging/preview or via VITE_DEPLOYED_WEB_API_BASE. Staging signed builds: pnpm tauri:build:signed:staging (repo root), pass --staging, or build from the staging branch.
• Project agent.json is hydrated with a multi-model ssscript provider catalog (OpenAI, Anthropic, xAI, Google, Moonshot) and Webflow MCP settings when project setup runs. See Project structure and Bun runtime.
• Runtime details (structured @plan tags, auth.set, parallel slots, diff preview): Agent runtime integration.
• AI usage metering prefers gateway-reported cost; if unavailable, spend falls back to per-model pricing estimates.
• User-initiated bug reports from the AI panel and crash recovery flows are sent to the web API (POST /api/bug-report); see Bug reports & AI diagnostics.