On this page
Environment variables and secrets
Environment variables are how you give a service its settings and secrets: database URLs, API keys, feature flags. Kilby stores them encrypted and hands them to your program when it starts.
Set them#
In the dashboard, open the service and its Environment tab. Add rows of name and value, or click Paste a .env file to add many at once (blank lines and # comments are skipped). Click Save and deploy: saving starts a new deploy, so a running service restarts with the new values (a service with a disk is down for a short time while it restarts: see Deploys). A cron job picks the new values up from its next run.
With the API, change some variables and leave the rest alone:
curl -sS -X PATCH https://onkilby.com/api/v1/services/<id>/env \
-H "Authorization: Bearer $KILBY_API_KEY" \
-H "Content-Type: application/json" \
-d '{"set": {"LOG_LEVEL": "debug"}, "unset": ["OLD_FLAG"]}'The answer lists the names now set and says whether the service restarted. To replace all variables at once, send env when you create or change the service. With the command line tool: kilby env set <service> LOG_LEVEL=debug, kilby env unset, kilby env import .env.
What a name and a value may be#
| Rule | Limit |
|---|---|
| Name | Letters, digits and underscores, not starting with a digit, up to 128 characters |
| Value | Up to 8 KB. Line breaks are fine, so a private key works. A NUL character is not. |
| Variables per service | 100 |
| All names and values together | 512 KB |
Values are not expanded: $OTHER stays as you wrote it.
Variables Kilby sets#
Kilby adds a few variables to the ones you define. The Environment tab and the page of each deploy list them, read-only and with their values, so nothing your program receives is hidden. A variable you define with the same name always wins, whether it is in the service or in a group the service uses, and the list then says that yours is used.
| Variable | Set for | Value |
|---|---|---|
PORT | A service that has a port | The port you chose. |
WEB_CONCURRENCY | A web or private service that has it switched on | How many worker processes an HTTP server should start: the CPU of the instance type rounded up to a whole number, and at least 1. |
KILBY | Every service | true, so that code can tell it runs on Kilby. |
KILBY_SERVICE_NAME | Every service | The service's name. |
KILBY_SERVICE_TYPE | Every service | web, private, worker or cron. |
KILBY_EXTERNAL_HOSTNAME | A web service | The service's address on Kilby, without https://. A custom domain is not in it. |
KILBY_EXTERNAL_URL | A web service | https:// and that address. |
KILBY_GIT_REPO_SLUG | A service built from Git | The repository, owner/name (for a public repository, its path on the host). |
KILBY_GIT_BRANCH | A service built from Git | The branch Kilby builds. For a public repository, the branch or tag you gave; not set when it builds the default branch. |
KILBY_GIT_COMMIT | A service built from Git | The commit the running version was built from, when Kilby knows it. A rollback brings back the commit of the version it restores. |
KILBY_PREVIEW | A pull request preview | true. |
KILBY_PULL_REQUEST | A pull request preview | The number of the pull request it runs. |
Servers such as Gunicorn, Uvicorn, Puma and pm2 read WEB_CONCURRENCY as their number of workers, so a bigger instance type uses its cores without a change to your start command. The value for each instance type:
| Instance type | CPU | WEB_CONCURRENCY |
|---|---|---|
starter | 0.5 | 1 |
standard | 1 | 1 |
pro | 2 | 2 |
Changing the instance type changes the value at the next deploy, and saving the new instance type is a deploy. A rollback restores the instance type of the deploy it goes back to, and with it the value. Workers and cron jobs do not get WEB_CONCURRENCY: it is a setting for HTTP servers, and a worker that reads it should have it defined by you.
A service that existed before Kilby began setting WEB_CONCURRENCY keeps working exactly as it did: for it the switch is off, and nothing changes until you turn it on. A service you create now has it on. The switch is under Run in the service's Settings (Set WEB_CONCURRENCY for me), and auto_concurrency in the REST API (PATCH /api/v1/services/<id>).
A service that existed before Kilby began setting the KILBY variables gets them with its next deploy: the version that runs now does not change, and the Environment tab says so until then.
Render compatibility#
Code written for Render often reads the variables Render sets: Render's Django guide turns debug off with DEBUG = 'RENDER' not in os.environ and adds RENDER_EXTERNAL_HOSTNAME to ALLOWED_HOSTS. Switch on Render compatibility and Kilby also sets them, with this service's values on Kilby, so that code works unchanged. The switch is under Run in the service's Settings (Set Render's variables), render_compat in the REST API, and renderCompatibility: true in a blueprint; a render.yaml you import turns it on. It changes at the next deploy, and a variable you define yourself always wins.
| Variable | Value on Kilby |
|---|---|
RENDER | true |
IS_PULL_REQUEST | true in a pull request preview, false in every other service. |
RENDER_SERVICE_NAME | The service's name. |
RENDER_SERVICE_TYPE | web, pserv (a private service), worker or cron. |
RENDER_EXTERNAL_HOSTNAME, RENDER_EXTERNAL_URL | For a web service, its address on Kilby, like KILBY_EXTERNAL_HOSTNAME and KILBY_EXTERNAL_URL. |
RENDER_GIT_REPO_SLUG, RENDER_GIT_BRANCH, RENDER_GIT_COMMIT | For a service built from Git, the same as the KILBY_GIT_ variables. |
RENDER_CPU_COUNT | The CPU of the instance type, such as 0.5. |
RENDER_WEB_CONCURRENCY | For a web or private service, the same number as WEB_CONCURRENCY would be. |
With Render compatibility on, the images built from a Dockerfile Kilby writes for you have, from the next build on, Render's code folder, /opt/render/project/src, as a link to the app's folder, so scripts that cd there work. An image built from your own Dockerfile is left as it is.
A Python app keeps the Python version in its build plan: a build never moves a running service to another Python by itself, and Settings shows the version the next build uses. With Render compatibility on, the service's PYTHON_VERSION variable (a build variable or one of its own; not one from a group) replaces a version Kilby detected, from the next build, as on Render; a version chosen for the plan, and the plan of a service set up before Kilby recorded where its version came from, stay as they are. A new service from an imported render.yaml gets its version as Render picks it, once: .python-version, else Render's default for a new service, Python 3.14, which is then kept; runtime.txt, Heroku's file, is not used, because Render does not read it. Render's default depends on when a service was created there, which Kilby cannot see, so set PYTHON_VERSION to the version your Render service runs. The build log confirms the version.
RENDER_SERVICE_ID, RENDER_INSTANCE_ID and RENDER_DISCOVERY_SERVICE are not set: they have no true value on Kilby. A custom domain is not in RENDER_EXTERNAL_HOSTNAME on Kilby either, as on Render: add it to ALLOWED_HOSTS yourself.
How they are stored, and who can read them#
- Values are encrypted with AES-256-GCM before they are saved, and are kept as a Kubernetes Secret in your workspace's namespace while the service runs.
- The Environment tab hides values until you reveal them. Names that look like secrets are marked.
- Only the roles with the
secretspermission (Developer, Admin and Owner) can see or change values. A Viewer sees the names, not the values. - The API never returns a value:
GET /api/v1/services/<id>/envlists names only, for every key role. - A change to the variables is recorded in the Activity page as the names added, changed and removed, never the values.
- Kilby AI never receives a value. See Kilby AI.
Warning
Variables are visible to the program that receives them, and to anyone who opens a shell in the service. Do not print them in logs. Logs are readable by every member of the workspace.
Generate a value#
Next to the value of a variable there is a Generate button: on the Environment tab, in the new service form and on the page of an environment group. (The gallery's templates do not have it: the keys they ask for, such as an OpenAI key, are issued by someone else, and a random value would only look like one.) It fills the field with a random value, from a short menu: 32 hex characters, 48 URL-safe base64 characters, a UUID, or a password of 24 letters and digits.
The value is made in your browser, with crypto.getRandomValues. Nothing is sent to Kilby when it is made, and Kilby does not know it until you save. It is shown in the field so that you can read and copy it, and the page says so: save to keep it. If you leave the page without saving, the value is gone and cannot be made again. The button needs JavaScript and does not appear without it.
Secret files#
Some programs read a secret from a file, not from a variable: a .env file, a private key, a certificate, a service-account file. A secret file is a text file you give to a service. Kilby stores it encrypted and the service reads it at /etc/secrets/<filename>.
To add one, open the service's Environment tab and click Add secret file in the Secret files card, or use the Advanced section of the new service form. Give it a name such as .env or private-key.pem, and paste the content or choose a file: a chosen file is read in your browser and goes nowhere until you save. Saving starts a new deploy, like saving variables (a service with a disk is down for a short time while it restarts, and a cron job takes the file from its next run). Changing several files with one request is one restart.
With the API and the command line tool:
curl -sS -X PUT https://onkilby.com/api/v1/services/<id>/secret-files/.env \
-H "Authorization: Bearer $KILBY_API_KEY" \
-H "Content-Type: application/json" \
-d '{"content": "DATABASE_URL=postgres://app:example@db-main-rw:5432/app\n"}'
kilby secret-file put api .env ./.env
kilby secret-file list api
kilby secret-file rm api .env --yesThe answer says whether the service restarted. Sending the same content again changes nothing and restarts nothing.
Where the service finds it#
- At
/etc/secrets/<filename>, read-only, with mode 0400. A folder of your image at that path is hidden by the mount. - Not in the working directory. Kilby does not know which folder your image starts in, and a copy there could hide one of the image's own files. Read the file from
/etc/secrets. If a program insists on finding.envnext to itself, link it in the start command, for exampleln -sf /etc/secrets/.env .env && exec node server.js(the working directory must be writable). - A change of a file reaches the service in a new deploy. While that deploy starts, instances that are still running may already see the new content, because the cluster updates the mounted files in place.
- The files are kept in memory on the machine that runs the service and are not written to its disk. They are not in the image, not in the environment and not in the logs.
- The files are owned by root. On a service without a disk, group 1000 can read them, and Kilby puts every process of the service in that group. A program that runs as another user can therefore read them. If your start command switches users with
su,gosuorsetpriv, make sure the new user is in group 1000, or read the file before switching. - On a service with a disk, only root can read them. Kilby cannot give them a group without also changing the permissions of the files on your disk, which would break programs that insist on strict permissions. If your image runs as another user, put those values in variables, or use a service without a disk.
What a file may be#
| Rule | Limit |
|---|---|
| Name | Letters, digits, dots, underscores and hyphens, up to 128 characters. No slash, not made of dots only, not starting with two dots. Unique in the service. |
| Content | Text (valid UTF-8, no NUL character), from 1 byte up to 128 KB. To keep a binary file, encode it (for example in base64) and decode it when the service starts. |
| Files per service | 10 |
| All files of a service together | 768 KB |
| Files per workspace | 100, and 8 MB together |
| Changes per minute | 60 for the whole workspace |
The dashboard saves line breaks as LF. The API keeps the content exactly as you send it.
Who can read them#
- Content is encrypted with AES-256-GCM before it is saved, like a variable, and is kept as a Kubernetes Secret in your workspace's namespace while the service runs. Deleting a service deletes its files and that Secret.
- Only the roles with the
secretspermission (Developer, Admin and Owner) can read a file again (Edit shows it) or change one. A Viewer sees the names, sizes and dates, not the content. - The API never returns content:
GET /api/v1/services/<id>/secret-fileslists names, sizes and dates for every key role. - A change is recorded in the Activity page as the names added, changed and removed, never the content.
Warning
A file is visible to the program that reads it, and to anyone who opens a shell in the service. Do not print it in logs. Logs are readable by every member of the workspace.
Share variables between services#
Variables that several services need (an API key, a feature flag) can live in an environment group: you define them once, link the group to each service, and a change restarts every service that uses it. A service's own variable wins over a group's. The Environment tab of a service shows its linked groups and an Effective variables table of what it really receives. See Environment groups. GET /api/v1/services/<id>/env lists the service's own variable names; GET /api/v1/services/<id>/env/effective lists every name it runs with and where each comes from.
Connect a database#
On a database's page, Connect a service adds its connection URL to a service as a variable (DATABASE_URL by default) and starts a new deploy. See Databases.
Related#
- Environment groups: share variables between services.
- Disks and scaling: what a disk changes about a restart.
- Services: the other settings of a service.
- Deploys, rollbacks and downtime: what a save does.
- Workspaces, roles and 2FA: who has the
secretspermission. - Use Kilby from an AI agent: why an agent's key should not read secrets.