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 Advanced section to access the environment variable configuration. 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:

<ENV_NAME>=<ENV_VALUE>

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

PUBLIC_KEY="-----BEGIN PGP PUBLIC KEY BLOCK-----
Comment: ABAF 11C6 5A29 70B1 30AB  E3C4 79BE 3E43 0041 1886

xsBNBE55CJIBCACkn+aOLmsaq1ejUcXCAOXkO3w7eiLqjR/ziTL2KZ30p7bxP8cT
UXvfM7fwE7EnqCCkji25x2xsoKXB8AlUswIEYUFCOupj2BOsVmJ/rKZW7fCvKTOK
+BguKjebDxNbgmif39bfSnHDWrW832f5HrYmZn7a/VySDQFdul8Gl/R6gs6PHJbg
jjt+K7Px6cQVMVNvY/VBWdvA1zckO/4h6gf3kWWZN+Wlq8wv/pxft8QzNFgweH9o
5bj4tnQ+wMCLCLiDsgEuVawoOAkg3dRMugIUoiKoBKw7b21q9Vjp4jezRvciC6Ys
4kGUSFG1ZjIn3MpY3f3xZ3yuYwrxQ8JcA7KTABEBAAHOwE0ETnkIkgEIAN+ybgD0
IlgKRPJ3eksafd+KORseBWwxUy3GH0yAg/4jZCsfHZ7jpbRKzxNTKW1kE6ClSqeh
UsuXT5Vc1eh6079erN3y+JNxl6zZPC9v+5GNyc28qSfNejt4wmwa/y86T7oQfgo7
7o8Gu/aO/xzOjw7jSDDR3u9p/hFVtsqzptxZzvs3hVaiLS+0mar9qYZheaCUqOXO
KVo38Vg5gkOhMEwKvZs9x3fINU/t8ckxOHq6KiLap5Bq87XP0ZJsCaMBwdLYhOFx
AiEVtlzwyo3DvMplIahqqNELb71YDhpMq/Hu+42oR3pqASCPLfO/0GUSdAGXJVhv
7L7ng02ETSBmVOUAEQEAAcLAdgQYAQIACQUCTnkIkgIbDAAhCRB5vj5DAEEYhhYh
BKuvEcZaKXCxMKvjxHm+PkMAQRiG6hsH/0WLUZUbmqc+rXhLRYpgRbc3z3Uvfstp
eYOH3vuv+PZ3Jk6hgiJXivHprq6uGr1RtyA3D+R7TVM0zjLsSFb+UWfElBdIyN2x
cZxv0fBR68OTYUxXWH2CQcuWpFSVOmNV1DBMH3Ax3htaFmzHJtOcaHqjx0LAERoY
2wexIFg7zU5etMT99xkSAoJ4pbbF0pGJrO7oy7lYtTqAHLac5zqgvbMolmMAJ+WV
DMHHn7rPY3hKPQkE6hvPhFHYksSUwRyQxt2pshL5z6fTYi0yYI5GBqR/viT5MRtp
nHdlNUeeG+pCpqdnPWLgjkjAcnGRSxgt12BivKVkf4zA0OUHm7cjXfw=
=HpqG
-----END PGP PUBLIC KEY BLOCK-----"

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

<ENV_NAME>=@<SECRET_NAME>

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

DB_PASSWORD=@POSTGRESQL_PASS

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.

Koyeb-provided runtime 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 at runtime:

VariableDetails
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.
Example: <SERVICE_NAME>-<ORGANIZATION>.koyeb.app
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_PORT_<PORT>_PROTOCOLDescription: The protocol of the exposed port <PORT>. Can be tcp, http, or http2.
Example: http
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_PRIVILEGEDDescription: Whether the container is running in privileged mode (opens in a new tab). Can be true or false.
Example: true
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
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.
Example: github.com/koyeb/example-qwik
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

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:

process.env.DATABASE_URL