Environment Variables

Environment variables in Build are managed at three levels: project defaults (in build.json), sandbox secrets (encrypted), and runtime overrides (per-session).

Project Defaults

Define default environment variables in the build.json file. These are included in every sandbox and preview:

build.json
json
{
  "env": {
    "NODE_ENV": "development",
    "API_URL": "https://api.example.com",
    "FEATURE_X": "true"
  }
}

Secrets

Sensitive values (API keys, database credentials) should be stored as secrets rather than in build.json. Secrets are encrypted at rest and never exposed in logs or previews:

Build UI
bash
# In the Build UI, navigate to:
Project Settings > Environment > Secrets


# Add a secret:
Name:  DATABASE_URL
Value: postgresql://user:pass@host:5432/db


# Secrets are injected as environment variables at runtime
# but never shown in plaintext after saving
!Warning
Never put secrets in build.json. The file is visible in the sandbox filesystem and may appear in agent logs. Use the Secrets UI for all sensitive values.

Preview Environment Variables

Each preview deployment can override environment variables. This is useful for feature branches that connect to different backends:

build.json
json
{
  "preview": {
    "env": {
      "API_URL": "https://staging-api.example.com"
    }
  }
}

Variable Precedence

When the same variable is defined at multiple levels, the highest priority wins:

  1. Runtime overrides (set via agent or shell in the current session)
  2. Preview environment variables
  3. Secrets
  4. Project defaults in build.json
PreviousAgentsNextDeployment