Environment Variables

Environment variables are the primary way to configure your Sprintsail apps. They are injected into every container instance at runtime.

Setting variables

Set one or more variables:

ss env set my-app NODE_ENV=production LOG_LEVEL=info

This triggers a rolling restart of your app with the new values.

Viewing variables

ss env list my-app

NAME              VALUE               SOURCE
NODE_ENV          production          user
LOG_LEVEL         info                user
DATABASE_URL      postgres://...      service:my-postgres
REDIS_URL         redis://...         service:my-redis
PORT              8080                platform

The SOURCE column shows where each variable comes from:

Source	Description
user	Set by you via ss env set
service:*	Injected by a service binding
platform	Set by Sprintsail (e.g., PORT)

Removing variables

ss env unset my-app LOG_LEVEL

Remove multiple variables:

ss env unset my-app LOG_LEVEL SOME_OTHER_VAR

Platform variables

Sprintsail automatically injects these variables into every app:

Variable	Description
PORT	The port your app must listen on (always 8080)
SS_APP_NAME	The app name
SS_ORG	The organization name
SS_REVISION	The current deployment revision number
SS_REGION	The cloud region

Your app must bind to the PORT variable. Sprintsail routes traffic to this port.

Service binding credentials

When you bind a service, its credentials are automatically injected as environment variables. These are read-only and managed by the platform.

ss services bind my-postgres my-app
# Injects DATABASE_URL, PGHOST, PGPORT, PGUSER, PGPASSWORD, PGDATABASE

If a service binding variable conflicts with a user-set variable, the user-set value takes precedence. This lets you override connection strings for testing:

ss env set my-app DATABASE_URL=postgres://localhost:5432/test

To restore the service-provided value, unset the override:

ss env unset my-app DATABASE_URL

Secrets

All environment variables are stored encrypted at rest and transmitted over TLS. For sensitive values, the workflow is the same as regular variables:

ss env set my-app STRIPE_SECRET_KEY=sk_live_abc123

When listing variables, sensitive values are masked by default:

ss env list my-app

STRIPE_SECRET_KEY    sk_live_***       user

To reveal values:

ss env list my-app --show-values

Marking variables as sensitive

Explicitly mark a variable as sensitive to ensure it is always masked in logs and CLI output:

ss env set my-app API_TOKEN=xyz --sensitive

Sensitive variables are:

• Masked in ss env list output
• Excluded from build logs
• Never exposed in the web console without explicit reveal
• Redacted from error reports

Build-time variables

Some variables are needed only during the build phase (e.g., private registry tokens). Set them with the --build flag:

ss env set my-app NPM_TOKEN=abc123 --build

Build-time variables are available during ss push builds but are not injected into the running application.

Using an env file

Load variables from a .env file:

ss env import my-app .env

File format:

# Comments are ignored
NODE_ENV=production
DATABASE_POOL_SIZE=10
API_KEY=secret-value

Export current variables to a file:

ss env export my-app > .env.production

Variable precedence

When the same variable is defined in multiple places, this order applies (highest wins):

1. ss env set (user-set variables)
2. Service binding credentials
3. Platform variables
4. ss.yaml env block

Next steps

• Services --- bind managed services for automatic credential injection
• Deploying --- build-time vs runtime variables
• CI/CD --- setting secrets in automated pipelines