Variable types
Pick Frontend, Backend, or Backend secret for each variable so every value reaches only the code that needs it.
Choose a type
The type decides where a value goes and who can read it. Choose it from what would happen if the value leaked: public configuration can ship to the browser, server configuration stays on the backend, and credentials get the extra protection of a secret.
| Criteria | Frontend | Backend | Backend secret |
|---|---|---|---|
| Reaches | The browser bundle, built in at build time. | Backend code at runtime. Never sent to the browser. | Backend code at runtime. Never sent to the browser. |
| Who can read it | Every visitor to the deployment. | Project members who can view variables, in plain text and change history. | Hidden in the Variables tab after saving; you can only replace it. |
| Key rule | Must start with VITE_. | Any valid name. | Any valid name. |
| Choose it when | The browser needs a public value that differs between deployments. | The value is configuration, not a credential. | Anyone who reads the value could act as your project. |
| Examples | VITE_API_URL, a feature flag. | LOG_LEVEL, DEFAULT_REGION, a public upstream URL, a timeout. | A third-party API key, a database password, a webhook signing secret, an OAuth client secret. |
Where you set the type depends on the scope:
- Full deployment: The deployment's Variables tab offers Frontend, Backend, and Backend secret as the Type.
- Project variables: The project's Variables tab offers Backend or Frontend as the Service. Check Secret (hidden after saving) to make a backend value a secret.
- Lite deployment: Overrides take no type. Keys starting with
VITE_go to the frontend and the rest to the backend.
Commit constants that are the same everywhere, like a support email address, to the code instead of a variable.
Frontend values are public
Frontend values are compiled into the JavaScript that every visitor downloads. Anyone who can load the site can read them with browser developer tools. Crucible requires the VITE_ prefix and does not offer a secret option for frontend variables. A credential cannot be marked for the browser by accident.
If the browser needs data that depends on a credential, keep the credential in a Backend secret and add a backend route that calls the upstream service. For model access, use the LLM Gateway instead of storing provider keys at all.
Changing a Frontend value rebuilds the frontend, because the value is fixed at build time. A running page keeps the old value until the visitor reloads.
When a backend value should be a secret
Use Backend for values you would be comfortable pasting into a pull request, and Backend secret for everything else. Both reach backend code the same way, as an ordinary environment variable. The choice never changes how your code reads the value.
- Backend values stay readable in the Variables tab, in deployment change history, and in the cloud provider's service configuration. That visibility makes debugging configuration easy.
- Backend secret values show as Stored securely and never appear again: not in the Variables tab, and not in change history, which records only the secret reference. The deployment's backend runtimes still read the value. To change one, enter a new value.
- Work locally gives each member the resolved values for their own machine, including secrets they are allowed to read. Keep local
.envfiles out of version control.
- Frontend: Written to the frontend build configuration and baked into the compiled bundle. The backend rejects frontend keys without the
VITE_prefix and rejects secret protection on non-backend services. - Backend: For full deployments, written to the deployment's Terraform variables (
terraform.auto.tfvars) and set as a plain environment variable on the backend workloads. Lite deployments and workspaces receive the resolved value as a backend environment variable in their managed runtime. - Backend secret: For full deployments, stored in the provider's secret store (GCP Secret Manager, AWS Secrets Manager, or Azure Key Vault). A Kubernetes Secret synced from that store is injected as environment variables into the API deployment, the Temporal worker deployment (created only when agents are enabled), and each CD task step. Crucible's own records keep only the secret reference. Each saved value becomes a new secret version. Lite deployments and workspaces receive the resolved value as a backend environment variable in their managed runtime.
Never give secret values to an agent
Do not paste a secret value into a chat, a prompt, a workspace agent, or any other model context. Text sent to a model can persist in transcripts, logs, and generated code, which undoes everything a Backend secret protects. Store the value as a Backend secret and refer to it only by its key, for example by asking the agent to read STRIPE_API_KEY from the environment.