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:

<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 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:

Variable	Details
`KOYEB_APP_NAME`	Description: Koyeb Application name. Example: `app`
`KOYEB_APP_ID`	Description: Koyeb Application ID. Example: `647813c7-09b8-44ce-a02a-0cc70092bf4c`
`KOYEB_ORGANIZATION_NAME`	Description: Koyeb Organization name. Example: `my-organization`
`KOYEB_ORGANIZATION_ID`	Description: Koyeb Organization ID. Example: `6704aff2-36ec-4e13-ba1e-0438eaf7a65e`
`KOYEB_SERVICE_NAME`	Description: Koyeb Service name. Example: `my-service`
`KOYEB_SERVICE_ID`	Description: Koyeb Service ID. Example: `41dcf9cb-53a4-4b02-960c-f421254a1678`
`KOYEB_SERVICE_PRIVATE_DOMAIN`	Description: Default Service URL for service discovery. Example: `<SERVICE_NAME>.<APP_NAME>.koyeb`
`KOYEB_PUBLIC_DOMAIN`	Description: Default public Service URL. Only routable for `web` Services. Example: `<SERVICE_NAME>-<ORGANIZATION>.koyeb.app`
`KOYEB_PORT_<PORT>_PROTOCOL`	Description: The protocol of the exposed port `<PORT>`. Can be `tcp`, `http`, or `http2`. Example: `http`
`KOYEB_PRIVILEGED`	Description: Whether the container is running in privileged mode (opens in a new tab). Can be `true` or `false`. Example: `true`
`KOYEB_DOCKER_REF`	Description: 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_SHA`	Description: The SHA (opens in a new tab) of deployed Git commit. Example: `ac18568cd565650e96216c8d092a6c60f9ed09b` Availability: Only for GitHub deployments
`KOYEB_GIT_BRANCH`	Description: Git branch name of the currently deployed Service. Example: `main` Availability: Only for GitHub deployments
`KOYEB_GIT_REPOSITORY`	Description: Git repository URL of the deployed Service. Example: `github.com/koyeb/example-qwik` Availability: Only for GitHub deployments
`KOYEB_GIT_COMMIT_MESSAGE`	Description: Commit message of the deployed Git commit. Example: `Fix README heading` Availability: Only for GitHub deployments
`KOYEB_GIT_COMMIT_AUTHOR`	Description: 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):

Variable	Details
`KOYEB_REGION`	Description: Region where the service is deployed. Example: `fra`
`KOYEB_REGIONAL_DEPLOYMENT_ID`	Description: Regional Deployment ID of the Service, which may be helpful for support. Example: `3a1bb3d0-7502-40a5-ae12-7e28f807531b`
`KOYEB_INSTANCE_ID`	Description: Koyeb Instance ID. Example: `e5f296b6-a911-8637-234e-f929e8bd5d87`
`KOYEB_INSTANCE_TYPE`	Description: Type of Instance running the Service. Example: `nano`
`KOYEB_INSTANCE_MEMORY_MB`	Description: The memory allocated to the Instance, in MB. Example: `256`
`KOYEB_HYPERVISOR_ID`	Description: The ID of the hypervisor the Service is running on, which may be helpful for support. Example: `fra1-rn23u23`
`KOYEB_DC`	Description: 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:

process.env.DATABASE_URL

Private Container Registry Secrets Monorepo