Build & Deploy
Environment Variables

Environment Variables

Environment variables (opens in a new tab) are a common method of passing configuration data to applications at runtime. You can define environment variables on Koyeb to pass important information to your Services. These variables are exposed during the build process and at runtime.

Each environment variable has the following components:

  • Name: The name of the environment variable.
  • Type: Either "Plaintext" or "Secret". Secrets are associated with a Koyeb organization and can either be created ahead of time or when setting up a new environment variable.
  • Value: The value that will be given when the variable is accessed. If using the "Secret" type, this instead specifies the name of the Secret to use. The Secret's value will be automatically decrypted and accessible to the Service under then variable name provided.

Koyeb Web Services always have a PORT variable defined. If the PORT environment variable is not set explicitly, it will be automatically set to the lowest exposed port number. You can set the PORT variable manually in the environment variable configuration if you wish to point it to a different port.

Managing environment variables

You can define and modify environment variables using either the Koyeb control panel (opens in a new tab) or the Koyeb CLI.

When using the Koyeb control panel, you can manage environment variables for your Service on the Service configuration screen. This screen is accessible both during your initial Service configuration and later in your Service's Settings tab.

From the Settings tab, expand the Environment variables section. From here, you can manage variables in two ways:

Manage individual variables

You can manage individual variables with the provided buttons.

To add a new variable, click Add Variable. Choose a name for the variable, the type (either plaintext or Secret), and then set the value.

To modify an existing variable, edit the variable's name, type, or value.

To delete a variable, click the trash icon associated with the environment variable line.

Perform bulk editing

To edit environment variables in bulk, click Bulk Edit.

This will open up a free-form text box pre-populated with the form's current environment variable configuration. Each variable is defined on its own line using the following format:


To set a value that spans multiple lines, wrap the value in single quotes, double quotes, or backticks:

Comment: ABAF 11C6 5A29 70B1 30AB  E3C4 79BE 3E43 0041 1886


To set an environment variable to a Koyeb Secret, prefix the Secret name with the at-symbol (@) as the environment variable value:


For example, to set a variable called DB_PASSWORD to a Secret called POSTGRESQL_PASS, add the following line:


Click the Save button when you are finished with the bulk edit operation. The environment variable fields on the configuration page will immediately update to reflect the new variable definitions. After completing your changes, click the Deploy button to create a new Deployment with the provided environment variables.

Environment variable interpolation

Variable interpolation, also known as variable substitution or expansion, is the process of replacing a reference to a variable with its defined value. Koyeb supports environment variable interpolation, meaning that you can refer to other environment variables when defining a variable value. Koyeb will replace all environment variable references with their respective values during processing.

To reference the value of an environment variable, use the following syntax:

{{ <ENV_NAME> }}

For example, the following definition defines two variables. The second variable refers to the value of the first:


This definition will result in the following variable values:


Note: References to undefined variables will be replaced by a blank string during processing.

In the example below, the STORAGE_ENDPOINT definition accidentally refers to the STORAGEREGION variable (which does not exist) instead of the STORAGE_REGION variable:

# The definition below does not reference the correct variable name

This will result in the following, unintended, variable values:


Updating an environment variable at runtime will not change the values of variables that reference it. Koyeb only processes environment variables for interpolation during the build and deployment stages.

You can also refer to Koyeb-provided variables, such as KOYEB_PUBLIC_DOMAIN, when defining a variable value. This strategy allows you to refer to values (like the App's public domain) that are only known at the time of deployment.

For example, our Django deployment guide uses the DJANGO_ALLOWED_HOSTS environment variable to pass in the domain name where the application is hosted. You can automatically populate the correct value by defining it in terms of the KOYEB_PUBLIC_DOMAIN variable:


With this, the DJANGO_ALLOWED_HOSTS variable will automatically be set to the public domain of your App.

Koyeb-provided variables

Koyeb automatically exposes information about your Service's deployment environment and configuration as environment variables.

The following Koyeb environment variables are exposed to your Services automatically both during the build and at runtime:

KOYEB_APP_NAMEDescription: Koyeb Application name.
Example: app
KOYEB_APP_IDDescription: Koyeb Application ID.
Example: 647813c7-09b8-44ce-a02a-0cc70092bf4c
KOYEB_ORGANIZATION_NAMEDescription: Koyeb Organization name.
Example: my-organization
KOYEB_ORGANIZATION_IDDescription: Koyeb Organization ID.
Example: 6704aff2-36ec-4e13-ba1e-0438eaf7a65e
KOYEB_SERVICE_NAMEDescription: Koyeb Service name.
Example: my-service
KOYEB_SERVICE_IDDescription: Koyeb Service ID.
Example: 41dcf9cb-53a4-4b02-960c-f421254a1678
KOYEB_SERVICE_PRIVATE_DOMAINDescription: Default Service URL for service discovery.
Example: <SERVICE_NAME>.<APP_NAME>.koyeb
KOYEB_PUBLIC_DOMAINDescription: Default public Service URL. Only routable for web Services.
KOYEB_PORT_<PORT>_PROTOCOLDescription: The protocol of the exposed port <PORT>. Can be tcp, http, or http2.
Example: http
KOYEB_PRIVILEGEDDescription: Whether the container is running in privileged mode (opens in a new tab). Can be true or false.
Example: true
KOYEB_DOCKER_REFDescription: The Docker container's image reference (opens in a new tab) as specified by the user in the CLI or the control panel.
Example: koyeb/demo:latest
Availability: Only for Docker deployments
KOYEB_GIT_SHADescription: The SHA (opens in a new tab) of deployed Git commit.
Example: ac18568cd565650e96216c8d092a6c60f9ed09b
Availability: Only for GitHub deployments
KOYEB_GIT_BRANCHDescription: Git branch name of the currently deployed Service.
Example: main
Availability: Only for GitHub deployments
KOYEB_GIT_REPOSITORYDescription: Git repository URL of the deployed Service.
Availability: Only for GitHub deployments
KOYEB_GIT_COMMIT_MESSAGEDescription: Commit message of the deployed Git commit.
Example: Fix README heading
Availability: Only for GitHub deployments
KOYEB_GIT_COMMIT_AUTHORDescription: Commit author of the deployed Git commit.
Example: Cindy Davis
Availability: Only for GitHub deployments

The following environment variables are exposed to your Service at runtime only (after the build):

KOYEB_REGIONDescription: Region where the service is deployed.
Example: fra
KOYEB_REGIONAL_DEPLOYMENT_IDDescription: Regional Deployment ID of the Service, which may be helpful for support.
Example: 3a1bb3d0-7502-40a5-ae12-7e28f807531b
KOYEB_INSTANCE_IDDescription: Koyeb Instance ID.
Example: e5f296b6-a911-8637-234e-f929e8bd5d87
KOYEB_INSTANCE_TYPEDescription: Type of Instance running the Service.
Example: nano
KOYEB_INSTANCE_MEMORY_MBDescription: The memory allocated to the Instance, in MB.
Example: 256
KOYEB_REPLICA_INDEXDescription: The 0-based index number of the replica. This may be useful, for example, for configuring leader elections.
Example: 0
KOYEB_HYPERVISOR_IDDescription: The ID of the hypervisor the Service is running on, which may be helpful for support.
Example: fra1-rn23u23
KOYEB_DCDescription: The data center the Service is deployed to (within a region), which may be helpful for support.
Example: fra1

Your Services can read the values of these environment variables to get contextual information about their deployment and runtime environment.

Using environment variables in your applications

An environment variable's value can be accessed within your application using your language's environment variable functionality.

For example, if you set an environment variable called DATABASE_URL, you could access it like this: