# 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](/docs/deploys.md)). A cron job picks the new values up from its next run. With the API, change some variables and leave the rest alone: ```sh curl -sS -X PATCH https://onkilby.com/api/v1/services//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 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](/docs/environment-groups.md) 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](/docs/previews.md) | `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/`). 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](/docs/blueprints.md); 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](/docs/previews.md), `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 `secrets` permission (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//env` lists 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](/docs/kilby-ai.md). > [!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/`. 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: ```sh curl -sS -X PUT https://onkilby.com/api/v1/services//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 --yes ``` The answer says whether the service `restarted`. Sending the same content again changes nothing and restarts nothing. ### Where the service finds it - At `/etc/secrets/`, 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 `.env` next to itself, link it in the start command, for example `ln -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`, `gosu` or `setpriv`, 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 `secrets` permission (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//secret-files` lists 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](/docs/environment-groups.md). `GET /api/v1/services//env` lists the service's own variable names; `GET /api/v1/services//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](/docs/databases.md). ## Related - [Environment groups](/docs/environment-groups.md): share variables between services. - [Disks and scaling](/docs/disks-scaling.md): what a disk changes about a restart. - [Services](/docs/services.md): the other settings of a service. - [Deploys, rollbacks and downtime](/docs/deploys.md): what a save does. - [Workspaces, roles and 2FA](/docs/workspaces.md): who has the `secrets` permission. - [Use Kilby from an AI agent](/docs/agents.md): why an agent's key should not read secrets.