Environment Variables
Zerops manages environment variables at two scopes: service level and project level. These variables are handled automatically without requiring .env files.
On this page: Service Variables · Project Variables · Referencing Variables · Variable Isolation · Restrictions · Examples
Service Variables
Variables that are specific to individual services.
User-Defined Variables
You can define service-level variables in two ways:
1. Build & Runtime Variables
These variables are defined with envVariables attribute in the build or run section of your zerops.yaml file and are accessible within their respective containers.
See how to reference variables between services and between build and runtime environments. All variables must follow the naming restrictions.
Your application must be redeployed when updating environmental variables in zerops.yaml.
2. Custom and Secret Variables
Variables stored in Zerops, not in your source repository. They can be updated without redeployment, but the service has to be restarted to pick up the new values.
Each of these variables is either plain or sensitive:
- Custom variables are plain.
- Secret variables are sensitive. Their values are encrypted at rest with a per-project key and masked in the GUI and API responses. Inside the containers they are plain text, so your application reads them like any other variable.
You can create both kinds in the GUI, in import.yaml or through the API. In API requests, the sensitive flag decides which kind a variable is and defaults to false. See Reading sensitive values for who can see a secret value.
GUI Interface
Navigate to service details and find Environment variables in the menu. The page has four sections:
- Custom variables: plain variables you set in the GUI
- Secret variables: sensitive variables, stored encrypted
- Variables from zerops.yml: the build and runtime variables deployed with your application
- Generated variables: variables set by the system
In the Custom variables and Secret variables sections you can:
- Add individual variables
- Edit individual variables through the menu that appears on hover
- Use the section's bulk editor to change multiple variables at once in .env format (see Editing several variables at once)
Secret values are masked. Revealing a value asks you to re-authorize, and so does loading secret variables into the bulk editor.

Import Configuration
Create custom and secret variables for a service with the vault attribute. Each entry is either a plain KEY: value pair, or an object with value and sensitive: true for a secret variable. See the complete import.yaml structure.
To paste variables in .env format, use dotEnvVariables for plain variables and dotEnvSecrets for secret variables. The envVariables and envSecrets attributes are deprecated but still accepted.
API
The endpoints that create or update a single variable accept a sensitive flag, which defaults to false, and their responses include sensitive, editable and internal. When you create a service or trigger its pipeline, pass plain variables in envVarsFile and secret variables in envSecretsFile, both as .env text. The userDataEnvFile field is deprecated. To change several variables at once, see Editing several variables at once.
System-Generated Variables
Zerops automatically generates variables based on service type.
These variables cannot be deleted and are listed in the Generated variables section of the environment variables page. Some are read-only (like hostname), while others can be edited (like PATH). Some are sensitive, such as a generated database password, and a sensitive system variable can't be changed to plain.
These variables can also be referenced.
Project Variables
Variables that apply across the runtime services within a project. These provide a way to share common configuration across services.
Like custom and secret service variables, each project variable is either plain or sensitive, and sensitive values are encrypted and masked the same way. Project variables can be updated without redeployment, but services have to be restarted to pick up the new values.
Project variables are automatically inherited by all runtime services in the project — both in build and runtime environments. You do not need to reference them in your zerops.yaml.
Managed services don't receive project variables. A managed service's own variables, references to other services' variables and isolation work as usual.
User-Defined Variables
You can set project-wide variables through:
GUI Interface
Access Project environment variables in your project detail to:
- Add individual variables one by one
- Edit individual variables
- Use the bulk editor to change multiple variables at once in .env format (see Editing several variables at once)
Import Configuration
Create project variables with the vault attribute. Each entry is either a plain KEY: value pair, or an object with value and sensitive: true for a sensitive variable. See the complete import.yaml structure.
These variables are automatically available in all runtime services without any additional configuration. The envVariables and envSecrets attributes are deprecated but still accepted.
Through the API, project creation accepts envVariables (plain) and envSecrets (sensitive), each an array of {key, content} objects. Single project variables are created and updated with a sensitive flag that defaults to false.
System-Generated Variables
Zerops automatically generates project-level variables that are also automatically available in all runtime services.
Overriding Project Variables
If you need a different value for a specific service, you can override a project variable by defining a service-level variable with the same key. See Variable Precedence for details on how conflicts are resolved.
Environment Variable Isolation
A security feature that controls the visibility of environment variables across services within a project. This affects how referencing variables across services works.
By default, Zerops isolates environment variables between services to enhance security and prevent unintended access to sensitive information. This isolation can be configured at both project and service levels.
Isolation Rules
The envIsolation value is a space-separated list of rules. A service's own rules decide which other services can see its variables. The rules of the service doing the reading are never consulted, so a service can widen or narrow what it exposes, but never what it receives.
| Rule | Description |
|---|---|
service | Default. Only the service itself sees its variables. Other services must reference them explicitly. |
none | Every service in the project sees the variables, prefixed with the service hostname. |
service@name | The service with hostname name additionally sees the variables. |
-service@name | The service with hostname name never sees the variables, even when none is present. |
Rule Evaluation Order
When service reader asks for the variables of service owner, the rules of owner are checked in this order:
-service@readeris present → hiddenservice@readeris present → visiblenoneis present → visible- Otherwise → hidden
Block rules always win over allow rules for the same service. A service always sees its own variables regardless of its rules, and explicit ${hostname_variable} references keep working in every mode.
Configuring Isolation
Project-Level Isolation
Zerops automatically creates the envIsolation project variable with the default value service. Every service inherits the project value unless it sets its own:
This can also be set through the Project Environment Variables section in the GUI.
Service-Level Override
Individual services can replace the project-level value with their own. The values are not merged, the service value applies on its own:
You might set a database service to envIsolation: none to expose its connection details to other services, without having to manually reference them, while keeping the rest of your services isolated.
In import YAML, envIsolation can also be nested under envVariables/envSecrets. (If both are present, the nested version takes precedence).
Common Combinations
Single privileged reader (tooling, migrations, admin service):
- ✅ The
zcpservice sees the variables of every service that inherits this value - ❌ Every other service stays isolated
Open project with one exception:
- ✅ All services see each other's variables
- ❌ The
untrustedservice sees only its own variables and project variables
Selective exposure on one service:
- ✅ The
apiandworkerservices see thedbvariables - ❌ Every other service must reference
dbvariables explicitly
Accessing Variables Across Services
With Isolation Enabled (service mode)
When isolation is enabled, you must explicitly create reference variables to access variables from other services:
This approach gives you complete control over which variables are shared between services.
When Variables Are Shared (none or service@name)
When the owning service shares its variables, they are automatically available with the service name prefix:
Best Practices for Variable Isolation
- Use Default Isolation: Keep the default
serviceisolation for enhanced security. - Explicit References: Create explicit references only for variables that need to be shared.
- Naming Conventions: Use clear naming patterns for reference variables (e.g.
DB_PASSWORDfor a reference todb_password). - Grant, Don't Open: Prefer
service@namefor the one service that needs broad access overnone, which exposes variables to every service. - Service-Level Exceptions: Use service-level isolation overrides sparingly and only for services that need to expose their variables widely.
Referencing Variables
You can reference other variables using the ${variable_name} syntax. This is used to reference service-level variables, not project variables (which runtime services already inherit automatically).
Within Same Service
Across Services
How this works depends on your environment variable isolation setting:
With Isolation Enabled (service mode - default)
Create an explicit reference in the destination service:
With Isolation Disabled (none mode)
Variables from other services are automatically injected into the container and available using the service prefix format servicename_variablename:
Between Build and Runtime Environments
Build and runtime are two distinct environments in Zerops. Each environment can have its own set of variables, and you can use the same variable names in both environments since they are separate. Due to this separation, variables defined in one are not automatically accessible in the other.
To share variables between environments, you need to use specific prefixes:
- Use
RUNTIME_prefix to access runtime variables during build - Use
BUILD_prefix to access build variables during runtime
Project Variables — No Reference Needed
Project variables are automatically available in all runtime services. Do not use the ${...} syntax to reference them:
If a project variable is named LOG_LEVEL, your application can read it directly — you don't need to add anything to your zerops.yaml.
Variable Restrictions
All environment variables must follow these restrictions:
Key
- Alphanumeric characters only (use
_to separate words) - Must be unique within their scope
- Case-sensitive
Value
- ASCII characters only
- No EOL characters
Variable Management
Editing Several Variables at Once
Custom and secret service variables and project variables can all be edited as a single .env file, with one KEY=value pair per line:
In the GUI, open the bulk editor of the Custom variables or Secret variables section on the service's Environment variables page, or in Project environment variables. Paste or edit the whole list and save it once, rather than adding or editing each variable separately.
Through the API, use the env file endpoints for service variables ↗ and project variables ↗. Each has one endpoint to read the variables as a file and one to write the edited file back. One request changes the whole set, while calling the single-variable endpoints once per variable starts a separate process for every variable. See the REST API reference for authentication and the full list of endpoints.
Variables are split into two groups, sensitive and non-sensitive, and the sensitive flag picks which group a request works with. A PUT sets that group to exactly what the file contains:
- Keys in the file are created, or updated if they already exist in the group.
- Keys in the group that are missing from the file are deleted.
- If a key in the file already exists in the other group, the request fails.
Because missing keys are deleted, read the current file first, edit it, and send the whole file back. Reading sensitive values requires sudo mode. As with any change to these variables, restart the affected services to pick up the new values.
Reading Sensitive Values
The value of a sensitive variable is only returned to a request in sudo mode:
- In the GUI, you enter sudo mode by re-authorizing. The GUI asks you to when you reveal a secret value or load secret variables into the bulk editor.
- An API token is in sudo mode if it was created with
sudo: true. Creating such a token requires sudo mode. A token without sudo always getsREDACTEDin place of sensitive values.
List and detail endpoints return REDACTED for a sensitive value unless the request is in sudo mode and the user's role isn't read-only. The read-only role never gets sensitive values. To reveal a single value, use the reveal endpoint for a service variable ↗ or a project variable ↗. Both require sudo mode.
Project and service exports write sensitive variables as value: REDACTED unless you request the values with reveal=true, which also requires sudo mode.
Variable Precedence
When the same environment variable key exists in multiple places, Zerops follows these precedence rules:
- Service-level variables take precedence over project variables
- Within service-level:
- Build/runtime variables override custom and secret variables
- Build and runtime containers are separate environments
Environment Variable Examples
Variable Isolation Example
Consider a project with three services: api, db, and cache:
project:
name: my-project
services:
- hostname: api
vault:
# Creating explicit references to needed variables
DB_CONNECTION:
value: ${db_user}:${db_password}@${db_hostname}:${db_port}
sensitive: true
CACHE_URL: ${cache_hostname}:${cache_port}
- hostname: db
vault:
password:
value: secureDbPassword
sensitive: true
user: dbuser
port: 5432
- hostname: cache
vault:
password:
value: cacheServerPass
sensitive: true
port: 6379
With this setup:
- The
apiservice can only access the specificdbandcachevariables it explicitly references - The
dbservice cannot see any variables fromapiorcache - The
cacheservice cannot see any variables fromapiordb
If we changed the project's envIsolation to none, all services would be able to see all variables from all other services (prefixed with the service name). With service@api instead, only the api service would see the db and cache variables, and db and cache would stay isolated from each other.
Need help? Join our Discord community.