Environment variables
This page lists the environment variables Keelson sets in app containers and the variables used to run the Keelson SDK locally.
Do not declare or override automatically supplied variables in env in keelson.yaml; use the values Keelson provides. Names beginning with KEELSON_ are reserved and cannot be used in env or secrets.
Core environment variables
Section titled “Core environment variables”| Variable | Description |
|---|---|
PORT | Port the app listens on. Read this value; do not set it |
TZ | Workspace time zone (for example, Asia/Tokyo) |
KEELSON_MODE | keelson on Keelson. Usually unset during local development; local also selects local storage for the Files / Media SDK and local synchronous runs for the Tasks SDK |
KEELSON_APP_ID | Internal app 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 deploy |
KEELSON_APP_URL | App URL (https://<ws>--<app>.keelson.run). Use when an absolute URL is required. Set when Keelson can generate the app’s public hostname |
KEELSON_DIRECTORY_BASE_URL | Directory API base URL used by the Identity SDK. Set to the same value as KEELSON_APP_URL, under the same condition |
The former tenant-named variable remains accepted as a compatibility alias. No removal date is set.
SDK and feature environment variables
Section titled “SDK and feature environment variables”The Files / Media / Identity / Tasks / Email SDKs read their connection settings and credentials automatically. App code generally does not need to access these values directly.
| Variable | Condition | Description |
|---|---|---|
KEELSON_DB_URL | db.mode: libsql | Managed SQLite connection URL |
KEELSON_DB_AUTH_TOKEN | db.mode: libsql | Managed SQLite authentication token |
TURSO_DATABASE_URL / TURSO_AUTH_TOKEN | db.mode: libsql | Aliases for the two variables above (for compatibility) |
KEELSON_FILES_BUCKET / KEELSON_FILES_PREFIX | Container deployments with file storage configured (automatic for standard deployments) | Storage location used by the Files SDK |
KEELSON_INTERNAL_MEDIA_BASE_URL / KEELSON_APP_MEDIA_TOKEN | Container deployments with Media enabled (automatic for standard deployments) | Upload destination and authentication token used by the Media SDK |
KEELSON_MEDIA_URL_PREFIX | Same condition as the Media SDK upload destination and token | Media delivery URL prefix (/__keelson/media/) |
KEELSON_DIRECTORY_TOKEN | After keelson apps directory enable and redeployment | Directory API token used by the Identity SDK. Handle only on the server |
KEELSON_EMAIL_API_URL / KEELSON_EMAIL_TOKEN | Container deployments (automatic for standard deployments) | Endpoint and authentication token the Email SDK uses to send email. Handle only on the server |
KEELSON_EMAIL_WEBHOOK_SECRET | Same condition as KEELSON_EMAIL_TOKEN | Key for verifying the signature of email delivery result notifications. Pass it to the Email SDK’s verification function |
KEELSON_TASKS_BASE_URL | Set in web, scheduled job, and task containers while Keelson accepts background tasks (whether or not the app declares tasks) | URL the Tasks SDK uses to enqueue tasks and read their status. You do not set it yourself |
Static sites and SPAs (assets without command) have no container, so no runtime environment variables are set. They cannot use the Files or Media SDKs. Apps that run only scheduled jobs also omit command, but their jobs run in containers and can use SDK environment variables.
Not set
Section titled “Not set”NODE_ENV— Not set automatically. Declare"production"inenvinkeelson.yaml- External database connection details — Pass them as secrets. With
db.mode: none, Managed SQLite connection details are not set automatically
Used for local development
Section titled “Used for local development”Set these in your local environment as needed to run the SDKs during development. Do not register them in env in keelson.yaml or as Keelson secrets.
| Variable | Description |
|---|---|
KEELSON_MODE=local | Use local storage with the Files / Media SDKs. With the Tasks SDK, enqueue runs the command synchronously on your machine through the CLI’s keelson dev task run. Both also work this way when this is unset in a standard local development environment |
KEELSON_FILES_DIR | Local storage location for the Files SDK (default: ./.keelson/files) |
MEDIA_DIR | Local storage location for the Media SDK (default: ./media) |
KEELSON_LOCAL_MODE=1 | Make the Identity SDK return test data without calling the API. Not needed when you start through keelson dev serve (Run your app locally) |
KEELSON_LOCAL_USERS_FILE | User list file the Identity SDK reads when KEELSON_LOCAL_MODE=1 (default: ./.keelson/dev-users.json) |
KEELSON_LOCAL_USER_ID / KEELSON_LOCAL_USER_EMAIL / KEELSON_LOCAL_USER_NAME | ID, email address, and display name of the test user returned by the Identity SDK. Not used when a user list file exists |
KEELSON_LOCAL_WORKSPACE_ID / KEELSON_LOCAL_WORKSPACE_ROLE / KEELSON_LOCAL_APP_ID | Test workspace ID, workspace role, and app ID returned by the Identity SDK |
The former KEELSON_LOCAL_TENANT_ID and KEELSON_LOCAL_TENANT_ROLE names remain
accepted as compatibility aliases. If both old and new names are set, the names containing WORKSPACE take precedence. No removal date is set.
Related pages
Section titled “Related pages”- Environment variables and secrets — Values you configure
- Files and media
- Using identity in your app