Environment variables

Add a variable

Open the Serverless App Service's Settings → Environment Variables and select Add environment variable (needs env:write). Enter:

• Key: letters, numbers and underscores, not starting with a number, up to 256 characters. Pasting KEY=value into the key field fills both fields.
• Value: up to 64 KB.
• Environments: Production, Preview, Development, or any combination.
• Sensitive: on by default.
• Readable by developers: only for a sensitive variable whose only environment is Development; see development secrets.

Variables apply to deployments created after you save. Running deployments keep the values they started with; redeploy to pick up a change.

Keys are case-sensitive: API_URL and api_url are two variables.

Import a .env file

Import takes pasted .env text and saves every variable in it at once, with the same environments and sensitivity:

• One KEY=value per line; an export prefix is allowed. Blank lines and # comments are ignored.
• Single- or double-quoted values can span lines; double quotes understand \n, \t, \" and \\.
• When a key appears twice, the last one wins.
• Up to 200 variables per import. Nothing is saved if any name is invalid or reserved.

Shared variables

Cloud → Settings → Environment Variables holds variables shared by every Serverless App Service in the organization, managed like Serverless App Service variables (add, edit, import, sensitive, environments). Each deployment gets the shared variables of its environment, and a Serverless App Service variable with the same key (same case) replaces the shared one for the environments it covers. The Serverless App Service's Environment Variables page lists the shared variables and which ones the Serverless App Service replaces; the organization's page shows which Serverless App Services replace each shared key. Changing a shared variable applies to each Serverless App Service's next deployment, and the next push to a Serverless App Service builds even when its code didn't change.

The same page lists every Serverless App Service with a link to its variables.

Environments

When a preview is promoted, its server function switches to the Production values; values the build inlined (such as NEXT_PUBLIC_*) keep their preview values.

Sensitive variables

A sensitive variable is a secret: its value isn't shown in lists, in Cloud or by the API (it's returned as null). Reading it back is its own action, allowed by the secret's access rule (owners and admins, plus the roles and groups the rule names) and recorded in the audit log. Every new value is a version; the newest 20 are kept and an earlier one can be restored. A rotation reminder can tell owners and admins when a value is due for a change. Cloud → Secrets lists every secret in the organization.

To change a sensitive variable's environments, edit it and leave the value empty: the stored value is kept. A sensitive variable can be made visible only by entering a new value.

Values of variables that aren't sensitive can be revealed in Cloud by anyone with env:read.

Development secrets

Local development often needs secrets too: a test payment key, a staging database password. A sensitive variable whose only environment is Development can be marked Readable by developers (in Cloud, or with si env add KEY --dev-readable). People with env:write (developers and up, and team grants) then get its value from si env pull and si dev; Cloud still hides it, and viewers don't get it. Each read is recorded in the audit log as Read development secrets of with the keys.

The flag is refused for a variable that also applies to Production or Preview, and a variable that later gains another environment stops being readable, so deployed secrets never leave the platform.

Where variables are available

Build-time availability is what lets NEXT_PUBLIC_* values reach client code; anything you reference in client code is public.

Platform variables

The platform sets these on every Next.js server function:

<NAME> is the storage's name in capitals, with every character other than letters and digits replaced by _: a database named app-data becomes SI_DATABASE_APP_DATA. Linking or unlinking storage takes effect on the next deployment.

Platform variables aren't set during the build.

Reserved names

Serverless App Services can't define:

• Names starting with SI_ or CODEBUILD_
• ARTIFACTS_BUCKET, ASSETS_BUCKET, AWS_ACCESS_KEY, AWS_ACCESS_KEY_ID, AWS_DEFAULT_REGION, AWS_EXECUTION_ENV, AWS_LAMBDA_FUNCTION_MEMORY_SIZE, AWS_LAMBDA_FUNCTION_NAME, AWS_LAMBDA_FUNCTION_VERSION, AWS_LAMBDA_INITIALIZATION_TYPE, AWS_LAMBDA_LOG_GROUP_NAME, AWS_LAMBDA_LOG_STREAM_NAME, AWS_LAMBDA_RUNTIME_API, AWS_REGION, AWS_SECRET_ACCESS_KEY, AWS_SESSION_TOKEN, CACHE_BUCKET, LAMBDA_RUNTIME_DIR, LAMBDA_TASK_ROOT, _HANDLER, _X_AMZN_TRACE_ID

Encryption

Values are encrypted with a KMS key, bound to the organization and Serverless App Service (shared variables to the organization), and decrypted only when a deployment builds or starts, or when Cloud shows a value that isn't sensitive. The build receives them sealed: encrypted with a key only that build can unlock, and opened into its environment before your install and build commands run, so they don't appear in the build's record.