Environment variables

Environment variables pass values that should not live in your code (API keys, database URLs, and so on) to your app. Nitroship stores them per app under two targets, production and preview. Production deployments get the production values; preview deployments get the preview values.

Run the commands below in a folder linked to your app, or add --app <app-name>.

Add and listCopy Anchor Link

ntro env add API_KEY production                    # secret value (default)
ntro env add API_ENDPOINT preview --no-sensitive   # plain value
ntro env ls

• env add asks for the value in the terminal, so it never appears on the command line.
• Values are secret by default. Once saved they are masked in listings and cannot be read back. Add --no-sensitive for values that do not need hiding.
• Adding a name that already exists for that target is an error. Add --force to overwrite.
• Where the CLI cannot ask questions, such as CI, you must name the target (production or preview).

In the dashboardCopy Anchor Link

• When adding or editing a variable, or entering deployment variables, secret values are visible only while their input is focused and are masked again when focus leaves.
• The environment table always shows plain values as text and secret values as bullets. Click an available value, or focus its cell and press Enter or Space, to copy it. Saved secrets are redacted and cannot be read or copied.

Platform variables and templatesCopy Anchor Link

At runtime, Nitroship injects NITROSHIP=1, NITROSHIP_* metadata (target, region, IDs, URLs, Git and build information), and PORT. Unknown optional metadata is an empty string. Platform values take precedence over user and image values; PORT is not reserved, but the platform value still wins. HOSTNAME is deliberately not set because managed Next.js uses it as the server bind address. Use NITROSHIP_HOST or NITROSHIP_URL for your app's address.

Plain values (--no-sensitive) support ${NAME} references:

printf '%s\n' '${NITROSHIP_URL}/api/auth/callback' | ntro env add AUTH_CALLBACK_URL production --no-sensitive

The single quotes keep your shell from expanding the template before saving it.

• References resolve recursively using platform variables and user variables in the same target only. Variables defined only in the OCI image (such as PATH) cannot be referenced.
• Secret values are always literal, not templates, but plain values can reference secrets by name. Keep resolved values containing secrets out of logs and client responses.
• $${ escapes a literal ${; $NAME without braces is unchanged. Default/fallback expressions such as ${NAME:-fallback} are not supported.
• The API and console display the original plain template, not its resolved value. Saved secrets remain hidden.
• Reserved keys are exactly NITROSHIP, NITROSHIP_ENV, NITROSHIP_REGION, NITROSHIP_INSTANCE_ID, NITROSHIP_DEPLOYMENT_ID, NITROSHIP_APP_ID, NITROSHIP_APP_SLUG, NITROSHIP_TEAM_SLUG, NITROSHIP_HOST, NITROSHIP_URL, NITROSHIP_PRODUCTION_HOST, NITROSHIP_PRODUCTION_URL, NITROSHIP_BRANCH_HOST, NITROSHIP_BRANCH_URL, NITROSHIP_GIT_COMMIT_SHA, NITROSHIP_GIT_BRANCH, NITROSHIP_GIT_REPO, NITROSHIP_BUILD_ID, and every name starting with NITROSHIP_ISR_ or NITROSHIP_PURGE_. Other NITROSHIP_* user keys are allowed but discouraged: future platform variables with the same names may take precedence over your values.
• Saving rejects reserved keys, malformed syntax, unknown references and cycles. Deleting a variable still referenced by another same-target plain variable is also rejected.

Hosted builds receive only a subset of platform metadata. A plain variable that directly or recursively references runtime-only metadata (such as NITROSHIP_URL) or PORT is omitted from the build environment with a build-log warning; this does not fail the build. It resolves normally at runtime.

See the canonical environment variable reference for the exact runtime/build variable table and detailed rules.

Use them on your machineCopy Anchor Link

ntro env pull                          # save preview values to .env.local
ntro env pull .env.prod --environment production
ntro env run -- npm run dev            # run a command with preview values set

• pull writes only the plain preview values to .env.local by default. If the file exists, add --yes to overwrite it.
• run writes no file; it runs the command after -- with the values set.
• Secret values cannot be retrieved with either pull or run. Manage them separately if you need them locally.

RemoveCopy Anchor Link

ntro env rm API_KEY production

Leave out the target to remove it from both targets. It asks for confirmation first.

API referenceCopy Anchor Link

PUT /v1/apps/{appId}/env in the REST API replaces the whole list. Variables you leave out are deleted, so send every entry you want to keep.