Environment variables
Build and CI
| Variable | Example | Required | Safe to expose? | Purpose | Failure behavior |
|---|---|---|---|---|---|
LINGUANA_PROJECT_TOKEN | lna_... | Remote build work | No | Manifest and paid-work authorization | Upload/translation returns authorization failure |
LINGUANA_API_URL | https://api.example.com | Remote compiler and SSR | Server configuration only | API origin for builds and server catalog reads | Registration or catalog load fails |
LINGUANA_UPLOAD | true | No | Build config, not secret | Enables manifest upload | false keeps extraction local |
LINGUANA_TRANSLATE | false | No | Build config, not secret | CLI templates translate development builds unless this is false | false uploads without translating |
LINGUANA_MAX_CHARGE_MICROS | 1000000 | No | Build config, not secret | Per-build translation ceiling in USD micros for CLI templates | Defaults to 1000000 ($1.00) |
GIT_COMMIT_SHA | Git revision | No | Yes | Records source revision in the manifest | Manifest omits source revision |
LINGUANA_PROJECT_ID | Project ID | CLI templates | Yes | Project for template builds; checked by linguana doctor | Connected templates refuse to build when it is missing or differs from VITE_LINGUANA_PROJECT_ID |
LINGUANA_ENVIRONMENT | development | CLI templates | Yes | Build environment for template builds | Connected templates refuse to build when it differs from VITE_LINGUANA_ENVIRONMENT |
Browser runtime
| Variable | Example | Required | Safe to expose? | Purpose |
|---|---|---|---|---|
VITE_LINGUANA_API_URL | https://api.example.com | Remote browser catalogs | Yes | Browser-reachable catalog API |
VITE_LINGUANA_PUBLISHABLE_KEY | pk_... | Remote browser catalogs | Yes | Read-only catalog authorization |
VITE_LINGUANA_PROJECT_ID | Project ID | CLI templates | Yes | Project the browser runtime reads |
VITE_LINGUANA_ENVIRONMENT | development | CLI templates | Yes | Environment the browser runtime reads |
Only intentionally public values should use the VITE_ prefix. Never create VITE_LINGUANA_PROJECT_TOKEN.
Written by the CLI
linguana link and linguana env pull write these values into .env.local, or .env.<environment>.local for other environments. Private and public pairs always match.
| Build/server variable | Browser variable | Value written |
|---|---|---|
LINGUANA_PROJECT_ID | VITE_LINGUANA_PROJECT_ID | Linked project ID |
LINGUANA_ENVIRONMENT | VITE_LINGUANA_ENVIRONMENT | Selected environment |
LINGUANA_API_URL | VITE_LINGUANA_API_URL | API origin |
LINGUANA_PROJECT_TOKEN | VITE_LINGUANA_PUBLISHABLE_KEY | Build token / public catalog-read key |
LINGUANA_UPLOAD | — | true |
LINGUANA_TRANSLATE | — | true for development, otherwise false |
LINGUANA_MAX_CHARGE_MICROS | — | 1000000 |
CLI
These variables configure the linguana command itself. They never belong in app environment files.
| Variable | Example | Required | Safe to expose? | Purpose |
|---|---|---|---|---|
LINGUANA_AUTH_TOKEN | Account session | No | No | Supplies a CLI account session for controlled automation instead of the saved login. Project build tokens are rejected |
LINGUANA_CONFIG_DIR | /tmp/linguana-cli | No | Yes | Directory for saved CLI account sessions |
See Sign in from the terminal.
Next.js
@linguanahq/next does not read environment variables by itself. Read them in next.config.ts and pass them to withLinguana. The Next.js guide uses these names:
| Variable | Passed to | Safe to expose? | Purpose |
|---|---|---|---|
LINGUANA_PROJECT_ID | projectId | Yes | Project identity |
LINGUANA_ENVIRONMENT | environment | Yes | Build and catalog environment |
LINGUANA_API_URL | apiUrl, runtime.catalogEndpoint | Yes | API origin for upload and catalogs |
LINGUANA_PROJECT_TOKEN | token | No | Build-only upload credential |
LINGUANA_UPLOAD | upload | Build config, not secret | Enables manifest upload during next build |
LINGUANA_PUBLISHABLE_KEY | runtime.publishableKey | Yes | Catalog-read key, shipped in public runtime configuration |
No NEXT_PUBLIC_ prefix is needed: withLinguana reads values when Next.js loads its configuration and exposes only the runtime options. Never pass the project token through runtime or a NEXT_PUBLIC_ variable.
Translation provider
| Variable | Example | Required | Safe to expose? | Purpose |
|---|---|---|---|---|
OPENROUTER_API_KEY | Provider secret | OpenRouter mode | No | Paid translation provider authorization |
OPENROUTER_MODEL | qwen/qwen3.8-flash | Provider-dependent | Server config only | Selects the provider model |
TRANSLATION_PROVIDER | openrouter | Server translation | Server config only | Selects deterministic or live provider adapter |
Documentation deployment
| Variable | Example | Required | Safe to expose? | Purpose |
|---|---|---|---|---|
DOCS_BASE_URL | https://docs.example.com | Hosted metadata | Yes | Canonical docs and llms.txt origin |
DOCS_PORT | 3004 | Deployment-dependent | Yes | Docs service port |
VITE_DOCS_URL | https://docs.example.com | Landing integration | Yes | Browser-visible docs destination |
Server and browser origins
The verified example uses LINGUANA_API_URL on the server and VITE_LINGUANA_API_URL in the browser because container networking and public browser origins may differ. Both must resolve the same API and project catalog scope.
See also
Classify build, runtime, CLI, Next.js, provider, and documentation settings by exposure and purpose.
Last updated November 17, 2026
Did this page get you to a working result?