Guides

Environment variables

Configuration and secrets live per app, per environment. Values are write-mostly: you can set them freely, but reading one back is a deliberate, audited act.

Setting variables

From the console, open an app and go to the Variables tab. From the CLI:

bash

# Set one or several at once$ codaracloud env set my-api DATABASE_POOL_SIZE=20 LOG_LEVEL=info # Import a .env file$ codaracloud env set my-api --from-file .env.production # List (values are masked)$ codaracloud env list my-api # Remove$ codaracloud env unset my-api LOG_LEVEL

Apply related changes together

Both the console and CLI batch staged changes into one apply operation, so related edits cause one rollout instead of several consecutive restarts.

Listing variables never returns plaintext — every value comes back masked. Revealing a value is a separate, explicitly permissioned action that writes an audit record naming who read which key and when.

bash

# Reveal a single value (audit-logged)$ codaracloud env get my-api DATABASE_URL # Dump everything in .env format (reveals every value, all audit-logged)$ codaracloud env export my-api > .env.production

An API token needs the env:reveal scope to do either. env:read alone lists keys with masked values.

When changes take effect

Changing a variable restarts the app. For apps without a persistent volume, Kubernetes rolls replicas gradually; the process must still handle termination signals and finish or hand off in-flight work within its shutdown grace period. Batch related changes together rather than applying them one at a time.

Rules and limits

Rule	Detail
Key format	A valid shell identifier — letters, digits and underscores, not starting with a digit.
Value size	Up to 65,536 characters.
Scope	Per app, per environment. Staging and production never share values.
Reserved keys	`PORT` and anything starting with `CODARA_` are managed by the platform and cannot be set.

PORT is set for you

Codara injects PORT based on the port configured on the app. Attempting to set it yourself is rejected. Read it from the environment in your code and you will work everywhere without changes.

Variables Codara provides

Every container receives a handful of read-only variables describing where it is running. They are visible in the console under Provided by Codara.

Variable	Contains
PORT	The port your app should listen on.
CODARA_PRIVATE_URL	This app’s internal URL, for other apps in the same environment.
CODARA_PRIVATE_DOMAIN	The internal hostname on its own.
CODARA_*	Additional identifiers for the workspace, project and environment the container belongs to.

Shared variables

When several apps in one environment need the same value, set it once as a shared variable rather than copying it into each app.

bash

# Share a value with every service in the environment$ codaracloud shared-vars set SENTRY_DSN=https://... \    --client my-workspace --project website --env production --all-services # Or attach it to specific services only$ codaracloud shared-vars set REDIS_URL=redis://... \    --client my-workspace --project website --env production \    --service api --service worker $ codaracloud shared-vars list --client my-workspace --project website --env production

An app’s own variables take precedence, so a local value always overrides a shared one of the same name. That makes shared variables safe as defaults.

If a shared-variable update reports a partial failure

Shared variables are projected into every attached service. When some services update and others do not, the command tells you so. Re-run the projection with codaracloud shared-vars reconcile --client … --project … --env ….

Connecting a database

You do not set database credentials by hand. Connecting a database to an app injects its connection variables automatically and keeps them current — see Databases.

bash

$ codaracloud apps connections add my-api main-db --client my-workspace

Copying between environments

The console can copy variables from another environment when you are setting up a new one. Database-managed and platform-managed keys are excluded from the copy, since those are provisioned per environment and must not be shared.

Build time versus runtime

Environment variables are runtime only. They are not available while your image is being built. If your build needs a public value, such as an API URL compiled into a frontend bundle, commit it to a file your framework reads at build time (a Next.js app uses .env.production), or build with your own Dockerfile and pass it as a build argument. Build arguments reach only a Dockerfile you wrote, not Railpack, Nixpacks or static builds. Never put a secret in either. See Building and deploying.

Good practice

Read PORT from the environment rather than hardcoding a port.
Keep an .env.example in your repository — the deploy wizard offers its keys when you create the app.
Rotate a leaked secret at its source, then update it here. Revealing a value is audited, but so is everything else — treat the audit trail as a record, not a control.
Use shared variables for anything more than one app in the environment needs.

Last updated 26 September 2026