環境変数とシークレット

外部サービスの API キーや接続先などを、アプリに設定できます。設定値をアプリに渡す仕組みを「環境変数」と呼びます。API キーなどの秘密の値は、Keelson の「シークレット」に登録します。

種類	例	どこに書くか
秘密でない設定値	NODE_ENV、LOG_LEVEL、公開 API の URL	keelson.yaml の env
秘密の値	API キー、トークン、DB 接続文字列、Webhook の署名シークレット	シークレット（コンソール / CLI / デプロイ時の env ファイル）

keelson.yaml はソースコードと一緒に管理するファイルです。秘密の値は含めず、シークレットに登録します。

必要な設定を AI エージェントに確認する

このアプリに必要な設定値と API キーを整理してください。設定ファイルには名前と用途を記載し、秘密の値を登録する場所を案内してください。

設定ファイルや値の読み取り処理はエージェントに依頼できます。秘密の値はチャットに貼る代わりに、コンソールや手元の設定ファイルへ入力します。

シークレットの値を登録する

既存のアプリは、コンソールのアプリ画面にある「シークレット」タブで追加・更新・削除できます。保存後に表示されるのは名前と更新日時で、値は再表示されません。

初回デプロイ時には、手元の env ファイルに値を入力し、デプロイと同時に登録することもできます。以下のファイルは書式の例です。

.env.keelson

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

# 初回デプロイと同時に登録
keelson deploy --new --secrets-from-env-file .env.keelson

# 既存アプリの更新と同時に登録
keelson deploy --secrets-from-env-file .env.keelson

# 値を登録し、アップロード・ビルドなしの再デプロイで反映
keelson secrets set --from-env-file .env.keelson --apply

--secrets-from-env-file で指定したファイルはアップロード対象から除外されます。秘密を含むファイルは Git に追加せず、値をコマンドに直接書くことも避けてください。コマンドに書いた値はシェル履歴に残ることがあります。

登録した値をアプリに反映する

シークレットは保存しただけでは、動いているアプリに反映されません。次のいずれかで反映します。

• コードも更新する場合は、keelson deploy でデプロイする
• 値だけを反映する場合は、コンソールに表示される「未反映の変更があります」の 適用ボタンを押す
• CLI で登録と反映をまとめて行う場合は、上の secrets set --apply を使う

「適用」と --apply は、コードを再アップロード・ビルドせずに再デプロイします。最後に成功したデプロイの実行用ファイル（コンテナイメージ）を使い、新しい値でアプリを起動します。完了後は、API キーを使う操作などが動くか確認します。

env（秘密でない値）

ここからは設定ファイルとコードの詳細です。秘密でない値は、エージェントに keelson.yaml の env への記載を依頼できます。

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

• 値は必ず引用符で囲みます（数値・真偽値も）。引用符がないとデプロイが拒否されます
• PORT と KEELSON_ で始まる名前は書けません（Keelson が設定します）
• 変更は次のデプロイで反映されます

必要なシークレットを設定ファイルに記載する

keelson.yaml の secrets に、アプリが読むシークレットの名前だけを宣言します。値は書きません。

secrets:
  items:
    - name: OPENAI_API_KEY
      description: "OpenAI API key"
    - name: SLACK_WEBHOOK_URL
      description: "通知先の Slack Webhook"
  required:
    - all_of: [OPENAI_API_KEY]
      message: "OPENAI_API_KEY を設定してください"

items は名前と用途の一覧で、コンソールにも表示されます。required はデプロイに必要な条件です。この例では OPENAI_API_KEY が未設定だと message が表示されます。SLACK_WEBHOOK_URL は一覧にありますが、必須条件には含まれていません。

設定する範囲と優先順位

範囲（スコープ）	設定場所	用途
ワークスペース	コンソールの「シークレット」	全アプリ共通の値（共有 API キーなど）
アプリ	アプリ画面の「シークレット」タブ	そのアプリだけの値、またはワークスペースの値の上書き

同じ名前があれば アプリ > ワークスペース > env の順で優先されます。アプリ画面のシークレットタブには、どちらのスコープから来た値かが表示されます。

アプリからの読み方

env もシークレットも、サーバー側のコードから環境変数として読み取ります。

import os

api_key = os.environ["OPENAI_API_KEY"]

const apiKey = process.env.OPENAI_API_KEY;

ビルド時には渡らない

env もシークレットも、ビルド（依存関係のインストール、npm run build）には渡りません。ビルドが読めるのはアップロードしたソース一式だけです。

フロントエンドのビルドに埋め込む公開値（VITE_API_URL など）は、ソース内の設定ファイルに書きます。ブラウザに配布される値なので、ここに認証情報を置かないでください。

システムが自動設定する環境変数

Keelson はプラットフォーム管理の変数を各アプリに設定します。自分で定義または上書きしないでください。

変数	内容
PORT	Web アプリの待ち受けポート。
TZ	ワークスペースのタイムゾーン。
KEELSON_MODE	プラットフォームモードを示す値。
KEELSON_APP_ID	アプリの内部 ID。
KEELSON_WORKSPACE_ID	ワークスペースの内部 ID。
KEELSON_TENANT_ID	KEELSON_WORKSPACE_ID の互換用別名（値は同じ）。
KEELSON_DEPLOY_ID	現在のデプロイの内部 ID。
KEELSON_APP_URL	ホストを解決できる場合のアプリの公開 URL。
KEELSON_DIRECTORY_BASE_URL	ホストを解決できる場合の Directory API のベース URL。

旧 tenant 名の変数も互換のため受け付けます。撤去時期は未定です。

機能を有効にすると追加の変数が設定されます。完全な一覧と設定条件は環境変数一覧にあります。

NODE_ENV は自動設定されないため、アプリが必要とする場合は env に記載します。

次に読む

• 環境変数一覧
• 外部システムとの連携
• keelson.yaml リファレンス