Environment Variables and Secrets

Apps often need API keys, connection details, and other configuration to communicate with external services. Managing these values as environment variables lets you change configuration without hard-coding it in the application.

This page explains how to configure ordinary environment variables and sensitive secrets in Keelson.

Choose where to define a value

Keelson provides two places for user-defined environment variables:

Use the env field in keelson.yaml for non-sensitive values that are safe to commit.
Use secrets in the console for API keys, access tokens, passwords, and other sensitive values.

Both kinds are exposed to the running application as normal environment variables, but they differ in visibility and in where you manage them.

Define non-sensitive values in keelson.yaml

Values in the env field are available to the running application. They are not passed into the build.

slug: my-app
runtime: node-slim
command: "npm start"
env:
  NODE_ENV: "production"
  PUBLIC_API_ORIGIN: "https://api.example.com"

Use this field for configuration that does not need to be secret, such as an operating mode or a public service URL.

Do not define the same key twice, and do not use YAML merge keys to construct env. Keelson rejects ambiguous definitions rather than guessing which value you intended.

Store sensitive values as secrets

Configure sensitive values from the Secrets area in the Keelson console. Keelson encrypts secret values at rest and injects them into the app at runtime.

The console lists each secret’s key, scope, and last-updated time. It does not return the stored value for display. To change a secret, enter a replacement value.

Secret names use environment-variable syntax. Choose a descriptive uppercase name such as OPENAI_API_KEY or DATABASE_URL, and make the application read that name.

Secret scopes

Secrets can be defined at workspace scope or app scope.

Workspace secrets

A workspace secret is available to apps in that workspace. Use workspace scope for a value intentionally shared by multiple apps, such as a common service credential.

Workspace secrets are managed from the workspace’s secret settings. Changes are tracked as configuration changes for the apps that use them.

App secrets

An app secret applies only to one app. Manage it from the Secrets tab on the app details page.

Use app scope when an app needs its own credential or when it must override a workspace value.

Precedence

If the same key is defined in more than one place, Keelson resolves it in this order:

Priority	Source	Effect
Highest	App secret	Applies only to the selected app.
Middle	Workspace secret	Applies to apps in the workspace unless an app secret overrides it.
Lowest	`keelson.yaml` `env`	Supplies the non-sensitive value committed with the source.

For example, you can define API_KEY as a workspace secret and then define a different API_KEY as an app secret for one app. That app receives its app-specific value.

Apply changes

Adding, replacing, or deleting a secret marks the app configuration as having unapplied changes. Use Apply changes in the console, or redeploy the app, to create a new revision with the updated environment.

Changing env in keelson.yaml also requires a deployment. Existing running revisions do not change in place.

Build-time and runtime availability

Stage	`keelson.yaml` `env`	Secrets
Build	Not available	Not available
Runtime	Available	Available

Neither env values nor secrets reach the build. The build sees only the source files you upload, so a public value a frontend build needs — such as VITE_API_URL — must be written into a file that ships with your source, such as your build tool’s config file.

Be careful with frontend build variables: values embedded in browser JavaScript are public even if their names look sensitive. Never use a build-time variable to conceal a credential.

Read values in your app

Your app reads both env values and secrets through its language’s ordinary environment-variable API.

Python:

import os

api_key = os.environ["API_KEY"]

Node.js:

const apiKey = process.env.API_KEY;

Go:

apiKey := os.Getenv("API_KEY")

Treat a missing required variable as a startup configuration error. This produces a clear deployment failure instead of an error only when a user reaches a particular feature.

Values that belong in secrets

Store values like these as console secrets:

API keys and access tokens
OAuth client secrets
Database connection strings containing credentials
Credentials for external services
Webhook signing secrets
Encryption and session keys

Do not print these values in build output, runtime logs, error messages, or client-side responses.

Environment variables set by Keelson

Keelson injects platform-owned variables into each running app. Do not define or override them yourself.

Variable	Meaning
`PORT`	Port on which the web app must listen.
`TZ`	Workspace timezone.
`KEELSON_MODE`	Platform mode marker.
`KEELSON_APP_ID`	Internal application ID.
`KEELSON_WORKSPACE_ID`	Internal workspace ID.
`KEELSON_TENANT_ID`	Compatibility alias for `KEELSON_WORKSPACE_ID` (same value).
`KEELSON_DEPLOY_ID`	Internal ID of the current deployment.
`KEELSON_APP_URL`	The app’s public origin, when its host can be resolved.
`KEELSON_DIRECTORY_BASE_URL`	Base URL of the Directory API, when the app’s host can be resolved.

The former tenant-named variable remains accepted as a compatibility alias. No removal date is set.

Additional variables are injected when a feature is enabled. For example, an app using managed libSQL receives its database URL and authentication token through platform-managed environment variables.