Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/nayalsaurav/deploy-your-app/llms.txt

Use this file to discover all available pages before exploring further.

Environment variables on Deploy Your App are encrypted at rest using AES-256-GCM before being written to PostgreSQL. The encryption is keyed by MASTER_ENCRYPTION_KEY — a server-side secret that must be at least 32 characters long. At deploy time, the builder retrieves each variable from the database, decrypts it, and writes all variables to a .env file that is placed inside the Docker build context before the image is built. This means your variables are available both during the docker build step (for build-time args) and at container runtime.
Changing or adding environment variables does not automatically restart or redeploy your application. The updated values are only applied the next time a deployment runs. After saving changes to your variables, trigger a manual redeploy from the project dashboard (or push a commit to your production branch) to apply them.

​
Managing variables via the dashboard

Open your project in the dashboard and scroll to the Environment Variables card. The Env Manager UI lets you:
  • Add a variable — type the key (automatically uppercased) and value into the form fields, then click Add Variable. The value field is masked by default.
  • Delete a variable — hover over an existing variable row to reveal the delete button, then confirm the prompt.
Variable values are never returned in plaintext from the API. The dashboard shows •••••••••••••••• for all stored values because the encrypted ciphertext is stored in the database and the decrypted value is only ever passed to the build worker — never to the browser.

​
Managing variables via the API

​
Add or update a variable

Send a POST request to /api/v1/projects/:id/envs. The endpoint upserts by key: if a variable with the same key already exists for the project it is updated; otherwise a new record is created. 
curl -X POST https://your-domain.com/api/v1/projects/PROJECT_ID/envs \
  -H 'Content-Type: application/json' \
  -b 'better-auth.session_token=YOUR_SESSION_TOKEN' \
  -d '{"key": "DATABASE_URL", "value": "postgres://user:pass@host:5432/db"}'
Request body
FieldTypeRequiredDescription
keystring✅ YesVariable name, e.g. DATABASE_URL
valuestring✅ YesPlaintext value — encrypted before storage
Response 
{ "message": "Environment variable saved" }

​
Delete a variable

Send a DELETE request to /api/v1/projects/:id/envs with the envId query parameter. You can find the envId from the project detail API response. 
curl -X DELETE \
  "https://your-domain.com/api/v1/projects/PROJECT_ID/envs?envId=ENV_RECORD_ID" \
  -b 'better-auth.session_token=YOUR_SESSION_TOKEN'
Response 
{ "message": "Environment variable deleted" }

​
How encryption works

Variable values are encrypted using AES-256-GCM via Node.js’s built-in node:crypto module (see packages/database/src/crypto.ts). The process works as follows:
  1. A random 12-byte IV is generated for every encryption call.
  2. The value is encrypted using the first 32 bytes of MASTER_ENCRYPTION_KEY as the cipher key.
  3. The GCM authentication tag (16 bytes) is computed to guarantee integrity.
  4. The result is stored as a colon-delimited string in the format iv:authTag:ciphertext (all hex-encoded).
On deployment, the worker calls decrypt(value, MASTER_ENCRYPTION_KEY) for each variable, verifies the auth tag, and writes the plaintext value into the .env file.
MASTER_ENCRYPTION_KEY must be set in your server environment. If it is missing or shorter than 32 characters, any attempt to save an environment variable will return 500 Server configuration error and the variable will not be stored.

​
Security considerations

  • Encrypted ciphertext is never decrypted in the browser. The project API returns Env records with the encrypted value field; the plaintext is only ever reconstructed inside the build worker, never in a browser response.
  • Rotate MASTER_ENCRYPTION_KEY carefully. If you change the key, any previously encrypted variables cannot be decrypted. Re-enter all variable values after a key rotation.
  • .env file scope. The .env file is written into the Docker build context only — it is not committed to your repository and is not included in the final image layer pushed to Cloudflare R2.

​
Adding variables during project import

You can supply environment variables at import time as part of the POST /api/v1/projects/import request body. Variables are encrypted and stored before the first build job is enqueued, so they are available immediately in the initial deployment. 
{
  "repositoryFullName": "owner/repo",
  "name": "my-app",
  "defaultBranch": "main",
  "envs": [
    { "key": "API_SECRET", "value": "super-secret-value" },
    { "key": "NODE_ENV", "value": "production" }
  ]
}
See Import a Project for the full import workflow.

Build docs developers (and LLMs) love

Get started for freeTalk to us