Environment variables and secrets

You can configure API keys, service URLs, and other values for your app. Environment variables are how these values reach your code. Store confidential values, such as API keys, as Keelson secrets.

Type	Examples	Where to set it
Non-secret configuration	`NODE_ENV`, `LOG_LEVEL`, public API URLs	`env` in `keelson.yaml`
Secret values	API keys, tokens, database connection strings, webhook signing secrets	Secrets, using the console, CLI, or an env file at deployment

Keep keelson.yaml with your source code. Do not include secret values in it; register them as secrets instead.

Ask your agent what the app needs

List the configuration values and API keys this app needs. Document their names and purpose, and create a local file where I can enter the values. Once I have filled it in, register and apply them in Keelson.

Your agent can prepare the configuration, implement code that reads the values, and register and apply secrets. Enter secret values in a local configuration file instead of pasting them into chat, then ask the agent to register them from that file. You can also enter them yourself in the console.

Register secret values

An AI agent with the Keelson Agent Skill can register secrets from a local env file, either on the first deployment or when updating an existing app.

Register the values in .env.keelson as this app’s secrets and apply them. Do not print the values in chat or logs.

The following illustrates the file format. Ask your agent to prepare the keys your app needs, then fill in their values.

OPENAI_API_KEY=sk-...
SLACK_WEBHOOK_URL=https://hooks.slack.com/...

To enter values yourself, use the Secrets tab of an existing app to add, update, or delete them. After saving, only the names and update times are shown; values cannot be displayed again.

You or your agent can also register and apply them with the CLI:

# Register with the first deployment
keelson deploy --new --secrets-from-env-file .env.keelson

# Register while updating an existing app
keelson deploy --secrets-from-env-file .env.keelson

# Register and apply without uploading or rebuilding the code
keelson secrets set --from-env-file .env.keelson --apply

The file passed to --secrets-from-env-file is excluded from the upload. Do not add files containing secrets to Git or put secret values directly in commands, where they may remain in shell history.

Apply saved values to the app

Saving a secret does not update an app that is already running. Ask your agent to both register and apply the values. They take effect during the first deployment; for existing apps, use one of these options:

If you are also changing code, run keelson deploy.
To apply values only, click Apply changes in the console’s pending-changes notice.
To register and apply in one CLI command, use secrets set --apply as shown above.

Apply changes and --apply redeploy without uploading or rebuilding the code. They use the last successful deployment’s container image to start the app with the new values. Once complete, test an action that uses the API key or other changed value.

env: non-secret values

The following sections cover configuration and code details. Ask your agent to put non-secret values under env in keelson.yaml.

env:
  NODE_ENV: "production"
  LOG_LEVEL: "info"

Quote all values, including numbers and booleans. Unquoted values cause deployment to be rejected.
Names starting with KEELSON_ are rejected; Keelson supplies them. PORT is ignored if set, and Keelson’s value is used.
Changes take effect on the next deployment.

Declare the secrets your app needs

The secrets section in keelson.yaml can list secret names, their purpose, and the conditions that make them required. Do not include values. This declaration is optional. Registered secrets are passed to the app as environment variables even without a declaration.

Declarations document the required configuration and let deployment checks catch missing values. Ask your agent to identify the keys and requirements.

secrets:
  items:
    - name: OPENAI_API_KEY
      description: "OpenAI API key"
    - name: SLACK_WEBHOOK_URL
      description: "Slack webhook for notifications"
  required:
    - all_of: [OPENAI_API_KEY]
      message: "Set OPENAI_API_KEY"

items lists names and descriptions, which also appear in the console. Listing a key here does not make it required.
required defines the conditions for deployment. If the registered secrets do not satisfy them, deployment fails with the specified reason. In this example, a missing OPENAI_API_KEY displays “Set OPENAI_API_KEY”. Register the value, then deploy again.
SLACK_WEBHOOK_URL is listed but not required, so its absence does not block deployment at this check.

Without required, Keelson does not perform this required-secret check. Missing values may instead cause errors when the app starts or performs an action that uses the key.

Scope and precedence

Scope	Where to set it	Use
Workspace	Secrets in the console	Values shared across apps, such as a common API key
App	The app’s Secrets tab	App-specific values or overrides of workspace values

For the same name, precedence is app secret > workspace secret > env. The app’s Secrets tab shows which scope each value comes from.

Read values in your app

Server-side code reads both env values and secrets as environment variables.

import os

api_key = os.environ["OPENAI_API_KEY"]

const apiKey = process.env.OPENAI_API_KEY;

Values are not available during builds

Neither env nor secrets are supplied during builds, including dependency installation and npm run build. The build can only read the uploaded source files.

Put public values needed by a frontend build, such as VITE_API_URL, in configuration files within the source. These values are distributed to browsers, so do not put credentials there.

Environment variables set by Keelson

Keelson sets these platform-managed variables for apps. Do not define or override them yourself.

Variable	Purpose
`PORT`	The listening port for a web app.
`TZ`	The workspace time zone.
`KEELSON_MODE`	Indicates platform mode.
`KEELSON_APP_ID`	The internal app ID.
`KEELSON_WORKSPACE_ID`	The internal workspace ID.
`KEELSON_TENANT_ID`	Compatibility alias for `KEELSON_WORKSPACE_ID`, with the same value.
`KEELSON_DEPLOY_ID`	The internal ID of the current deployment.
`KEELSON_APP_URL`	The standard app URL.
`KEELSON_DIRECTORY_BASE_URL`	The Directory API URL.

Additional variables are set when features are enabled. See the Environment variable reference for the complete list, the conditions for each variable, and compatibility variables.

NODE_ENV is not set automatically. Add it to env if your app needs it.