環境変数とシークレット

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

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

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

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

このアプリに必要な設定値と API キーを整理してください。設定ファイルには名前と用途を記載し、私が値を入力するファイルを用意してください。入力後に Keelson への登録と反映をお願いします。

設定ファイルの作成、アプリ側で値を読み取る処理、Keelson へのシークレットの登録・反映まで、エージェントに依頼できます。秘密の値はチャットに貼る代わりに、手元の設定ファイルへ入力して、そのファイルから登録してもらいます。コンソールから自分で入力することもできます。

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

Keelson のスキルを設定した AI エージェントに、手元の env ファイルからシークレットを登録するよう依頼できます。初回デプロイ時の登録も、既存アプリの値の更新も依頼できます。

.env.keelson に入力した値を、このアプリのシークレットに登録して反映してください。値そのものはチャットやログに出力しないでください。

以下のファイルは書式の例です。必要なキーをエージェントに用意してもらい、値を入力します。

.env.keelson

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

自分で登録する場合は、既存アプリの「シークレット」タブで追加・更新・削除できます。保存後に表示されるのは名前と更新日時で、値は再表示されません。

CLI から登録する場合は、次のコマンドを使います。エージェントもこれらのコマンドで登録・反映できます。

# 初回デプロイと同時に登録
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"

• 値は必ず引用符で囲みます（数値・真偽値も）。引用符がないとデプロイが拒否されます
• KEELSON_ で始まる名前は書けません（Keelson が設定します）。PORT は書いても無視され、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 が未登録だと「OPENAI_API_KEY を設定してください」と表示されます。値を登録してから、もう一度デプロイします
• SLACK_WEBHOOK_URL は一覧にありますが、必須条件には含まれていないため、未登録でもこのチェックではデプロイを止めません

required を書かない場合、Keelson はこの必須チェックを行いません。必要な値が不足していてもデプロイ時のチェックでは検出されず、アプリの起動時や API キーを使う操作時にエラーになることがあります。

設定する範囲と優先順位

範囲（スコープ）	設定場所	用途
ワークスペース	コンソールの「シークレット」	全アプリ共通の値（共有 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。

機能を有効にすると追加の変数が設定されます。完全な一覧、各変数の設定条件、互換性のために残されている変数は環境変数一覧にあります。

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

次に読む

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