keelson.yaml の設定

keelson.yaml は、アプリの起動方法やデータベースの利用、定期実行などを Keelson に伝える設定ファイルです。アプリのソースコードと同じフォルダの一番上（プロジェクトルート）に置きます。

通常は、デプロイを依頼した AI エージェントが作成・更新します。 このページでは、エージェントが作った設定を確認するときに役立つ項目を説明します。すべての設定項目や細かい条件は keelson.yaml リファレンスを参照してください。

設定ファイルの例

Python の Web アプリで、Keelson のデータベースを使う例です。

slug: my-app              # アプリの識別子
runtime: python-slim      # Python の実行環境
command: "python app.py"  # Web サーバーを起動するコマンド
db:
  mode: libsql            # Keelson の Managed SQLite を使う

項目	確認すること
slug	アプリを識別する名前です。https://<ワークスペース>--<slug>.keelson.run の一部になります
runtime	アプリの言語に合う実行環境です。Python / Node.js / Go から選びます
command	アプリの Web サーバーを起動するコマンドです。依存パッケージのインストールはビルド時に行われます
db.mode	Keelson のデータベースを使うなら libsql、使わない場合や外部 DB を使う場合は none です

db.mode: libsql はデータベースを用意する設定です。アプリのコードにも、用意された DB に接続して読み書きする処理が必要です。既存のファイル SQLite が、この設定だけで Managed SQLite に切り替わるわけではありません。

Files / Media SDK だけを使うアプリは db.mode: none で構いません。Files / Media の利用を宣言する設定は不要です。

アプリの構成による違い

どのアプリにも slug、runtime、db.mode が必要です。そのほかの項目は、アプリの構成で変わります。

アプリの構成	主な設定
Web アプリ	command に起動コマンドを書く
静的サイト / SPA	type: web と assets を設定し、command は書かない
静的な画面 + API サーバー（ハイブリッド）	assets と command の両方を設定する
定期実行だけのアプリ	crons を設定し、Web サーバー用の command は書かない

Web アプリに crons を追加することもできます。定期実行の設定は定期実行ジョブを参照してください。

静的サイト / SPA

ビルド済みのファイルを配信する例です。assets.dir にはビルド出力のフォルダを指定します。

slug: my-site
type: web
runtime: node-slim
db:
  mode: none
assets:
  dir: dist
  fallback: index.html # SPA で、画面の URL を直接開いたときにも index.html を返す

静的サイトは手元でビルドしてからデプロイします。Keelson 上で依存パッケージのインストールやビルドは行われません。通常の静的サイトで、見つからないページを index.html に戻す必要がなければ fallback は省略できます。

静的な画面 + API サーバー

/api 以下へのリクエストをサーバーで処理し、それ以外ではビルド済みの画面を配信する例です。

slug: my-app
runtime: node-slim
command: "node server.js"
db:
  mode: libsql
assets:
  dir: dist
  fallback: index.html
  api: /api

必要に応じて追加する設定

やりたいこと	設定	詳しくは
アプリの説明を付ける	description	リファレンス
アプリに設定値を渡す	env	環境変数とシークレット
API キーなどを使う	secrets に必要な名前を宣言する。秘密の値は書かない	環境変数とシークレット
デプロイ時に DB のテーブルや列を変更する	db.migrate	データベース（Managed SQLite）
決まった時刻・間隔で処理を実行する	crons	定期実行ジョブ
起動確認に使うページを指定する	health.path	リファレンス
外部サービスから Webhook を受け取る	auth.endpoints	外部システムとの連携

デプロイ前に確認すること

• アプリ名と保存先が意図どおりか。 slug が対象アプリの名前か、db.mode が利用するデータベースに合っているかを確認します。
• API キーやパスワードが直接書かれていないか。 secrets には名前と説明だけを書き、値はコンソールなどから設定します。
• 必要な定期処理が設定されているか。 アプリ内のタイマーに任せず、crons のスケジュールを確認します。

起動コマンドや依存ファイルの確認は、エージェントに依頼できます。次のコマンドでは、アップロードせずに設定と送信対象のファイルを確認できます。

keelson deploy --check --json

この確認だけでは、実際にアプリが起動するかやプランの上限内かまでは分かりません。デプロイ後はアプリの URL を開き、動作を確認してください。

設定を変更したら

keelson.yaml の変更は、次のデプロイで反映されます。エージェントに「設定を変更して再デプロイしてください」と依頼してください。

PORT など Keelson が設定する環境変数や、廃止された設定項目は自分で追加する必要はありません。古い設定を引き継ぐ場合や検証エラーが出た場合は、keelson.yaml リファレンスを参照してください。

次に読む

• keelson.yaml リファレンス
• デプロイする
• 対応アプリと制約 — ランタイムのバージョンと制約