Environment Variables

Environment variables are encrypted key/value pairs attached to a project. They're injected into preview containers and (for service-managed credentials) agent task containers, letting your code read secrets (API keys, database URLs, etc.) without hardcoding them.

Setting Variables#

From Project Settings > Environment:

  1. Enter a key (e.g., STRIPE_SECRET_KEY, OPENAI_API_KEY)
  2. Enter a value
  3. Click Add — the value is encrypted with AES-256-GCM encryption and stored in the database

Permission required: project:settings

Key naming rules#

  • Keys must be uppercase letters, digits, and underscores, and must start with a letter (pattern: ^[A-Z][A-Z0-9_]*$).
  • The following keys and prefixes are reserved and cannot be set manually:
    • Reserved prefixes: REDSTICK_, RS_
    • Reserved keys: INSTALL_COMMAND, NEXT_TURBOPACK_ROOT, PGHOST, PGPORT, PGUSER, PGPASSWORD, PGDATABASE, DATABASE_URL
  • Reserved keys are either managed by the platform or by an attached service. Trying to set a reserved key returns an error.

Viewing Variables#

By default, values are masked — displayed as **** followed by the last 4 characters (or simply **** for very short values). To reveal all values, click Reveal values. Revealing requires the project:settings permission — only project owners and admins can reveal plaintext values; members receive a 403.

Service-Managed Variables#

When you attach a project service (e.g., a Postgres database), the service auto-provisions one or more environment variables (e.g., DATABASE_URL) so your agents and previews can connect without manual wiring. Those rows are platform-managed:

  • They're marked with a lock icon next to the key.
  • The delete button is disabled for these rows.
  • To remove a service-managed variable, detach the service from the project — the variable is cleaned up automatically.

You can still add your own variables alongside service-managed ones; only the platform-managed rows are locked.

Using Variables#

Environment variables are automatically available in:

  • Preview containers — your application can read them like any environment variable. Both user-defined variables and service-managed credentials (e.g., DATABASE_URL) are injected.
  • Agent task containers — service-managed credentials (variables provisioned by an attached service) are available to agents. User-defined variables are not currently injected into agent task containers; agents access them indirectly through the preview container or by reading the values from the environment section of Project Settings.

Encryption#

All values are encrypted at rest using AES-256-GCM symmetric encryption (256-bit keys with 96-bit random nonces). The encryption key is configured server-side — it is never stored in the database.

Troubleshooting#

"Key must match …" validation error The key must be all-uppercase, start with a letter, and contain only letters, digits, and underscores. Spaces, hyphens, and lowercase letters are not allowed.

"'KEY' is a reserved key and cannot be set" error Some keys are reserved by the platform or by attached services (e.g., DATABASE_URL, PGHOST). Choose a different key name, or attach the relevant project service to let the platform provision that variable automatically.

Variable not visible in my preview application Restart (or re-launch) the preview container — environment variables are injected at container start and are not hot-reloaded into a running container.

Variable not visible in the agent's environment User-defined variables are currently injected into preview containers only. If your agent needs a secret, have it read the value through the preview environment, or attach a project service whose credentials are automatically made available to both agents and previews.