はじめに ドキュメントガイド Keelson は、AI ツールなどで作った社内アプリをデプロイし、ログインとアクセス権を付けてチームで使えるようにするサービスです。
利用を始めるには、Keelson コンソールでアカウントを作成・ログイン してください。
初めて試す方はクイックスタート、すでにアプリを持っている方は持ち込みガイドから始めてください。
試す サンプルをデプロイして、ログイン保護が効くところまで。所要 15 分 持ち込む Lovable / Bolt / v0 や手元のコードで作ったアプリをデプロイする 困っている デプロイが失敗する、利用者が開けない、データが消えた Python / Node.js / Go の Web アプリ、ビルド済みの静的サイト、定期実行ジョブに対応しています。社内の数人〜数百人が使う業務アプリを想定しており、利用者数は料金に影響しません。
常駐プロセスや WebSocket を前提とする構成、GPU が必要なアプリなどには対応していません。フレームワークごとの対応状況は対応アプリと制約 を確認してください。
Keelson 専用のフレームワークで作る必要はありません。既存の外部 DB やサービスも利用できます。ほかの環境へ移す場合に必要な準備は FAQ を参照してください。
サービス概要と料金は公式サイト にあります。
まず読む
必要になったら参照する
メンバーを招待する メンバーとロール チームにアプリを共有する — 特定のチームだけに公開する手順グループとアプリ権限 — 誰がどのアプリを使えるかIP 制御 プランと制限 / 料金と契約の運用
AI エージェント向けの仕様は Keelson Deploy Spec に 1 ページでまとまっています。次の URL をエージェントに渡すと、アプリを Keelson にデプロイできるかを確認し、必要なコードや設定の変更を提案します。
https://keelson.dev/ja/docs/reference/deploy-spec.txt
ドキュメント全体の索引は /ja/llms.txt/ja/llms-full.txt.md に変えると Markdown で取得できます(例: /ja/docs/introduction/quickstart.md)。
CLI に同梱されている Skill(keelson install-agent)には、同じ内容に加えて言語別の書き換え手順が入っています。
導入前によく聞かれることは FAQ にまとめています。
クイックスタート 小さなサンプルアプリを Keelson にデプロイし、ブラウザで開き、ログインしていない人には開けないことを確認します。
できること : 自分のワークスペースに最初のアプリが作成され、専用 URL とログイン保護が付く所要時間 : 15 分ほど。ビルドの待ち時間が大半です必要なもの : Keelson のアカウント、ターミナル、Claude Code / Codex / Cursor のいずれか。外部サービスの API キーは要りません完了条件 : 発行された URL を自分のブラウザで開くと挨拶の画面が出て、シークレットウィンドウで開くとログイン画面になる
Keelson のアカウントがまだ無い方は、console.keelson.dev からサインアップしてください。
Keelson CLI は、ターミナルからログインやデプロイを行うためのツールです。使っている OS のタブを選び、次のコマンドでインストールしてください。
curl -fsSL https://keelson.dev/install.sh | sh
keelson コマンドが見つからない場合 インストーラーは、コマンドを探す場所（PATH）を変更しません。次の行を ~/.zshrc や ~/.bashrc に追加し、ターミナルを開き直してください。
export PATH = " $HOME /.keelson/bin: $PATH "
Windows 10 / 11 または Windows Server 2016 以降に標準搭載されている Windows PowerShell 5.1 以上で実行します。
irm https: // keelson.dev / install.ps1 | iex
インストール後、現在の PowerShell で keelson コマンドを使えるように、次を実行します。
$ env: Path = " $ env: USERPROFILE \.keelson\bin; $ env: Path "
次回以降の PowerShell でも使えるようにする インストーラーは、コマンドを探す場所（PATH）を変更しません。「環境変数を編集」からユーザー環境変数の Path に %USERPROFILE%\.keelson\bin を追加し、PowerShell を開き直してください。
続けてログインします。ブラウザが開くので、Keelson のアカウントでログインしてください。
サンプルアプリをダウンロード（ZIP） します。ZIP を展開します。
展開した keelson-hello フォルダを Claude Code / Codex / Cursor で開きます。
サンプルの中身を見る from fastapi import FastAPI, Request
from fastapi.responses import HTMLResponse
@app.get ( "/" , response_class = HTMLResponse)
def index (request: Request):
email = escape(request.headers.get( "X-Keelson-User-Email" ) or "ゲスト" )
<html lang="ja"><body style="font-family: sans-serif; padding: 2rem">
<h1>こんにちは、 { email } さん</h1>
<p>このアプリは Keelson で動いています。</p>
command : "uvicorn main:app --host 0.0.0.0 --port $PORT"
このアプリは、Keelson が付けるヘッダーからログイン中のユーザーのメールアドレスを読んで表示します。認証のコードは 1 行もありません。
Skill は、AI エージェントに Keelson のデプロイ手順を教えるものです。Keelson CLI に同梱されています。展開した keelson-hello フォルダでターミナルを開き、使っているエージェントに合わせて 1 回実行します。
keelson install-agent claude-code --global
--global を付けない場合、いま開いているプロジェクトにだけ入ります。
keelson install-agent codex
keelson install-agent cursor
配置先や更新方法は CLI コマンド を参照してください。
エージェントのチャットに次のように依頼します。
このアプリを Keelson にデプロイして
エージェントがデプロイを実行し、完了まで待ちます。初回は数分かかります。完了すると、次のようなアプリの URL が表示されます。
https://<ワークスペース>--hello.keelson.run
エージェントを使わない場合は、フォルダで keelson deploy --new を実行しても同じです。
公開 URL はアプリの作成時に発行されるため、URL が表示されただけではデプロイ成功の証拠にはなりません。画面のない環境では、デプロイの完了前にコマンドが終了し、その後デプロイが失敗することもあります。URL を開く前に、デプロイ時に表示された ID で状態を確認してください。
keelson status <deploy-id>
失敗している場合は、このコマンドで理由と次に必要な操作を確認できます。
URL を自分のブラウザで開きます。「こんにちは、… さん」と本文が表示されれば成功です。「ゲスト」と表示されても、未ログインという意味ではありません。ログイン方法によってメールアドレスを取得できない場合に表示されます
同じ URL をシークレットウィンドウ で開きます。Keelson のログイン画面になり、アプリは表示されません
これで、専用 URL とログイン保護が付いたアプリを利用できます。デプロイしたアプリは Keelson コンソール にも表示されます。
基本コンセプト Keelson では、同じワークスペースに社内アプリとメンバーをまとめて管理します。アプリを増やすたびに、ログインやメンバー管理の仕組みを作り直す必要はありません。
このページでは、基本的な用語と、Keelson が用意する機能・アプリ側で実装する機能の違いを説明します。
用語 意味 ワークスペース メンバーやアプリをまとめて管理する単位 アプリ デプロイして利用する業務ツール。案件管理や日報など メンバー ワークスペースに参加している人 グループ 部署やチームなど、アクセス権をまとめて設定するためのメンバーの集まり デプロイ アプリのコードと設定を送り、Keelson 上で使える状態にすること
たとえば、同じワークスペースに「営業日報」と「経費申請」を作り、営業チームには営業日報、全社員には経費申請を共有できます。
Web アプリや静的サイトをデプロイすると、HTTPS で保護された専用 URL が発行されます。証明書の取得や更新は Keelson が行います。
https://<ワークスペース>--<アプリ>.keelson.run
通常のアプリ画面は、URL を知っているだけでは開けません。Keelson がログインとアプリの閲覧権限を確認し、許可されたアクセスだけをアプリに渡します。
Keelson：ログイン・アプリの閲覧権限・IP 制御の条件を確認
アプリ側でログイン画面や Keelson のログインセッションを実装する必要はありません。誰がアクセスしているかは、Keelson が渡すユーザー情報で確認できます。
外部サービスからの Webhook など、ブラウザのログインを使わない呼び出しには別の設定を行います。詳しくは外部システムとの連携 を参照してください。
ユーザーは 1 回ログインすれば、同じワークスペース内で閲覧権限のあるアプリを開けます。Keelson のログインをアプリごとにやり直す必要はありません。アプリが独自の外部認証も使っている場合は、そのログインが別途必要になることがあります。
メンバーとグループはワークスペースで管理し、アプリごとにグループへ権限を割り当てます。
権限 できること 閲覧（view） アプリを開いて利用する 管理（manage） アプリをデプロイし、設定やシークレットを変更する
新しいアプリには、既定で「全員に閲覧、開発者に管理」が割り当てられます。特定のチームだけに絞る場合はチームにアプリを共有する を参照してください。
管理権限は、業務上の承認権限とは別です。 「上司だけが申請を承認できる」「担当者だけが案件を編集できる」といったルールは、ユーザーやグループの情報を使ってアプリ側で実装します。
機能 Keelson が用意すること アプリで実装すること 画面と業務処理 アプリの URL と実行環境 入力画面、集計、申請などの機能 ログインと権限 ログイン、メンバー管理、アプリを開ける人の確認 本人のデータだけ表示するなど、業務に応じた制御 データの保存 Managed SQLite、Files / Media SDK 保存先を使った読み書き API キーなどの秘密情報 シークレットの保管とアプリへの受け渡し 受け取った情報を使う外部サービスへの接続 定期実行 設定した時刻・間隔で処理を起動 1 回分の処理を行って終了するコード 運用 ログ、アプリ一覧、Managed SQLite のバックアップと復元 業務上の処理結果やエラーをログに記録すること
通常は、AI エージェントに作りたい機能を伝え、アプリのコードと Keelson の設定を作成してもらいます。
共通の API キーはワークスペースに設定し、アプリへ環境変数として渡せます。アプリごとに別の値を設定して上書きすることもできます。秘密の値をコードや keelson.yaml に直接書く必要はありません。
詳しくは環境変数とシークレット を参照してください。
keelson.yaml に db.mode: libsql と書くと、アプリ専用の Managed SQLite が用意されます。接続情報は Keelson が渡しますが、接続してデータを読み書きするコードはアプリ側に必要です。
Managed SQLite にはバックアップと復元が付きます。Files / Media のファイルは、このバックアップの対象外です。保存先の選び方はデータベース とファイルとメディア を参照してください。
毎朝の集計や定期的なデータ同期は、keelson.yaml の crons に設定します。Web アプリへのアクセスがなくても実行できます。設定方法は定期実行ジョブ を参照してください。
コンソールでは、各アプリを誰が作ったか、誰が使えるか、最後にいつ利用・デプロイされたかを確認できます。作成者以外も、アプリの管理状況を把握できます。
アクセスがない状態が続くと、Web アプリは停止します。 次のアクセスで起動するため、停止後の最初の応答には通常より時間がかかることがあります。レスポンスを返した後の処理は、最後まで実行されることが保証されません。サーバー内のローカルファイルは、再起動・再デプロイで失われます。 この性質を「揮発性」と呼びます。残したいデータは Managed SQLite、Files SDK、Media SDK などに保存してください。
実装時の注意点はアプリが動くタイミング と対応アプリと制約 を参照してください。
FAQ 対応アプリ、料金、アクセス権、データについて、導入前によくある質問をまとめました。設定や操作の詳細は、各回答のリンク先を参照してください。
構成によります。ビルド済みの HTML・CSS・JavaScript は静的サイトとして、Next.js などサーバー側の処理があるものは Web アプリとしてデプロイできます。静的サイトは手元でビルドし、外部サービスの接続先なども設定しておきます。
外部から接続できる DB やストレージは使い続けられますが、作成ツール内のデータや認証機能が自動で移るわけではありません。まず AI エージェントにコードの確認を依頼してください。詳しくは持ち込みガイド を参照してください。
はい。Keelson 専用のフレームワークで作る必要はなく、ほかのホスティングサービスや自分のサーバー、自分の PC のローカル環境でも動かせます。
動かす環境に合わせて、Python / Node.js などの実行環境や依存パッケージを用意し、起動設定やデータベースの接続先などを設定します。Keelson に任せていたログイン保護・アクセス制御・定期実行が必要な場合は、その環境で用意します。Keelson 固有の認証情報や Files / Media SDK を使っている部分は、コードの変更やデータの移行が必要です。
現在は動きません。Streamlit は WebSocket が必須で、Keelson の実行モデルと合わないためです。Gradio は検証中です。対応アプリと制約 を参照してください。
現在は未対応です。Keelson の Managed SQLite（libSQL）と Django ORM の互換性に制約があるためです。フレームワーク別の注意点 を参照してください。
いいえ。Web アプリはアクセスがない状態が続くと停止し、次のアクセスで起動します。そのため、停止後の最初の応答には通常より時間がかかることがあります。
決まった時刻の処理は定期実行ジョブに設定します。レスポンスを返した後のバックグラウンド処理は、最後まで実行されることが保証されません。詳しくはアプリが動くタイミング を参照してください。
14 日間の無料トライアルの終了後です。Starter / Plus はカード登録なしで始められ、終了までにカードを登録しなければ課金されずに終わります。Team はトライアル開始時にカード登録が要ります。料金と契約の運用 。
Plus 以上です。開発・管理する人が 2 人なら、Developers の席が 2 席必要です。利用者 50 人は App User として追加でき、その人数は料金に影響しません。
Developers の席には Owner / Admin / Developer を数えます。あわせて「同時に使えるアプリ数」（Starter 1、Plus 2、Team 4）が用途に合うかを確認してください。詳しくはプランと制限 を参照してください。
有料契約中は保存数に上限がなく、上限は「同時に動かせる数」だけです。直近 5 分にアクセスがあったアプリだけが枠を使い、使われていないアプリはスリープして枠を空けます。トライアル中だけは保有数も 3 個まで（静的サイトとしてデプロイ済みのアプリは数えません）です。プランと制限 。
同時に動かせるアプリ数の上限に達していると、スリープ中のアプリを開いた利用者には、起動できる枠が空くまで待つよう案内する画面が表示されます。枠を使っているアプリへのアクセスが約 5 分途絶えると、その枠が空きます。他のアプリが使われ続けている間は空きません。重要なアプリには優先起動 （Plus 以上）で枠を予約できます。
含まれません。アプリから外部 API を呼ぶ費用は、その API の提供元との契約です。API キーはシークレットとして設定してアプリから利用します。外部システムとの連携 。
開けません。ワークスペースのメンバーがログインし、そのアプリの閲覧権限を持っている場合だけ表示されます。ログインしていない人にはログイン画面が出ます。社外の人に見せるには、その人をメンバーとして招待します（App User は人数無制限）。認証とログイン 。
アプリとその Managed SQLite は、日本リージョンに配置されます。
※ 米国西海岸リージョンは近日リリース予定です。
Managed SQLite には、全プランでバックアップと復元が付きます。Files / Media SDK のファイルや外部 DB は、このバックアップの対象外です。
日次バックアップ、手動バックアップ、時刻を指定した復元（PITR）、ダウンロードが使えます。詳しくはデータベース を参照してください。
Managed SQLite、Files SDK、Media SDK に保存したデータは、通常の再デプロイだけでは消えません。一方、アプリが動くサーバー内のローカルファイルは、再起動・再デプロイで失われます。
DB の変更処理やアプリのコードでデータを削除・更新した場合は、その変更が反映されます。保存先の違いはデータベース 、変更を戻す方法は更新と復元 を参照してください。
どの場合も、アプリとデータがその場で消えることはありません。契約が終了すると新しいデプロイと起動がブロックされ、14 日の猶予の後に自動削除されます。猶予中に再契約すれば残ります。プランのダウングレードは請求期間の終わりに適用され、上限を超えている分は起動できなくなります。料金と契約の運用 。
アプリを作る 対応アプリと制約 Keelson は、Python・Node.js・Go の Web アプリ、静的サイト、定期実行ジョブに対応しています。
フレームワークやデータの保存方法によっては、コードや設定の変更が必要です。以下の表で対応状況を確認してください。
Dockerfile は不要です。アプリに含まれていても、Keelson のビルドには使用されません。
アプリ 対応状況 補足 Python の Web アプリ（FastAPI、Flask など） 対応 環境変数 PORT で指定されたポートで起動。Flask は gunicorn を使用 Node.js の Web アプリ（Express、Hono、Next.js など） 対応 環境変数 PORT で指定されたポートで起動。Next.js は next start Go の Web アプリ（net/http、Gin など） 対応 Keelson がビルドして ./app で起動 ビルド済みの静的サイト / SPA（React、Vue、Svelte など） 対応 assets にビルド出力を指定フロントエンド（静的）+ バックエンド API 対応 hybrid 構成。assets.api で API のパスを指定 定期実行だけ（Web UI なし） 対応 crons だけを定義外部の PostgreSQL / MySQL / libSQL に接続する 対応 db.mode: none。接続情報はシークレットで渡す外部 API（OpenAI、Slack、Google Sheets など）を呼ぶ 対応 外部通信は制限なし ファイル SQLite を使っている（sqlite3、better-sqlite3 など） 変更が必要 libSQL クライアントに置き換えて db.mode: libsql ローカルファイルにデータを保存している 変更が必要 Managed SQLite か Files SDK / Media SDK へ。ローカルディスクは再起動で消える アプリ内でタイマーやバックグラウンドスレッドを動かしている 変更が必要 リクエスト処理中に完了させるか、定期実行ジョブに移す（アプリが動くタイミング ） Django 現在未対応 Keelson の Managed SQLite（libSQL）と Django ORM の互換性に制約があるため、現在は対応していません Streamlit 未対応 WebSocket が必須のため、現在は動きません（フレームワーク別の注意点 ） Gradio 検証中 4 以上を検証中。現時点では動作を保証しません Ruby / PHP / Java / Rust / .NET / Elixir 未対応 対応ランタイムは Python / Node.js / Go のみ Dockerfile で apt パッケージを追加している 未対応 root 権限なし。画像・動画系は -media ランタイムで代替できる場合あり 常駐プロセス・デーモン・WebSocket サーバー前提 未対応 アイドル時に停止する実行モデルと合わない Redis / Kafka / DB サーバーを自前で起動する 未対応 外部サービスとして接続するのは可 GPU が必要 未対応
「変更が必要」のアプリは、コードや設定を変更して対応できる場合があります。AI エージェントに確認を依頼すると、必要な変更を提案します。
他のツールで作ったアプリ（Lovable、Bolt、v0 など）をデプロイする手順は持ち込みガイド にあります。
keelson.yaml の runtime で選びます。迷ったら -slim から始め、画像・動画・PDF 処理のライブラリ（Pillow、sharp、ffmpeg など）が必要になったら -media に切り替えます。
ランタイム 言語バージョン ビルド時の処理 python-slim / python-mediaPython 3.12 requirements.txt または pyproject.toml から自動インストールnode-slim / node-mediaNode.js 24 package.json と package-lock.json から依存を自動インストール。npm run build があれば実行go-slim / go-mediaGo 1.26 go.mod から go build し、./app として起動
Go のバージョンは、ビルドに使用するツールチェーンのバージョンです。依存パッケージはビルド時にインストールされます。command には起動コマンドだけを書きます。
Node.js: ビルドには npm を使います。pnpm-lock.yaml / yarn.lock のみの構成は対応していないため、package-lock.json を用意してください。Go: CGO_ENABLED=0 でビルドします。cgo に依存するライブラリは使用できません。
依存ファイルの要件やビルドの制約は、keelson.yaml リファレンス を参照してください。
項目 内容 OS / CPU Linux / x86_64 権限・システムパッケージ 非 root で動作します。sudo や apt-get は使えません Web サーバーの起動 0.0.0.0 と環境変数 PORT で指定されたポートで待ち受けますデータの保存 ローカルファイルは永続保存されません。残したいデータには Managed SQLite や Files / Media SDK を使います 処理の実行 リクエスト処理と定期実行ジョブに対応します。詳しくはアプリが動くタイミング を参照してください
実行時間やアプリ数などの上限はプランと制限 を参照してください。
Python（FastAPI）の例です。keelson.yaml と requirements.txt と app.py の 3 ファイルでデプロイできます。
from fastapi import FastAPI
return { "message" : "Hello from Keelson" }
if __name__ == "__main__" :
uvicorn.run(app, host = "0.0.0.0" , port = int (os.environ[ "PORT" ]))
通常は AI エージェントが keelson.yaml を書くので、自分で作る必要はありません。
アプリが動くタイミング Keelson は、アクセスに応じて Web アプリを起動し、アクセスがない状態が続くと停止します。次のアクセスがあると、再び起動します。
画面表示や API の処理はリクエストを受けて実行し、毎日の集計などは Keelson の定期実行ジョブで実行します。アプリが常に起動していることを前提にした処理には対応していません。
アプリが停止しているときにリクエストを受けると、Keelson がアプリを起動します。このため、停止後の最初のアクセスでは、通常より応答に時間がかかることがあります。
再起動すると、メモリ上の変数やローカルファイルに保存したデータは引き継がれません。残しておきたいデータは、Managed SQLite や Files / Media SDK に保存してください。
詳しくはデータベース（Managed SQLite） とファイルとメディア を参照してください。
データの保存や外部 API の呼び出しなど、そのリクエストで必要な処理は、レスポンスを返すまでに完了させてください。
レスポンスを返した後にバックグラウンドで続ける処理は、最後まで実行されることが保証されません。FastAPI の BackgroundTasks や、完了を待たずに開始する非同期処理を使う場合は、処理方法の変更が必要です。
AI の回答生成など、結果を少しずつ返す処理にはストリーミングを利用できます。ただし、接続が切れた後も処理を続ける仕組みとしては利用できません。
毎朝のレポート作成や定期的なデータ同期は、keelson.yaml の crons に設定します。Web アプリにアクセスがなくても、設定したスケジュールに従って実行されます。
ジョブは Web アプリとは別の実行環境で起動し、指定したコマンドの処理が終わると終了します。Web アプリと共有するデータは、データベースなどに保存してください。
アプリ内のタイマーやスケジューラで時刻を待つ方法は、アプリの停止中には動作しません。定期的な処理は Keelson の定期実行ジョブに設定してください。
設定方法は定期実行ジョブ を参照してください。
やりたいこと 実装方法 フォームの内容を保存する リクエスト処理中に保存し、結果を返す AI の回答を順次表示する リクエスト処理中にストリーミングで返す 毎朝レポートを作成する 定期実行ジョブに設定する 外部サービスと定期的に同期する 1 回分の同期処理を定期実行ジョブで実行する 受け付けた処理を後でまとめて実行する 未処理の内容を DB に保存し、定期実行ジョブで処理する
DB に保存して後で処理する方法では、次のジョブ実行まで待ち時間が発生します。すぐに開始する必要がある処理には適していません。また、処理の重複や失敗に備える必要があります。詳しくは定期実行ジョブの設計 を参照してください。
Keelson は、任意のバックグラウンド処理を即座に開始するタスク実行 API や、常駐ワーカーを提供していません。
ここまでの説明は、サーバー側の処理が対象です。ブラウザ側のタイマーや画面の自動更新に、この制約は適用されません。
HTTP リクエストと定期実行ジョブには、それぞれ実行時間の上限があります。長い処理は、上限内に完了する単位に分けてください。
詳細はプランと制限 と定期実行ジョブ を参照してください。
他のツールで作ったアプリを持ち込む Lovable、Bolt、v0 などで作ったアプリや、手元で開発したアプリも、ソースコードがあれば Keelson へのデプロイを検討できます。対応できるかどうかは、使ったツールの名前ではなく、アプリの言語やデータの保存方法で決まります。
まず AI エージェントにコードを確認してもらい、必要な変更を確認してからデプロイします。外部サービスにあるデータや利用者のアカウントは、コードをデプロイしただけでは Keelson に移りません。
作成したツールからコードをエクスポートするか、Git リポジトリを手元に取得し、アプリのフォルダを AI エージェントで開きます。
Keelson CLI とエージェント用の Skill の準備、Keelson へのログインがまだの場合は、クイックスタート を先に進めてください。
次のように依頼してください。
このアプリを Keelson にデプロイしたいです。コードを確認し、対応できるかと必要な変更を説明してください。データベース、ログイン、ファイルの保存先、定期的な処理を確認し、既存のデータや利用者のアクセス権に影響する変更は、実施前に説明してください。
エージェントが確認するのは、主に次の点です。
確認すること 確認する理由 アプリの言語とフレームワーク Keelson の対応範囲と、起動・ビルド方法を確認するため データの保存先 外部 DB を使い続けるか、Managed SQLite に変更するかを判断するため ログインとアクセス権 既存の利用者が自分のデータを引き続き使えるようにするため ファイルの保存先 再起動で消える保存方法になっていないかを確認するため タイマーやバックグラウンド処理 リクエスト処理や Keelson の定期実行ジョブに変更する必要があるかを確認するため
対応している言語・フレームワークは対応アプリと制約 、処理の実行方法はアプリが動くタイミング にまとめています。
アプリから接続できる外部サービスは、デプロイ後も使い続けられます。この場合、データを移す必要はありません。たとえば、外部 DB を使うアプリは db.mode: none にし、接続情報を設定します。
サーバー側で使う API キーやパスワードはシークレット で渡します。ブラウザ側で使うサービスの URL や公開用のキーは、そのサービスの案内に従って設定してください。秘密の値をブラウザに送るコードへ埋め込まないでください。
Supabase などをブラウザから直接呼ぶ構成では、外部サービス側のアクセス権設定も引き続き必要です。Keelson のログインでアプリを保護しても、外部サービスのデータ権限が自動で置き換わるわけではありません。
Keelson では、アプリを開くときに Keelson のログインが必要です。元のログイン機能を残すと、利用者は両方にログインすることになります。
元のログインを外せるかどうかは、ユーザーの識別やデータのアクセス権に使っているかで判断します。
元のログインの役割 対応方法 アプリを開く人を制限するためだけに使っている Keelson のログインとアプリのアクセス権に置き換えることを検討できます ユーザーごとに見せるデータを制限している 元の認証を残すか、Keelson のユーザー情報を使って権限を判定するように変更します データに元のサービスのユーザー ID を保存している 既存のユーザーと Keelson のユーザーをどう対応付けるかを決めます
たとえば Supabase の RLS（行ごとのアクセス制御）で auth.uid() を使っている場合、ログイン機能だけを外すと、誰のデータかを判定できなくなります。ログイン画面を削除する前に、データへのアクセス方法を確認してください。
アプリが動くサーバー内のファイルは、再起動・再デプロイで失われます。残したいものに合わせて保存方法を変更します。
保存先を変更する場合は、コードの変更に加えて、既存データを移す手順もエージェントに確認してください。
変更内容を確認したら、エージェントに依頼します。
確認した内容で必要な変更と keelson.yaml の作成を行い、このアプリを Keelson にデプロイしてください。
エージェントはアプリの構成に合わせて設定を作成します。主な構成は次のとおりです。設定を自分で書く必要はありません。
アプリの構成 デプロイ方法 静的サイト / SPA（ビルド済みの HTML・CSS・JavaScript） ビルドしたファイルを assets に指定して配信します。外部サービスの API をブラウザから呼ぶアプリも含みます サーバー側の処理がある Web アプリ（Next.js、Express、FastAPI など） command で Web サーバーを起動します静的な画面と API サーバーを組み合わせたアプリ assets と command を設定し、assets.api で API のパスを指定します（ハイブリッド構成）
設定の読み方は keelson.yaml の設定 、操作手順はデプロイする を参照してください。
静的サイトは、手元でビルドしてからデプロイします。Keelson にアップロードされるのは assets.dir の中身と keelson.yaml で、Keelson 上で npm install や npm run build は実行されません。
ビルド時に読み込むサービスの URL や公開用のキーは、ビルド前に設定します。デプロイ後にサーバーの環境変数を設定しても、ビルド済みの画面には反映されません。エージェントには、設定を含めてビルドとデプロイを依頼してください。
Keelson の URL で画面が開き、必要な操作ができる
既存のデータが表示され、追加・更新したデータも保存される
画像や添付ファイルを表示・閲覧できる
元の認証を残した場合も含め、想定したログイン手順で利用できる
他のメンバーも利用でき、見せるべきでないデータは表示されない
作成ツールが提供するデータベース、認証、ファイル保存、サーバー側の関数は、ソースコードだけをデプロイしても移りません。外部から利用できるものは接続を維持し、利用できないものはデータの移行や処理の書き換えが必要です。
作成ツール内の編集機能も Keelson には移りません。デプロイ後のコード変更は、手元の AI エージェントなどで行い、再デプロイして反映します。
keelson.yaml の設定 keelson.yaml は、アプリの起動方法やデータベースの利用、定期実行などを Keelson に伝える設定ファイルです。アプリのソースコードと同じフォルダの一番上（プロジェクトルート）に置きます。
通常は、デプロイを依頼した AI エージェントが作成・更新します。 このページでは、エージェントが作った設定を確認するときに役立つ項目を説明します。すべての設定項目や細かい条件は keelson.yaml リファレンス を参照してください。
Python の Web アプリで、Keelson のデータベースを使う例です。
runtime : python-slim # Python の実行環境
command : "python app.py" # Web サーバーを起動するコマンド
mode : libsql # Keelson の Managed SQLite を使う
項目 確認すること slugアプリを識別する名前です。https://<ワークスペース>--<slug>.keelson.run の一部になります runtimeアプリの言語に合う実行環境です。Python / Node.js / Go から選びます commandアプリの Web サーバーを起動するコマンドです。依存パッケージのインストールはビルド時に行われます db.modeKeelson のデータベースを使うなら 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 を追加することもできます。定期実行の設定は定期実行ジョブ を参照してください。
ビルド済みのファイルを配信する例です。assets.dir にはビルド出力のフォルダを指定します。
fallback : index.html # SPA で、画面の URL を直接開いたときにも index.html を返す
静的サイトは手元でビルドしてからデプロイします。Keelson 上で依存パッケージのインストールやビルドは行われません。通常の静的サイトで、見つからないページを index.html に戻す必要がなければ fallback は省略できます。
/api 以下へのリクエストをサーバーで処理し、それ以外ではビルド済みの画面を配信する例です。
command : "node server.js"
アプリ名と保存先が意図どおりか。 slug が対象アプリの名前か、db.mode が利用するデータベースに合っているかを確認します。API キーやパスワードが直接書かれていないか。 secrets には名前と説明だけを書き、値はコンソールなどから設定します。必要な定期処理が設定されているか。 アプリ内のタイマーに任せず、crons のスケジュールを確認します。
起動コマンドや依存ファイルの確認は、エージェントに依頼できます。次のコマンドでは、アップロードせずに設定と送信対象のファイルを確認できます。
keelson deploy --check --json
この確認だけでは、実際にアプリが起動するかやプランの上限内かまでは分かりません。デプロイ後はアプリの URL を開き、動作を確認してください。
keelson.yaml の変更は、次のデプロイで反映されます。エージェントに「設定を変更して再デプロイしてください」と依頼してください。
PORT など Keelson が設定する環境変数や、廃止された設定項目は自分で追加する必要はありません。古い設定を引き継ぐ場合や検証エラーが出た場合は、keelson.yaml リファレンス を参照してください。
データベース（Managed SQLite） 顧客情報、案件、申請内容など、アプリで登録・検索・更新するデータには Managed SQLite を使います。Keelson がアプリ専用に用意するデータベースで、保存したデータはアプリを再起動・再デプロイしても残ります。
画像や設定ファイルにも、再起動後に残せる保存先があります。保存したいものと用途で選びます。
保存したいもの・用途 保存先 顧客情報、案件、申請などを登録・検索・更新する Managed SQLite 設定ファイルや処理済みデータの記録を、アプリ内部で読み書きする Files SDK 画像を画面に表示する、PDF や添付ファイルを利用者が開く Media SDK
たとえば案件管理アプリなら、案件名や担当者は DB に、添付 PDF は Media に保存します。DB には添付ファイルの ID も記録し、案件とファイルを関連付けます。
ファイルの保存方法はファイルとメディア を参照してください。
ここでいう「ローカルファイル」は、Keelson 上でアプリが動くサーバー内に書き込むファイル です。アプリを再起動・再デプロイしたり、アクセスがなくなって停止したりすると、そのファイルは失われます。この性質を「揮発性」と呼びます。
./data.db、/tmp/data.db、/data/main.db のように保存先のフォルダを変えても、再起動後にデータを残すことはできません。定期実行ジョブは Web アプリとは別の環境で動くため、これらのファイルを共有することもできません。
アップロードの受け取りや変換途中のファイルなど、処理中だけ使う一時ファイルは /tmp に置いて構いません。後で必要になるデータは、上の表の保存先に保存してください。
sqlite3 や better-sqlite3 でファイルに保存している場合は、Managed SQLite に接続するコードへ変更します。AI エージェントに、次のように依頼できます。
このアプリのデータが、Keelson で再起動・再デプロイした後も残るようにしてください。ファイル SQLite を使っている箇所を確認し、Managed SQLite への変更と、既存データの移し方を説明してください。
ファイル SQLite を使うコードはデプロイ時に検出され、宣言がなければ拒否されます。再生成できるキャッシュ用途に限り、db.local_sqlite で一時ファイルの利用を宣言できます。この設定でもファイルは再起動後に残りません。詳しくはリファレンス を参照してください。
keelson.yaml に次の設定を書くと、アプリ専用のデータベースが用意されます。通常は AI エージェントが設定と接続コードを作成します。
DB サーバーの準備は不要です。 接続 URL と認証トークンは、Keelson がアプリの環境変数に設定します。アプリごとにデータを分けます。 接続用の認証情報でアクセスできるのは、そのアプリの DB だけです。保存を確定したデータは再起動後も残ります。 SQL のコミットが完了した時点で保存されます。日本リージョンに配置されます。 米国西海岸リージョンは近日リリース予定です。バックアップから戻せます。 日次バックアップ、手動バックアップ、指定時刻への復元に対応しています。
設定ファイルの変更に加えて、アプリ側も libSQL クライアントで DB に接続する必要があります。SQL は SQLite と同じように書けますが、ローカルのファイルパスではなく、Keelson が渡す接続 URL と認証トークンを使います。対応クライアントは Python・Node.js・Go で利用できます。
以下はテーブルを作り、データを 1 件保存する例です。Python は libsql、Node.js は @libsql/client を依存パッケージに追加します。
database = os.environ[ "KEELSON_DB_URL" ],
auth_token = os.environ[ "KEELSON_DB_AUTH_TOKEN" ],
CREATE TABLE IF NOT EXISTS items (
id INTEGER PRIMARY KEY AUTOINCREMENT,
created_at TEXT DEFAULT CURRENT_TIMESTAMP
conn.execute( "INSERT INTO items (name) VALUES (?)" , ( "サンプル" ,))
import { createClient } from "@libsql/client" ;
const db = createClient ({
url: process.env. KEELSON_DB_URL ,
authToken: process.env. KEELSON_DB_AUTH_TOKEN ,
CREATE TABLE IF NOT EXISTS items (
id INTEGER PRIMARY KEY AUTOINCREMENT,
created_at TEXT DEFAULT CURRENT_TIMESTAMP
await db. execute ({ sql: "INSERT INTO items (name) VALUES (?)" , args: [ "サンプル" ] });
顧客名や案件名など、何を保存するかを定義したものを「スキーマ」と呼びます。テーブルがまだなければ、上の例のように CREATE TABLE IF NOT EXISTS で作成できます。
デプロイに合わせてテーブルや列を変更する場合は、db.migrate に変更用のコマンドを書きます。この処理を「マイグレーション」と呼びます。
migrate : "python migrate.py"
db.migrate は新しいコードに切り替える前に実行されます。失敗した場合は、それまでのコードでアプリの提供を続けます。ただし、DB に加えた変更は自動では戻りません。
同じコマンドがデプロイのたびに実行されても結果が壊れないようにし（冪等性）、それまでのコードでも読み書きできる変更にしてください。詳しくは更新と復元 を参照してください。
SQLite は、同時に書き込みを行う処理を 1 つずつ実行します。Web アプリと定期実行ジョブなどが同時に書き込むと、待ち時間が発生することがあります。書き込みが集中し、応答時間に影響する場合は、処理の見直しや外部の PostgreSQL などを検討してください。
すでに使っている PostgreSQL、MySQL、外部の libSQL などに接続する場合は、db.mode: none にします。接続情報は自分で用意し、シークレットとして設定してください。この設定で Keelson が外部 DB を作成したり、既存のデータを移したりすることはありません。
description : "PostgreSQL の接続文字列"
Django は現在未対応です。詳しくはフレームワーク別の注意点 を参照してください。
外部 DB を使う主なケースです。
ケース 選択肢 データ量や必要な処理速度が Managed SQLite では対応できない 外部 PostgreSQL 同時書き込みが非常に多い PostgreSQL、MySQL BI ツールや基幹システムから直接参照する 共有の PostgreSQL、データウェアハウス Keelson のプランより長い期間のバックアップが必要 外部のマネージド DB
誤ってデータを削除・更新した場合に備えて、すべてのプランでバックアップと復元を利用できます。
方法 用途 日次バックアップ 毎日自動で保存されるバックアップから戻す 手動スナップショット 大きな変更の前など、必要なタイミングでバックアップを作る（1 アプリ 1 日 5 回まで） 時刻復元（PITR） 戻せる期間内の時刻を指定し、その時点のデータに戻す ダウンロード バックアップや指定時刻のデータを手元に保存する
Starter Plus Team 日次バックアップの保存数 1 回分 3 回分 7 回分 時刻を指定して戻せる期間 過去 24 時間 過去 7 日 過去 14 日
コンソールのアプリ画面で「復元ポイント」を開き、タイムライン上のバックアップや時刻を選ぶと、復元やダウンロードができます。
復元はアプリ単位で、他のアプリには影響しません。復元前の状態は 72 時間保持され、その間は復元を取り消せます。復元の実行には、ブラウザでの承認が必要です。
このバックアップで戻せるのは Managed SQLite のデータだけ です。Files / Media SDK のファイル、外部 DB、アプリのコードや設定は対象外です。
たとえば、DB に保存した添付ファイルの ID を復元しても、Media から削除済みのファイル本体は戻りません。コードや設定を含めた変更の戻し方は更新と復元 を参照してください。
Managed SQLite にはプランごとの固定上限はありません。ただし、基盤側の技術上限は適用されます。また、平常の業務利用を著しく超える負荷や、プラットフォームの安定運用・他のお客様の利用・当社の合理的な運用コストに影響を及ぼす利用を検知した場合、アプリの実行を制限または停止することがあります。緊急時は事前の通知なく制限することがあります
ワークスペースのストレージ（Files / Media SDK のファイル、スナップショット、デプロイ用ファイルなどの合計）はプランごとに上限があります。DB の容量はこれとは別枠です
プラン別の制限はプランと制限 を参照してください。
ファイルとメディア アプリの再起動・再デプロイ後も残したいファイルは、Files SDK または Media SDK で保存します。SDK は、アプリのコードから保存・読み取りなどを行うためのライブラリです。
アプリ内部で読み書きするファイルには Files、画面に表示したり利用者が開いたりするファイルには Media を使います。 Media に保存すると、ブラウザから直接開ける URL を使えるため、画像表示や添付ファイルの閲覧に適しています。
Files SDK Media SDK 主な用途 アプリ内部の処理に使うファイルを保存・更新する 利用者に画像を見せる、PDF や添付ファイルを開いてもらう 例 設定 JSON、処理済み URL の一覧、中間集計ファイル 商品写真、申請書 PDF、利用者向けのレポート 読み取り方 サーバー側のコードが SDK で読み取る。配信用 URL は付かない サーバー側のコードで読み取れるほか、ブラウザから URL で開ける 更新方法 同じ名前（キー）で上書きできる。更新頻度の目安は 1 キーにつき 1 秒に 1 回程度 上書きせず、新しいファイルとして保存するたびに ID が付く 1 ファイルの上限 10 MiB 50 MiB
ファイル形式だけで決める必要はありません。たとえば CSV でも、アプリ内部で集計に使うなら Files、利用者に渡すレポートなら Media が適しています。
Media の URL は誰でも開ける公開 URL ではありません。そのアプリを閲覧できるメンバーだけが、Keelson にログインして開けます。 Files も Media も、利用には keelson.yaml への追加設定は不要です。
アプリが動くサーバー内のファイルは、再起動・再デプロイで失われます。この性質を「揮発性」と呼びます。/tmp や /data に書くだけでは、後で使うファイルを残せません。
Files / Media SDK で保存が完了すると、ファイルはアプリの再起動後も残ります。後から同期処理を行う必要はありません。顧客情報や案件など、項目ごとに検索・更新するデータには Managed SQLite を使ってください。
必要な SDK をアプリの依存パッケージに追加します。以下のコード例はサーバー側で実行します。通常は AI エージェントに、保存したいファイルと用途を伝えて実装を依頼できます。
言語 パッケージ Node.js npm install @keelsonhq/files @keelsonhq/mediaPython pip install keelson-sdk（from keelson import files, media）Go go get github.com/keelsonhq/go-sdk（.../go-sdk/files、.../go-sdk/media）
Files は、アプリが名前を付けて保存し、必要に応じて同じ名前で更新するファイルに向いています。Web アプリと定期実行ジョブの間で、保存したファイルを共有できます。
保存先の名前を「キー」と呼びます。settings.json や reports/2026-08.csv のように指定します。主な操作は、保存する write、読み取る read、削除する delete、キーの一覧を取得する list です。read はファイルがなければ null / None を返します。
次は、設定を保存して読み取り、レポートの一覧取得と削除を行う例です。
import * as files from "@keelsonhq/files" ;
await files. write ( "settings.json" , JSON . stringify ({ theme: "dark" }));
const raw = await files. read ( "settings.json" ); // Uint8Array | null
const settings = raw ? JSON . parse ( new TextDecoder (). decode (raw)) : {};
const keys = await files. list ( "reports/" ); // ["reports/2026-08.csv", ...]
await files. delete ( "reports/2026-07.csv" );
from keelson import files
files.write( "settings.json" , json.dumps({ "theme" : "dark" }))
settings = json.loads(files.read( "settings.json" ) or " {} " ) # read() -> bytes | None
keys = files.list( "reports/" )
files.delete( "reports/2026-07.csv" )
ローカルファイルから移す場合は、書き込みと読み取りの両方を SDK に変更します。Files には配信用 URL がないため、保存したファイルを利用者に渡したい場合は、アプリ側にダウンロード処理を実装するか、Media を使ってください。
Media は、アプリの画面で見せる画像や、利用者が開く PDF・添付ファイルに向いています。保存したファイルを Keelson が URL で配信するため、アプリ側にファイル配信用の処理を書く必要はありません。
サーバー側のコードで put を呼び、ファイルを保存します。
返されたファイル ID を、案件や商品などのデータと一緒に DB に記録します。
url(id) で URL を取得し、画面の画像やリンクに設定します。ブラウザがその URL にアクセスすると、Keelson が認証を確認してファイルを返します。
画像を保存するサーバー側の関数の例です。引数には、アップロードで受け取った画像データを渡します。
import * as media from "@keelsonhq/media" ;
async function savePhoto ( imageBytes ) {
const id = await media. put (imageBytes, {
contentType: "image/png" ,
// id を DB に記録し、url を画面に返します。
return { id, url: media. url (id) };
from keelson import media
def save_photo (image_bytes):
content_type = "image/png" ,
# file_id を DB に記録し、url を画面に返します。
return { "id" : file_id, "url" : media.url(file_id)}
Keelson 上での URL は /__keelson/media/<ファイルID> という形式です。たとえば、画像の URL を <img> の src に、PDF の URL をリンクの href に設定します。
<!-- 保存したファイルの URL を設定する例 -->
< img src = "/__keelson/media/画像のファイルID" alt = "商品の写真" />
< a href = "/__keelson/media/PDFのファイルID" >申請書を開く</ a >
ファイルの読み取りは Keelson が処理します。URL を知っているだけでは開けず、そのアプリの閲覧権限が必要です。
保存済みのファイルは上書きできません。差し替える場合は新しいファイルを保存し、DB に記録した ID を更新します。不要になった古いファイルは別途削除してください。
サーバー側で中身を読み取るには get(id)、種類（Content-Type）とサイズを調べるには stat(id) を使います。
存在確認は exists(id)、削除は Node.js では del(id)、Python では delete(id) です。
Content-Type を省略すると、ファイル名の拡張子から決まります。
手元で開発するときは、Keelson の接続設定がなければ、どちらの SDK もローカルのフォルダにファイルを保存します。手元のファイルが、デプロイ時に Keelson の Files / Media に自動で移されるわけではありません。
Files: ./.keelson/files/ 配下に実ファイルとして書きます。.keelson/ を .gitignore に入れてください
Media: ./media/ 配下に書きます（MEDIA_DIR で変更可）
Keelson 上では、必要な環境変数を Keelson が設定します。
Media のローカルモードでは、URL の既定値は /media/<ファイルID> です。ブラウザで表示を確認するには、開発用サーバーにファイルを返す処理を用意してください。media.url() は URL を返す関数で、ローカルの HTTP 配信を開始するものではありません。
Files SDK のローカルモードは OS によって条件が違います。確実に動くのは Linux（WSL2 や Linux の devcontainer を含む）です。
SDK Linux macOS Windows Node.js 動く 標準では動かない。KEELSON_FILES_ALLOW_BESTEFFORT_LOCAL=1 で試験的に有効化できるが、環境によっては書き込みに失敗する 動かない Python 動く 動く 動かない（POSIX 専用の API を使うため） Go 動く 動く 動く
Node.js を macOS / Windows で使う場合や、Python を Windows で使う場合は、Linux の開発環境（devcontainer や WSL2）を利用してください。Media SDK のローカルモードにこの OS 制限はありません。
コンソールや CLI には、アプリのファイルを一覧表示・ダウンロード・差し替える機能はありません。利用者向けのファイル一覧はアプリに用意します。Media は保存した ID から閲覧用リンクを作り、Files は必要に応じてダウンロード処理を実装してください。
上限を超える大容量ファイルは、S3 互換などの外部オブジェクトストレージにアプリから直接保存してください（外部通信に制限はありません）
Files / Media のファイルはワークスペースのストレージ容量（プランと制限 ）に含まれます。
Managed SQLite のバックアップには、Files / Media のファイル本体は含まれません。DB を復元しても、削除したファイルは戻りません。
定期実行ジョブ 毎朝のレポート作成や、1 時間ごとのデータ同期など、決まった時刻・間隔で処理を動かせます。この処理を「定期実行ジョブ」と呼びます。Web アプリへのアクセスがなくても実行されます。
通常は AI エージェントに、実行したい処理とスケジュールを伝えると、keelson.yaml の crons に設定します。
毎朝 9 時に売上を集計する定期実行ジョブを追加してください。実行結果をログで確認できるようにしてください。
Web アプリに、毎日 9 時に report.py を実行するジョブを追加した例です。
schedule : "0 9 * * *" # 毎日 9:00
command : "python report.py"
timeout : 120 # 1 回の実行を最大 120 秒にする
項目 意味 nameジョブの名前。小文字英数字とハイフンで指定します schedule実行する時刻・間隔を表す cron 式 command1 回分の処理を実行し、終了するコマンド timeout1 回の実行時間の上限（秒）。上限に達すると停止します enabledfalse にすると定期実行を止めます。省略時は true です
name、schedule、command は必須です。timeout は 1〜600 秒の範囲で、プランの上限以下を指定してください。省略時は 300 秒ですが、プランの上限がそれより短ければ、その上限が適用されます。上限を超える値を明示すると、デプロイは拒否されます。
Web アプリなしで、定期実行だけのアプリも作れます。その場合はトップレベルの command を省略します。定期実行だけのアプリは「同時に使えるアプリ数」の枠を消費しません。
schedule には、時刻や間隔を 5 つの項目で表す「cron 式」を書きます。
やりたいこと cron 式 毎日 9:00 0 9 * * *平日 9:00 0 9 * * 1-5毎時 0 分 0 * * * *15 分ごと（Plus / Team） */15 * * * *5 分ごと（Team） */5 * * * *毎月 1 日 0:00 0 0 1 * *
スケジュールはワークスペースのタイムゾーン で評価されます。タイムゾーンはワークスペース作成時にブラウザから設定され、後から変更できません。実行開始は予定時刻より遅れることがあります。
最小間隔は Starter 60 分 / Plus 15 分 / Team 5 分です。それより短いスケジュールはデプロイ時に拒否されます。毎分の実行には対応していません。
cron 式の各項目
│ │ │ │ ┌───── 曜日（0–6、0=日曜）
* はすべての値を表します。たとえば 0 9 * * * は「毎月・毎日・すべての曜日の 9 時 0 分」です。
コンソールのアプリ画面で、ジョブごとの実行履歴、成功・失敗、ログを確認できます。「今すぐ実行」で、次の予定時刻を待たずに動作を確認することもできます。
失敗した場合はログを確認し、必要なシークレットや設定値がそろっているか、timeout 内に処理が終わるかを調べます。ログを AI エージェントに渡して、原因の調査と修正を依頼できます。
標準出力・標準エラーのログは、1 回あたり 256 KiB まで記録されます。超えた分は省略されます。
実際に開始した実行を数えます。成功・失敗・「今すぐ実行」は含み、スキップされた回は含みません。プランの上限に達すると当月の残りの実行はスキップされ、翌月にリセットされます。
本数・実行時間・月間実行回数の上限はプランと制限 を参照してください。
定期実行ジョブは、1 回分の処理を行って終了します。アプリを動かし続けるための機能ではありません。
項目 動作 Web アプリとの関係 別の実行環境で動きます。メモリやローカルファイルは共有しません データの保存 実行環境内のファイルは次回に引き継がれません。残したいデータは Managed SQLite や Files / Media SDK に保存します 前回の実行が終わっていない場合 同じジョブの次の実行をスキップします。後で実行するための予約は残りません 実行に失敗した場合 自動ですぐに再試行はしません。次の予定時刻には通常どおり実行します 実行時間の上限に達した場合 処理の途中でも停止します
アプリ内のタイマーやスケジューラは、アプリが停止している間には動作しません。決まった時刻の処理には crons を使ってください。レスポンスを返した後のバックグラウンド処理も、完了が保証されません。リクエスト内で完了させるか、後述の方法で定期実行に移します。
詳しくはアプリが動くタイミング を参照してください。
途中で停止した処理を次回やり直したり、「今すぐ実行」で同じ処理を繰り返したりしても、登録や送信が重複しないようにします。この性質を「冪等性」と呼びます。
たとえば、日付が一意の reports テーブルに集計結果を保存するなら、同じ日付のデータがあれば更新します。
INSERT INTO reports (date, total) VALUES (?, ?)
ON CONFLICT(date) DO UPDATE SET total = excluded.total
Web アプリで受け付けた処理を後でまとめて実行する場合は、未処理の内容を Managed SQLite に保存します。定期実行ジョブが未処理のデータを読み取り、処理してから完了を記録します。
command : "python process_pending.py"
開始までの待ち時間を考慮します。 次のジョブ実行まで待つため、すぐに開始する必要がある用途には適していません。利用者にも待ち時間を案内してください。同じ処理が繰り返される場合に備えます。 メール送信などが成功しても、完了を DB に記録する前にジョブが止まることがあります。失敗の回数と理由を記録します。 再試行の上限を設け、繰り返し失敗するデータをどう扱うか決めてください。Keelson が個々の未処理データを自動で再試行・隔離するわけではありません。
リクエスト内で完了できる短い処理は、レスポンスを返す前に済ませてください。
大量のデータを処理するときは、1 回の件数に上限を設け、残りは次回に処理します。実行時間の上限を超える処理は、複数回に分けてください。
外部 API を呼ぶ場合は、相手のサービスが定める呼び出し回数の制限にも合わせます。間隔を広げるか、1 回あたりの呼び出し回数を減らしてください。
sales と reports テーブルが作成済みの例です。集計対象の日付はアプリ側で決めます。スケジュールのタイムゾーンと、コードで日付を求める際のタイムゾーンは区別してください。
import os, datetime, libsql
database = os.environ[ "KEELSON_DB_URL" ],
auth_token = os.environ[ "KEELSON_DB_AUTH_TOKEN" ],
today = datetime.date.today().isoformat()
"SELECT COUNT(*), COALESCE(SUM(amount), 0) FROM sales WHERE date = ?" , (today,)
"INSERT INTO reports (date, count, total) VALUES (?, ?, ?) "
"ON CONFLICT(date) DO UPDATE SET count = excluded.count, total = excluded.total" ,
print ( f "集計完了: { today } { row[ 0 ] } 件 / { row[ 1 ] } " )
import { createClient } from "@libsql/client" ;
const db = createClient ({
url: process.env. KEELSON_DB_URL ,
authToken: process.env. KEELSON_DB_AUTH_TOKEN ,
const res = await fetch (process.env. SYNC_API_URL );
if ( ! res.ok) throw new Error ( `同期先 API のエラー: ${ res . status }` );
const items = await res. json ();
for ( const item of items) {
sql: `INSERT INTO synced_items (id, data) VALUES (?, ?)
ON CONFLICT(id) DO UPDATE SET data = excluded.data` ,
args: [item.id, JSON . stringify (item)],
console. log ( `同期完了: ${ items . length } 件` );
通知処理を notify.py に実装した場合の設定例です。Webhook URL はシークレットで渡します。
- name : SLACK_WEBHOOK_URL
description : "通知先の Slack Incoming Webhook"
- all_of : [ SLACK_WEBHOOK_URL ]
command : "python notify.py"
状況 対処 timeout に 600 秒を超える値、またはプラン上限を超える値を指定した上限以下にし、必要なら処理を分割する スケジュールがプランの最小間隔より短い 間隔を広げる ジョブの本数がプラン上限を超えている 処理をまとめるか、不要なジョブを削除する type: web と crons を併用している定期実行だけなら type を外す。静的サイトに処理を追加する場合は、サーバーを持つ構成への変更も確認する 廃止された workers: が残っている 削除し、処理に応じて crons かリクエスト処理に変更する
イベント発生後、すぐに開始する必要がある処理。定期実行では次の予定時刻まで待ちます。
分割できず、1 回の実行時間の上限を超える処理。
ジョブの完了を待って別のジョブを開始するなどの、ワークフロー制御。
ログイン中のユーザー情報を使う Keelson がログインと、アプリを開ける人の確認を行います。アプリでは、そのユーザー情報を使って、作成者を記録したり、本人のデータだけを表示したりできます。
「誰がどの申請を承認できるか」など、アプリ内の業務ルールはアプリ側で実装します。用途に応じて、次の 3 つの方法を使い分けます。
やりたいこと 使うもの 追加設定 誰がアクセスしているか知りたい（作成者の記録、自分のデータだけ表示） ヘッダー X-Keelson-User-Id / -Email / -Name 不要 アプリの運用者（デプロイ・設定変更ができる人）だけに見せる画面を作りたい ヘッダー X-Keelson-User-App-Perms 不要（権限はコンソールで設定） 部署ごと・役職ごとの分岐、承認者の判定 Identity SDK の attributes.groups keelson apps directory enable
「上司だけが承認できる」のような業務上の権限は、アプリ管理用の manage ではなく、所属グループ、またはアプリ自身のデータ（担当者テーブルなど）で判断します。manage を持つのはアプリをデプロイ・設定できる人であり、業務上の承認者と一致するとは限りません。
Keelson は、ログイン済みユーザーからのリクエストに、ユーザー情報をヘッダー（リクエストに付く付加情報）として渡します。アプリのサーバー側で読み取れます。
ヘッダー 内容 X-Keelson-User-Idユーザー ID（安定した識別子。DB に保存するならこれ） X-Keelson-User-Emailメールアドレス（Keelson に値がなければ空文字） X-Keelson-User-Name表示名（Keelson に値がなければ空文字）
作成者を記録するなら、データの保存時にユーザー ID も記録します。本人のデータだけを表示するなら、DB の検索条件にその ID を使います。ヘッダーを読み取るだけで、データの絞り込みが自動で行われるわけではありません。
user_id = request.headers.get( "X-Keelson-User-Id" )
email = request.headers.get( "X-Keelson-User-Email" )
const userId = req.headers[ "x-keelson-user-id" ];
const email = req.headers[ "x-keelson-user-email" ];
これらのユーザー情報は、Keelson がログインを確認したうえで付けます。呼び出し元が同名のヘッダーを送っても、Keelson が確認したユーザー情報に置き換えられます。アプリ側で Keelson のログインセッションを管理する必要はありません。
Identity SDK を使うと、ユーザー情報を id、email、name としてまとめて取得できます。getCurrentUser はヘッダーを読むだけで、外部への通信や Directory API の有効化は不要です。JavaScript では await を付けて呼びます。ヘッダーがない場合は例外（IdentityError）になります。
import { getCurrentUser } from "@keelsonhq/identity" ;
app. get ( "/" , async ( req , res ) => {
const user = await getCurrentUser ({ headers: req.headers }); // { id, email, name }
res. type ( "text" ). send ( `こんにちは、${ user . name ?? "ゲスト"} さん` );
アプリの権限は「閲覧（view）」と「管理（manage）」の 2 種類で、コンソールまたは CLI でグループに割り当てます（グループとアプリ権限 ）。manage はデプロイ・設定変更・シークレット編集ができる運用者の権限で、既定では Owner / Admin / Developer が持ちます。Keelson はその結果をヘッダーで渡します。
X-Keelson-User-App-Perms意味 view閲覧できる view,manage閲覧と管理ができる
アプリは manage が含まれるかだけを見ます。グループ名はコードに書きません。
// Express — ヘッダーはリクエストごとに違うので、ハンドラの中で読む
function canManage ( req ) {
const perms = (req.headers[ "x-keelson-user-app-perms" ] ?? "" ). split ( "," );
return perms. includes ( "manage" );
app. get ( "/admin" , ( req , res ) => {
if ( ! canManage (req)) return res. status ( 403 ). end ();
# FastAPI / Flask — 同じくリクエストごとに読む
def can_manage (request) -> bool :
perms = request.headers.get( "X-Keelson-User-App-Perms" , "" ).split( "," )
「経理チームだけが使えるアプリ」は権限の割り当てだけで実現でき、アプリ側のコードは要りません（チームにアプリを共有する ）。「運用者だけが設定画面を開ける」は manage の確認で実現できます。誰が manage を持つかは、コードを変えずにコンソールで変えられます。
部署ごと・役職ごとの分岐や、「承認者だけが承認できる」のような業務上の権限が必要なら、Identity SDK でユーザーの所属グループを取得します。
画面の出し分けだけでは不十分です。「本人の申請だけ見える」を実装するときは、一覧の絞り込みに加えて、API で他人の申請 ID を指定しても取得・更新できない ことをサーバー側で確認してください。判定に使うのは、ブラウザから送られた値ではなく、Keelson が付けたヘッダーや SDK の戻り値です。
アプリに Directory API の読み取りを許可し、再デプロイします。
Directory アクセスを有効にするとトークンが保存されますが、再デプロイするまでアプリには注入されません。
keelson apps directory enable
これでアプリに KEELSON_DIRECTORY_TOKEN が注入され、SDK が自動で使います。トークンはサーバー側だけで使い、ブラウザに渡さないでください。
import { getCurrentIdentity } from "@keelsonhq/identity" ;
const me = await getCurrentIdentity ({ headers: req.headers });
const groups = me.attributes?.groups ?? []; // 例: ["everyone", "developers", "経理"]
const isAccountingMember = groups. includes ( "経理" );
// この結果を使って、経理向けの操作を許可するか判断します。
from keelson_identity import get_current_identity
me = get_current_identity( headers = request.headers)
groups = me.attributes.groups if me.attributes else []
is_accounting_member = "経理" in groups
# この結果を使って、経理向けの操作を許可するか判断します。
attributes.groups に入るのはグループのキー です。
ロールに応じたシステムグループ: Owner は owners developers everyone、Admin は admins developers everyone、Developer は developers everyone、App User は everyone
そのアプリに権限が割り当てられているカスタムグループのうち、ユーザーが属するもの。アプリに割り当てていないグループは出ません
キーは変わらないので、コードに書いて判定に使えます。日本語のキー（経理）も使えます
getCurrentIdentity の戻り値には、ユーザー（id email name）、ワークスペースでのロール（workspace.role）、このアプリでの権限（app.permissions）も含まれます。
担当者の選択肢を出すなど、他のメンバーの情報が必要なときは listMembers / list_members（検索、ロール・グループで絞り込み）、getUser、listGroups が使えます。
Identity SDK は KEELSON_LOCAL_MODE=1 で、開発用のダミーユーザーを返します。ユーザー ID やメールアドレスは KEELSON_LOCAL_USER_ID / KEELSON_LOCAL_USER_EMAIL で変更できます。
ただし、ダミーユーザーは本番の権限を完全には再現しません。一般利用者には管理画面を開かせない、といった動作は、実際の権限を設定したテスト用アプリでも確認してください。
ローカルで権限を確認するときの注意点
ヘッダーを直接読むコードには、SDK のダミーは適用されません。テスト用のリクエストにヘッダーを付けるなどして確認します。
ダミーの app.permissions は常に manage,view です。KEELSON_LOCAL_WORKSPACE_ROLE=APP_USER にしても、管理権限のないユーザーの動作にはなりません。
カスタムグループは含まれません。ダミーの Owner は admins にも含まれますが、本番の Owner は admins には含まれません。
外部システムから呼ばれるパス（auth.endpoints）には X-Keelson-User-Id が付きません。そこでは Webhook の署名やアプリトークンで認証します。外部システムとの連携 を参照してください。
外部システムとの連携 OpenAI などの API を呼ぶ、外部サービスの通知を受け取る、アプリ宛てのメールを処理するなど、用途に応じて連携方法を選べます。
アプリから外部サービスへの通信に制限はありません。必要な API キーをシークレット に設定し、アプリから呼び出します。外部サービス側の契約や呼び出し回数の制限は、そのサービスの条件に従います。
一方、外部のシステムからアプリを呼ぶ場合は、既定で Keelson のログインが必要です。ブラウザでログインできないシステムから呼び出すには、以下の設定を行います。
Webhook は、外部サービスで起きた出来事をアプリに通知する仕組みです。たとえば決済完了の通知を受けて、注文の状態を更新できます。
keelson.yaml の auth.endpoints に受信先のパスとメソッドを設定します。この設定は、指定したパスをブラウザのログインなしで呼べるようにするものです。誰からの呼び出しかは、署名やアプリトークンで確認します。
パスは /api/webhooks/ または /api/external/ で始まる必要があります。
- path : /api/webhooks/stripe
指定したパスの受信処理もアプリ側に実装し、その URL を送信元のサービスに登録します。これらのリクエストには、ログインユーザーの情報（X-Keelson-User-Id）は付きません。
送信元が署名を付ける場合 （Stripe、GitHub、Slack など）: 署名シークレットを secrets で受け取り、署名を検証します送信元が署名を付けない場合 : アプリトークン（次の節）を発行し、X-Webhook-Secret ヘッダーまたは URL /api/webhooks/<token>/... で受け取ります
宣言していないパスは、これまでどおりログイン必須のままです。Webhook のために必要なパスだけを開けてください。
なお /api/webhooks/email と /api/webhooks/email-events はプラットフォーム予約のため、独自のアプリ Webhook として宣言できません。メール受信を有効にすると、下記のとおりプラットフォームが /api/webhooks/email を直接呼びます。auth.endpoints への追加は不要です。
社内の別システムやスクリプトからアプリの API を呼ぶ場合は、アプリトークンを発行します。
keelson apps tokens create --name batch-client --scope api --allowed-ip 203.0.113.0/24
トークンは keelson_... の形式で、作成時に 1 回だけ表示されます
--scope api は /api/external/ 配下、--scope webhook は /api/webhooks/ 配下に対応します--allowed-ip で送信元 IP を絞れます（CIDR、複数可）。ワークスペースやアプリの IP 制御とは別に、トークン単位で適用されます同じ設定はコンソールのアプリ画面からも行えます。keelson apps tokens list / rotate / delete でローテーションと失効ができます
呼び出し側は Authorization: Bearer keelson_... を付けて、auth.endpoints で宣言したパスを呼びます。
curl -H "Authorization: Bearer keelson_xxx" https://acme--myapp.keelson.run/api/external/status
- path : /api/external/status
- /api/external/import # メソッド指定なし = すべて
Keelson は、トークンが有効で対象アプリ・用途に合っていること、送信元 IP が許可されていること、パスとメソッドが宣言に合っていることを確認してから、アプリにリクエストを渡します。
アプリ宛てのメールを受け取り、問い合わせの登録や添付ファイルの処理に使えます。Keelson がメールを受信し、内容をアプリの受信処理に渡します。
次の設定でメール受信を有効にします。
アプリに POST /api/webhooks/email の受信処理を実装します。
デプロイ後、コンソールに表示された受信アドレスへメールを送って確認します。
メール受信にはサーバー側の処理が必要です。静的サイトだけの構成では利用できません。
既定は無効です。メールを送るだけ、または扱わないアプリでは設定しません。
デプロイに成功すると、アプリには <slug>@inbound.keelson.run というアドレスが割り当てられます。<slug> はアプリの slug です。現在の環境で実際に割り当てられたアドレスはコンソールに表示されます。
アプリに POST /api/webhooks/email を実装してください。このパスはプラットフォーム予約なので auth.endpoints には宣言しません。メールが届くと Keelson が直接呼び出します。
項目 内容 delivery_id配信を識別する ID。同じメールの再配信を判別するために使います from / to差出人と宛先 subject件名 text / html本文 attachments添付ファイルの ID、ファイル名、サイズなど
受信データの JSON 例
代表的なキーの抜粋です。追加のキーが届いても処理できるように実装してください。
"delivery_id" : "del_01JEXAMPLE" ,
"received_at" : "2026-09-04T10:15:30Z" ,
"address" : "ada@example.com"
"address" : "my-app@inbound.keelson.run"
"address" : "replies@example.com"
"subject" : "アカウントについての質問" ,
"text" : "プレーンテキスト部分の本文です。" ,
"html" : "<p>HTML 部分の本文です。</p>" ,
"envelope_to" : "my-app@inbound.keelson.run" ,
"references" : [ "<earlier-message@example.com>" ],
"filename" : "question.pdf" ,
"content_type" : "application/pdf" ,
"download_url" : "https://example.invalid/temporary-download"
受信処理では、Keelson から届いた通知かどうかを SDK で確認してから、本文や添付ファイルを処理します。確認に使う署名シークレットは、KEELSON_EMAIL_WEBHOOK_SECRET としてアプリに渡されます。
署名の検証には、JSON に変換する前の、変更を加えていないリクエスト本文を使ってください。以下の例は検証成功後に 200、検証失敗時に 401 を返します。二重処理を防ぐ方法は次の節で説明します。
Python の実装例
from fastapi import FastAPI, HTTPException, Request, Response
from keelson_email import EmailError, verify_webhook
secret = os.environ[ "KEELSON_EMAIL_WEBHOOK_SECRET" ]
@app.post ( "/api/webhooks/email" )
async def receive_email (request: Request) -> Response:
message = verify_webhook( await request.body(), request.headers, secret)
except EmailError as exc:
raise HTTPException( status_code = 401 , detail = "invalid signature" ) from exc
return Response( status_code = 200 )
Node.js の実装例
import { createServer } from "node:http" ;
import { verifyWebhook } from "@keelsonhq/email" ;
const secret = process.env. KEELSON_EMAIL_WEBHOOK_SECRET ;
if ( ! secret) throw new Error ( "KEELSON_EMAIL_WEBHOOK_SECRET is required" );
createServer ( async ( request , response ) => {
if (request.method !== "POST" || request.url !== "/api/webhooks/email" ) {
response. writeHead ( 404 ). end ();
message = await verifyWebhook (request, secret);
response. writeHead ( 401 ). end ();
response. writeHead ( 200 ). end ();
}). listen (process.env. PORT ?? 3000 );
Go の実装例
" github.com/keelsonhq/go-sdk/email "
secret := os. Getenv ( "KEELSON_EMAIL_WEBHOOK_SECRET" )
panic ( "KEELSON_EMAIL_WEBHOOK_SECRET is required" )
http. HandleFunc ( "/api/webhooks/email" , func ( w http . ResponseWriter , r * http . Request ) {
message, err := email. VerifyWebhook (r, secret)
http. Error (w, "invalid signature" , http.StatusUnauthorized)
w. WriteHeader (http.StatusOK)
if err := http. ListenAndServe ( ":" + os. Getenv ( "PORT" ), nil ); err != nil {
アプリが 200 を返す前に停止したり、応答が遅かったりすると、同じメールが再配信されることがあります（at-least-once 配信）。署名が正しくても、初めて届いたメールとは限りません。注文の登録や返信メールの送信などが二重に行われないようにしてください。
受信データの delivery_id（配信イベントでは event_id）と処理状況を DB に保存し、処理済みなら再処理せず 200 を返す
ID の保存と業務データの更新は同じトランザクションで行う
処理中に同じ ID が来たら 503 を返して再配信に回す
SDK の重複処理防止機能を使う場合
SDK には重複抑止の補助があります。Go は VerifyWebhookOnce / VerifyEventWebhookOnce に IdempotencyStore を渡します。Node.js / Python は setIdempotencyStore / set_idempotency_store で永続ストアを登録できますが、これは SDK の組み込みサーバーに効くもので、上の例のように verifyWebhook を自分で呼ぶ場合には適用されません。組み込みサーバーの既定の重複抑止はプロセス内メモリなので、再起動や複数インスタンスをまたいでは効きません。
PostgreSQL、MySQL、自前の libSQL に接続する場合は db.mode: none にし、接続情報をシークレットで渡します。詳しくはデータベース を参照してください。
Files / Media SDK の上限を超えるファイルは、S3 互換のストレージにアプリから直接保存します。認証情報はシークレットで渡します。
フレームワーク別の注意点 このページでは、フレームワークごとの本番向けの起動方法と注意点を説明します。Web サーバーは、環境変数 PORT で指定されたポートで起動してください。データベースや通信方式に制約があるフレームワークもあるため、対応アプリと制約 も確認してください。
開発サーバーは、性能やエラー画面での内部情報の表示、終了時のリクエスト処理などに問題があるため、本番向けのサーバーを使用してください。
通常の設定は AI エージェントに任せられます。このページは、起動方法を確認したいときや、デプロイ時の問題を調べるときに、自分のフレームワークの箇所を参照してください。
0.0.0.0 と環境変数 PORT で指定されたポートで待ち受ける。127.0.0.1 ではリクエストが届きません起動コマンドにインストール処理を含めない。 requirements.txt / package.json / go.mod からビルド時に入ります停止は SIGTERM → 10 秒後に SIGKILL。 処理中のリクエストは 10 秒以内に終わらせます1 vCPU。 worker 数は 1 にしますデバッグモードの既定は off。 デバッグ画面は環境変数（DB の認証トークンを含む）を表示することがあります「Keelson 上か」の判別は KEELSON_MODE。 値が keelson ならプラットフォーム上です。DEBUG をこの目的に使うとローカルで起動できなくなります
ON_KEELSON = os.environ.get( "KEELSON_MODE" ) == "keelson"
DEBUG = os.environ.get( "DEBUG" , "false" ).lower() == "true" # 既定は false
command : "uvicorn main:app --host 0.0.0.0 --port $PORT"
--reload は付けません（ファイル監視がメモリを消費し、二重起動することがあります）。worker は既定の 1 のままにします。
app.run() は開発サーバーです。gunicorn を requirements.txt に追加して起動します。
command : "gunicorn --bind 0.0.0.0:$PORT --workers 1 --threads 8 --timeout 0 --graceful-timeout 9 app:app"
app:app はモジュール名とアプリオブジェクト名に置き換えます。--graceful-timeout 9 で 10 秒の SIGTERM 猶予に収めます。
Django は現在未対応です。Keelson の Managed SQLite（libSQL）と Django ORM の互換性に制約があるためです。
ファイル SQLite を使う構成では、sqlalchemy-libsql-native を使って Managed SQLite に接続する方法があります。この方法は実験的な扱いです。接続設定の変更に加えて、モデル・クエリ・マイグレーションが動作するかを確認してください。AI エージェントに、必要な変更と互換性の確認を依頼してください。
Streamlit は WebSocket が必須のため、現在は動きません。Gradio は 4 以上を検証中です。
NODE_ENV は自動設定されません。keelson.yaml で宣言します。未設定だと Express などがスタックトレースをレスポンスに含めます。
ビルドには npm と package-lock.json を使います。pnpm-lock.yaml / yarn.lock しかない場合は、事前チェックでデプロイが止まります。package-lock.json を生成し、npm で依存のインストールとビルドが成功するかを確認してください。詳しくは依存関係のインストール を参照してください。
command : "npm start" # package.json: "start": "node server.js"
エラーハンドラでスタックを返さない
app.set("trust proxy", 1) でクライアント IP / プロトコルをエッジから受け取るセッションや JWT のシークレットは secrets で
ビルドして next start で起動します。next dev は本番用ではありません。
command : "npm run start" # package.json: "start": "next start -p $PORT"
npm run build がビルド時に自動実行されます。.next/ が生成されることを確認します"start": "next dev" になっていたら直しますKEELSON_DB_URL をサーバー側で読みます。NEXT_PUBLIC_* に入れるとブラウザに配布されます
provider = "sqlite" のままでは動きません。@prisma/adapter-libsql を @prisma/client と同じメジャーバージョンにそろえて使います（6.x で検証済み）。利用中のバージョンでクエリやマイグレーションが動作するかを、AI エージェントに確認してもらってください。
Keelson が go build -o /workspace/app . でビルドし、./app で起動します。
CGO_ENABLED=0 でビルドされます。mattn/go-sqlite3 などの cgo SQLite ドライバは使えません。Managed SQLite には純 Go の libSQL クライアントを使いますListenAndServe を放置せず、signal.NotifyContext と server.Shutdown で 10 秒以内に処理中のリクエストを処理し切りますGORM を使っている場合は database/sql + libSQL に置き換えます
Vite、Next.js の静的エクスポート、Astro などは、手元でビルドした出力を assets.dir に指定してデプロイします。command のない静的サイトでは、Keelson 上で依存パッケージのインストールやビルドは行われません。
静的サイトには type: web が必要です。dist/ を .gitignore に入れていても、assets.dir に指定していれば送信対象に含まれます。設定例は keelson.yaml の設定 を参照してください。
デプロイと運用 デプロイする 作ったアプリを Keelson で使えるようにする操作を「デプロイ」と呼びます。初めてアプリを使うときや、変更した内容を反映するときに行います。通常は AI エージェントに依頼できます。
対応している アプリのソースコードアプリのフォルダに置く設定ファイル keelson.yaml（なければ AI エージェントに作成を依頼できます）
Keelson CLI のインストールとログイン（クイックスタート ）
アプリが必要とする API キーなどの値（環境変数とシークレット ）
新規作成には Owner / Admin / Developer のロール、既存アプリの更新には、そのアプリの管理権限（manage）が必要です。
アプリのフォルダを AI エージェントで開き、次のように依頼します。Keelson のスキルの設定方法はクイックスタート にあります。
このアプリを Keelson にデプロイしてください。必要な設定を確認し、完了したらアプリの URL と動作確認の結果を教えてください。
エージェントには、次の内容を確認・実行してもらいます。
アプリの保存方法や起動設定が Keelson に合っているか確認する
keelson.yaml を作成・更新し、必要な API キーなどの登録先を案内するデプロイを実行し、完了まで確認する
失敗した場合はログを調べ、原因と対応方法を説明する
完了後に動作を確認し、確認した内容を報告する
初回デプロイでアプリが作られます。2 回目以降は、同じワークスペース内の keelson.yaml の slug に対応するアプリが更新されます。slug はアプリを識別する名前です。
Web アプリや静的サイトは、報告された URL を開き、画面表示や主な操作を確認します。確認する項目やエージェントへの依頼例はデプロイ後の確認 を参照してください。
定期実行だけのアプリは、画面を開く代わりに、コンソールの「定期実行」タブでスケジュールと実行結果を確認します。手動で試す方法は定期実行ジョブ にあります。
変更 反映のタイミング コード、keelson.yaml の設定 デプロイで反映 シークレット 保存後、次のデプロイで反映。「適用」でも、コードを再アップロード・ビルドせずに再デプロイして反映できる アプリ権限、IP 制御、公開 URL のアクセス設定 デプロイなしで反映。通常は 2 分以内。障害中の変更は復旧後に反映
公開 URL をアプリ内部でも使っている場合は、URL 変更後の確認 も参照してください。
エラーメッセージに含まれるエラーコード（code）や対処のヒント（hint）を AI エージェントに伝えると、原因の調査に役立ちます。ログの確認方法と症状別の対処はトラブルシューティング にあります。
更新の切り替え前に失敗した場合、以前のバージョンへのアクセスは維持されます。ただし、データベースに加えた変更は自動では戻りません。データベースの変更を含む場合は、更新と復元 の手順で状態を確認します。
エージェントを介さず、ターミナルから実行することもできます。
keelson deploy --new --secrets-from-env-file .env.keelson
# アップロードせずに設定とアーカイブ内容を確認する
keelson deploy --check --json
--secrets-from-env-file で指定したファイルはアーカイブから除外されます複数のワークスペースに属している場合は --workspace <slug> を付けます
更新先のアプリを明示するには --app <slug> を付けます。アップロードするソースは、コマンドを実行したフォルダのものです
スクリプトから使う場合は keelson deploy --ndjson --yes を使うと、完了まで待って結果を 1 行 1 JSON で返します
ここからは、設定やログを詳しく確認するときの説明です。サーバーで画面や API の処理を行う Web アプリでは、次の処理が行われます。
検証 — keelson.yaml とアップロードするファイルを確認しますビルド — 必要なライブラリをインストールし、実行に必要なファイルをまとめます。このまとまりを「コンテナイメージ」と呼びます（ビルドの上限は 900 秒）起動 — 新しいコードと設定でアプリを起動します。この実行単位を「リビジョン」と呼びますヘルスチェック — アプリが応答するか、health.path（既定 /）と verify のパスで確認しますマイグレーション — DB の構造などを更新する db.migrate があれば実行します切り替え — 利用者のアクセス先を新しいリビジョンに移します
静的サイト / SPA は、ビルド済みの HTML・JavaScript などを配信します。Web サーバーの起動は行いません。定期実行だけのアプリには Web のアクセス先を切り替える処理はなく、設定した時刻にジョブが実行されます。
保存方法や起動設定を調整する例として、ローカルの SQLite ファイルから Managed SQLite への移行や、Keelson が渡す PORT を使う変更があります。詳しくは対応アプリと制約 を参照してください。
デプロイ後の確認 デプロイが完了したら、アプリを開き、普段使う操作ができるか確認します。AI エージェントには、画面や API が正常に応答するかの確認を依頼できます。
自分のアカウントでアプリを開けるか
一覧表示や検索など、主な操作ができるか
保存機能がある場合、テスト用のデータを保存して読み直せるか
利用者に共有する前には、その人がアプリを開ける権限を持っているかも確認します。自分のアカウントで開けても、他の利用者が開けるとは限りません（アプリ URL とドメイン ）。
定期実行だけのアプリは、コンソールの「定期実行」タブで実行結果を確認します。
デプロイしたアプリの主な画面と API を確認してください。確認できたことと、まだ確認していないことを教えてください。データを変更する確認にはテスト用データを使ってください。
画面や API から応答が返っても、計算結果や業務上のルールが正しいかは別途確認が必要です。普段使う入力例と期待する結果を伝えると、エージェントも確認しやすくなります。
通常のアプリの URL は認証で保護されているため、ログイン情報を付けない curl では確認できません。keelson app curl は、CLI にログインした本人の権限でリクエストを送ります。
本人としてアプリにアクセスするための一時的な認証情報を「プレビュートークン」と呼びます。app curl は内部でトークンを取得するため、利用者が値を扱う必要はありません。
次のコマンドで、ページや API の応答を取得できます。
keelson app curl / # GET /
keelson app curl -i /api/items # ヘッダーも表示
データの登録・更新・削除やファイルのアップロードは、実際のアプリに変更を加えます。次は書き込みの例です。パスとデータは、確認するアプリに合わせます。
keelson app curl /api/items --method POST \
--data '{"name":"example"}' \
--header 'Content-Type: application/json'
keelson app curl /upload --form title=example --form photo=@sample.png
レスポンス本文は標準出力、メソッド・URL・ステータスは標準エラー出力に出ます。-i を付けるとヘッダーも標準エラー出力に出るので、本文だけをファイルに落とせます
既定は GET。--method で POST / PUT / PATCH / DELETE を明示すると、有効期間 5 分の書き込みを許可するトークンが使われます
--data は書き込みメソッドとだけ併用できます。@ファイル名 でファイルから読みます--form を使うとメソッドは POST になり、multipart の Content-Type は CLI が付けます（--header での上書きは不可）パスは / で始める必要があります。絶対 URL と // で始まるパスは拒否されます。リダイレクトは追いません
/__keelson/media/... と /__keelson/assets/... も GET / HEAD で確認できます対象のアプリを明示する場合は --app <slug>
エージェントには、成功を示すステータスだけでなく、返された内容の種類（Content-Type）も確認してもらいます。たとえば、存在しない JavaScript ファイルの代わりに SPA の HTML が返ると、200 でも画面は正常に動きません。
別の HTTP クライアントを使う、複数回リクエストする、有効期間を選ぶ、といった場合はトークンを直接発行します。
keelson preview # GET / HEAD のみ。既定 30 分
keelson preview --allow-writes # POST / PUT / PATCH / DELETE も可。既定 5 分、最大 10 分
keelson preview --json # トークン・URL・有効期限を JSON で
--json が返す token と app_url を別の HTTP クライアントで使います。トークンは Bearer トークンとして渡します。
curl --header 'Authorization: Bearer <token>' '<app_url>/api/items'
トークンは標準出力に 1 回だけ表示され、Keelson は保存しません。ログや報告書に残さないでください。keelson preview で発行できるトークンは、アプリ × 利用者につき 1 本です。もう一度発行すると、有効期限内でも前のトークンは取り消されます。keelson app curl は別の内部用のトークンを使うため、preview で発行したトークンを取り消しません。
現在配信中のデプロイを自分が作っていない場合、プレビュートークンの発行前に、ブラウザで開く承認 URL が案内されます。承認には、そのアプリの管理権限（manage）が必要で、管理権限がある本人が承認することもできます。
承認画面で対象アプリ、書き込みの許可、有効期間を確認し、トークンの発行を承認します。承認後、案内された --confirmation <id> を付けて同じコマンドを再実行します。
これらのコマンドで取得できるのは、本人の権限で送ったリクエストへの応答です。ブラウザでの見た目や操作、他の利用者のアクセス権限は別途確認します
静的サイトには書き込み先がないので、書き込みメソッドは拒否されます
読み取り用の GET でも、アプリ側の実装によってはデータの変更やメール送信が起こります。確認対象の処理をエージェントに調べてもらい、意図しない変更が起きるパスは避けます
環境変数とシークレット 外部サービスの API キーや接続先などを、アプリに設定できます。設定値をアプリに渡す仕組みを「環境変数」と呼びます。API キーなどの秘密の値は、Keelson の「シークレット」に登録します。
種類 例 どこに書くか 秘密でない設定値 NODE_ENV、LOG_LEVEL、公開 API の URLkeelson.yaml の env秘密の値 API キー、トークン、DB 接続文字列、Webhook の署名シークレット シークレット （コンソール / CLI / デプロイ時の env ファイル）
keelson.yaml はソースコードと一緒に管理するファイルです。秘密の値は含めず、シークレットに登録します。
このアプリに必要な設定値と API キーを整理してください。設定ファイルには名前と用途を記載し、秘密の値を登録する場所を案内してください。
設定ファイルや値の読み取り処理はエージェントに依頼できます。秘密の値はチャットに貼る代わりに、コンソールや手元の設定ファイルへ入力します。
既存のアプリは、コンソールのアプリ画面にある「シークレット」タブで追加・更新・削除できます。保存後に表示されるのは名前と更新日時で、値は再表示されません。
初回デプロイ時には、手元の env ファイルに値を入力し、デプロイと同時に登録することもできます。以下のファイルは書式の例です。
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 キーを使う操作などが動くか確認します。
ここからは設定ファイルとコードの詳細です。秘密でない値は、エージェントに keelson.yaml の env への記載を依頼できます。
値は必ず引用符で囲みます（数値・真偽値も）。引用符がないとデプロイが拒否されます
PORT と KEELSON_ で始まる名前は書けません（Keelson が設定します）変更は次のデプロイで反映されます
keelson.yaml の secrets に、アプリが読むシークレットの名前だけ を宣言します。値は書きません。
description : "OpenAI API key"
- name : SLACK_WEBHOOK_URL
description : "通知先の Slack Webhook"
- all_of : [ OPENAI_API_KEY ]
message : "OPENAI_API_KEY を設定してください"
items は名前と用途の一覧で、コンソールにも表示されます。required はデプロイに必要な条件です。この例では OPENAI_API_KEY が未設定だと message が表示されます。SLACK_WEBHOOK_URL は一覧にありますが、必須条件には含まれていません。
範囲（スコープ） 設定場所 用途 ワークスペース コンソールの「シークレット」 全アプリ共通の値（共有 API キーなど） アプリ アプリ画面の「シークレット」タブ そのアプリだけの値、またはワークスペースの値の上書き
同じ名前があれば アプリ > ワークスペース > env の順で優先されます。アプリ画面のシークレットタブには、どちらのスコープから来た値かが表示されます。
env もシークレットも、サーバー側のコードから環境変数として読み取ります。
api_key = os.environ[ "OPENAI_API_KEY" ]
const apiKey = process.env. OPENAI_API_KEY ;
env もシークレットも、ビルド（依存関係のインストール、npm run build）には渡りません。ビルドが読めるのはアップロードしたソース一式だけです。
フロントエンドのビルドに埋め込む公開値（VITE_API_URL など）は、ソース内の設定ファイルに書きます。ブラウザに配布される値なので、ここに認証情報を置かないでください。
Keelson はプラットフォーム管理の変数を各アプリに設定します。自分で定義または上書きしないでください。
変数 内容 PORTWeb アプリの待ち受けポート。 TZワークスペースのタイムゾーン。 KEELSON_MODEプラットフォームモードを示す値。 KEELSON_APP_IDアプリの内部 ID。 KEELSON_WORKSPACE_IDワークスペースの内部 ID。 KEELSON_TENANT_IDKEELSON_WORKSPACE_ID の互換用別名（値は同じ）。KEELSON_DEPLOY_ID現在のデプロイの内部 ID。 KEELSON_APP_URLホストを解決できる場合のアプリの公開 URL。 KEELSON_DIRECTORY_BASE_URLホストを解決できる場合の Directory API のベース URL。
旧 tenant 名の変数も互換のため受け付けます。撤去時期は未定です。
機能を有効にすると追加の変数が設定されます。完全な一覧と設定条件は環境変数一覧 にあります。
NODE_ENV は自動設定されないため、アプリが必要とする場合は env に記載します。
アプリ URL とドメイン Web アプリや静的サイトには専用の URL が割り当てられ、デプロイ後に利用者へ共有できます。自社で管理するドメインを使うこともできます。
標準の URL は次の形式です。slug は、URL などに使う識別名です。
https://<ワークスペース slug>--<アプリ slug>.keelson.run
ワークスペースの slug が acme、keelson.yaml の slug が dashboard なら https://acme--dashboard.keelson.run です。HTTPS の証明書は Keelson が管理します。
URL は、コンソールのアプリ画面、デプロイ完了時の AI エージェントの報告、keelson status で確認できます。
URL を知っているだけでは開けません。ワークスペースにログインし、そのアプリの閲覧権限を持つメンバーだけが開けます。IP 制御を設定していれば、許可されたネットワークからのアクセスに限られます。
App User にはアプリの URL を別途共有する 必要があります。App User はコンソールを開けないため、自分で URL を確認する手段がありません。上のいずれかの方法で URL をコピーし、チャットやメールで本人に送ってください。
アプリ作成後も URL は変えられます（Owner / Admin）。コンソールのアプリ設定「公開 URL」から行います。
変更すると以前の URL からは開けなくなり、新しい URL への自動転送もありません。利用者に新しい URL を共有し、ブックマークや外部サービスの設定を更新します。影響を確認するチェックを付けてから変更します。
以前の URL は 30 日間予約され、他のアプリが同じ名前を使えません。その間のアクセスには、利用できなくなったことを示す 410 Gone が返ります。30 日後に自動で解放されます
keelson.yaml の slug を変えてもアプリの URL は変わりません。slug はアプリの識別に使われます。コンソールでアプリの識別名も変更した場合は、次のデプロイ前に keelson.yaml の slug を合わせます
ワークスペースの slug も設定から変更できますが、既存アプリの URL は変わりません 。新しいワークスペース slug の形式に揃えたい場合は、アプリごとに公開 URL を更新します。
Team プランでは、app.example.com のような自社のサブドメインでアプリを利用できます。設定には、ドメインの管理画面で DNS を変更できる権限が必要です。社内のドメイン管理者に依頼する場合は、Keelson が表示する設定値を共有します。
対象: Team プラン。ワークスペース合計で 10 件まで、1 アプリに 1 ドメイン
サブドメインのみ。ルートドメイン（example.com）とメールドメインは対象外
カスタムドメイン経由でも、認証・権限・IP 制御は同じように適用されます
設定は次の順で行います。
Owner または Admin が、コンソールのアプリ設定か keelson domains add <hostname> [--app <slug>] でドメインを登録します。登録すると、DNS に設定する CNAME の転送先が表示されます
DNS 事業者の設定で、登録したサブドメインの CNAME を表示された転送先へ向けます。本番環境の転送先は custom-origin.keelson.run です。コンソールまたは CLI に表示された値を使用してください
コンソールの状態表示か keelson domains verify <hostname> [--app <slug>] で有効になったことを確認します。有効化には数分かかることがあります
所有権の確認、HTTPS 証明書の発行、配信の設定は Keelson が自動で行います。
メール内のリンクなど、アプリが自分の URL を組み立てる場合の実装方法です。設定は AI エージェントに依頼できます。
アプリの標準 URL は環境変数 KEELSON_APP_URL で渡されます。リクエストの Host ヘッダーは内部のホスト名になるので、絶対 URL が必要な場面（メール内のリンク、リダイレクト、og:url）では KEELSON_APP_URL を使います。
base_url = os.environ[ "KEELSON_APP_URL" ] # 例: https://acme--dashboard.keelson.run
ローカル開発では設定されません。「Keelson 上で動いているか」の判別には KEELSON_MODE を使ってください。
公開 URL を変更しても、動いているアプリの環境変数はその場では更新されません。KEELSON_APP_URL を使うアプリは再デプロイし、メール内のリンクや移動先が新しい URL になっているか確認します。
カスタムドメインを設定しても、KEELSON_APP_URL は標準 URL のままです。メールのリンクなどにもカスタムドメインを使いたい場合は、その URL をアプリ側の設定値として持つようエージェントに依頼します（環境変数とシークレット ）。
アプリの状態とログ アプリが使える状態か確認したり、不具合の原因を調べたりするときは、コンソールの状態表示とログを確認します。ログには、アプリの処理やエラー、アクセスの記録が残ります。
コンソールのアプリ一覧とアプリ画面に、状態がバッジで表示されます。
状態 意味 稼働中 最近のアクセスにより、「同時に使えるアプリ数」の枠を 1 つ使っている スリープ中 デプロイ済みで、最近のアクセスによる枠を使っていない。停止しているアプリはアクセス時に自動で起動する 配信中 静的サイト / SPA を配信している。画面のファイルは Keelson が直接返す サスペンド 手動で停止した状態。アクセスがあっても起動・再公開しない 。データ・URL・設定は保持される 起動中 / デプロイ中 起動・停止の切り替え、または新しいコードや設定の反映を処理している 未デプロイ アプリは作られているが、まだデプロイされていない エラー 直近のデプロイまたは実行に失敗した。アプリ画面に原因が表示される 削除中 削除処理中。完了すると一覧から消える — 定期実行だけのアプリ。ジョブごとの実行結果は「定期実行」タブで確認する
「稼働中」「スリープ中」は利用状況の表示で、サーバーのプロセスが起動しているかを直接示すものではありません。Web アプリは、アクセスがない状態が続くと停止し、次のアクセスで起動します（アプリが動くタイミング ）。
通常は、直近 5 分にアクセスがあったアプリが枠を使います。優先起動で予約した枠は、アクセスがなくても確保されます。枠が空いていないときは、空くまで待つよう案内する画面が表示されます。予約していない枠は、そのアプリへのアクセスが約 5 分途絶えると空きます。
「エラー」は直近のデプロイの失敗を示す場合もあり、以前のバージョンが使えることがあります。「概要」の失敗内容と、アプリを実際に開けるかを合わせて確認します。
一時的に止めたいアプリは、アプリ画面の「設定」→「サスペンド」でサスペンドします。サーバーを持つアプリだけでなく、静的サイトや SPA もサスペンドできます。サスペンド中は、アクセス・Webhook・cron のいずれでも起動せず、静的ファイルも配信されません。Keelson の標準 URL には停止ページが表示され、独自ドメインの配信も止まります。データ・URL・設定は削除されません。
再開はアプリ画面のヘッダーの「再開」から行います。静的サイトや SPA はサスペンド中にデプロイしても停止状態を維持し、明示的に再開したときに配信へ戻ります。静的ファイルの停止と再公開は順次反映されるため、操作後に配信状態が切り替わるまで少し時間がかかることがあります。
アプリ画面のヘッダーの「優先起動」を ON にすると、「同時に使えるアプリ数」の枠を常に 1 つ予約します。枠が埋まっていて起動できない、という状態を防げます。
枠を予約していても、アプリはアクセスがない状態が続くと停止します。次のアクセス時には起動を待つことがあります
Plus 以上で、枠数より 1 つ少ない数まで設定できます
調べたいことに合わせて、次の場所を確認します。
調べたいこと 確認する場所 記録される内容 デプロイが失敗した理由 「デプロイ」の各デプロイにある「ログを表示」 デプロイの進行と、失敗時のビルド・起動エラー アプリ使用中のエラー 「ログ」のアプリログ アプリが出力した処理の記録やエラー（標準出力・標準エラー） 利用者がアクセスを拒否された理由 「ログ」のアクセスログ 誰が・いつ・どのパスにアクセスし、許可・拒否されたか 定期実行が成功したか 「定期実行」の実行履歴 実行ごとの開始時刻・結果・所要時間・ログ
AI エージェントには、アプリ名・発生時刻・起きたことを伝えて調査を依頼できます。
このアプリで［日時］に［操作］をするとエラーになりました。状態とログを確認し、原因と対応方法を教えてください。
アプリログは Web と定期実行（cron）を切り替えられます。画面には直近 200 行を表示し、エクスポートでは最大 5,000 行を取得できます。アクセスログは、利用者・機械（アプリトークン）・Webhook で絞り込めます。閲覧できる期間はプラン によって異なります。
CLI からは keelson logs で取得できます。エージェントが処理しやすい JSON 形式でアプリログを取得するには、keelson logs app <slug> --json を使います。デプロイ失敗時に確認するログはトラブルシューティング にまとめています。
「デプロイ」タブに過去のデプロイが並び、各デプロイのソースのダウンロードとログの表示ができます。
コードを前のデプロイに戻す操作を「ロールバック」と呼びます。データベースの内容は戻らず、静的サイト / SPA は以前のファイルを再デプロイする必要があります。手順と戻せる範囲は更新と復元 にまとめています。
「再デプロイ」（アプリ画面ヘッダー）は、最後に成功したデプロイの実行用ファイルを使って起動し直す操作です。シークレットの「適用」も、コードを再アップロード・ビルドせずに再デプロイして反映します（環境変数とシークレット ）。
アプリを廃止するときは「設定」→「危険な操作」から削除できます。ブラウザでの承認が必要で、利用者自身で取り消すことはできません。削除前に取り出すデータと保持期間は更新と復元 を参照してください。一時的に止める場合は、上の「サスペンド」を使います。
更新と復元 アプリの変更を反映したり、不具合が起きたときに以前のコードやデータへ戻したりできます。やりたいことに合わせて操作を選びます。
操作には、そのアプリの管理権限（manage）が必要です。データベースの復元とアプリの削除にはブラウザでの承認も必要です。
コードを戻しても、データベースやファイルは以前の状態に戻りません。 詳しい範囲は、後半の何が戻り、何が戻らないか で確認できます。
AI エージェントには、変更内容と確認してほしい操作を伝えます。
この変更を Keelson に反映してください。デプロイ前に設定とアップロード対象を確認し、完了後に［操作］ができるか確認してください。
手元の開発環境で変更内容を確認します
エージェントにデプロイを依頼します。CLI では keelson deploy --check --json で設定とアップロード対象を事前確認し、keelson deploy で反映できます
完了したらアプリを開き、変更した操作を確認します。定期実行だけのアプリは実行履歴を確認します（デプロイ後の確認 ）
切り替え前に失敗した場合、以前のバージョンへのアクセスは維持されます。ただし db.migrate が途中まで実行された場合、その変更は残ります（下の「DB の構造を変える」）。
反映されるもの・されないもの（シークレットは保存後にデプロイまたは「適用」が必要、など）はデプロイする を参照してください。
コードを以前のデプロイに戻す操作を「ロールバック」と呼びます。対象にできるのは、実行用のファイルをまとめた「コンテナイメージ」が残っている、過去の成功したデプロイです。
エージェントには「［不具合］が起きたので、前のコードに戻せるか、データへの影響も含めて確認してください」と依頼できます。CLI の操作は次のとおりです。
keelson rollback # 直前の成功したデプロイに戻す
keelson rollback <deploy_id> # 指定したデプロイに戻す
ビルドし直さず、対象デプロイのイメージと keelson.yaml の設定でアプリを起動します
対象にできるのは、イメージを持つ完了済みのデプロイだけです。静的サイト / SPA のデプロイと、古い方式で作られたデプロイはロールバック先にできません
シークレットは現在の値が使われます
対象デプロイの keelson.yaml に db.migrate があれば、ロールバックでも切り替え前に実行されます。DB に一切触れない操作ではありません
データベースは戻りません。 更新時に DB の構造（スキーマ）を変えていた場合、戻したコードがその構造で動くか確認が必要です。列の追加でも制約や既定値によって影響が出るため、エージェントに互換性の確認を依頼します。必要に応じて DB の復元も検討しますデプロイ進行中は実行できません
デプロイの一覧はコンソールの「デプロイ」タブにあり、各デプロイのソースをダウンロードできます。
静的サイト / SPA を戻すには、以前の成果物をもう一度デプロイします。Git で前のコミットに戻して手元でビルドし直すか、「デプロイ」タブから以前のデプロイのソース（assets.dir の中身と keelson.yaml）をダウンロードして、そのまま keelson deploy します。
Managed SQLite（db.mode: libsql）のデータは、コンソールのアプリ画面にある「復元ポイント」から戻します。
復元ポイントのタイムラインから時点を選びます。日次バックアップ、手動で保存した状態（スナップショット）、指定した時刻への復元（PITR）のいずれかです（プランごとの保持世代数と復元窓はプランと制限 ）
選択した過去の復元ポイントをダウンロード して、中身を確認することもできます。この操作で取得するのは、現在の DB ではありません
復元 を実行します。ブラウザでの承認が要ります復元後、アプリを開いてデータを確認します
復元で起きること:
その時点以降の書き込みはすべて消えます。 消したデータだけを戻す操作ではありません。現在のデータも残しておきたい場合は、復元を実行する前に現在の DB の手動スナップショットを作成し、そのスナップショットをダウンロードします。復元後に必要な変更を移す作業は、エージェントに相談できます復元前の状態は 72 時間保持され、その間は復元を取り消せます
復元は 1 つのアプリの DB だけに効きます。他のアプリには影響しません
Files / Media のファイルと外部 DB は対象外です
大きな変更の前に手動スナップショットを作ると、戻す時点を残せます（1 アプリ 5 回/日）。
保存する項目の追加など、DB の構造を更新する処理を「マイグレーション」と呼びます。コードを戻したときにも動くよう、エージェントには次の確認を依頼します。
DB の構造を変更する場合は、更新前のコードでも動くか、失敗後に再実行しても問題がないかを確認してください。復元が必要になる変更は、実行前に影響と戻し方を教えてください。
db.migrate に書いたコマンドは、デプロイやロールバックで新しいバージョンへ切り替える前に実行されます。
失敗すると以前のバージョンへのアクセスは維持されます。ただし、途中まで実行された DB の変更は自動では戻りません 。keelson logs deploy <deploy_id> のログと DB の状態を確認してから修正します
同じ処理を繰り返しても重複した変更が起きないようにします。この性質を「冪等性」と呼びます。適用済みの変更を記録する仕組みや IF NOT EXISTS などを使い、途中で失敗した場合も確認します
列やテーブルを追加する場合も、旧コードとの互換性を確認します。列の削除や型の変更など影響の大きい変更は、直前にスナップショットを作成し、利用の少ない時間帯に行う方法を検討します
「止める」と「消す」は別の操作です。
操作 何が起きるか 戻せるか サスペンド （アプリ画面の「設定」→「サスペンド」）アクセス・Webhook・cron のいずれでも起動しない。URL には停止ページが出る。データ・URL・設定は残る 「再開」でいつでも戻せる 削除 （「設定」→「危険な操作」）アプリ本体・URL・デプロイ履歴・シークレットが消える。ブラウザでの承認が要る 戻せない
削除の前に取り出しておくもの:
DB のデータ — 現在のデータが必要なら手動スナップショットを作り、その復元ポイントからダウンロードFiles のファイル — アプリにダウンロード処理を用意して取り出しますMedia のファイル — アプリが記録したファイル ID から閲覧用リンクを作り、削除前に保存します。Files / Media とも、コンソールや CLI には一覧・ダウンロード機能がありません（ファイルとメディア ）ソースコード — Git、または「デプロイ」タブの各デプロイからダウンロードシークレットの値 — 保存後は再表示されません。登録時の保管先や発行元で、必要な値を確認します
削除後、DB のバックアップ・Files・非機密の構成メモ（アプリ名、URL、cron 定義、環境変数とシークレットの名前 ）は 7 日間隔離保持されますが、これは誤削除への裁量対応であり、復元の保証ではありません。
契約が終了した場合のアプリの扱いは料金と契約の運用 を参照してください。
表の「ロールバック」はコードを前のデプロイに戻す操作、「DB の復元」は Managed SQLite を復元ポイントに戻す操作です。
対象 ロールバックで戻るか DB の復元で戻るか 備考 コード（イメージ） 戻る 戻らない ビルドし直さず、対象デプロイのイメージを起動する。静的サイト / SPA は対象外 keelson.yaml の設定（env、crons、assets、health）戻る 戻らない 対象デプロイ時点の設定が使われる シークレットの値 戻らない 戻らない 常に現在の 値が使われる。コンソールで手で戻す Managed SQLite のデータ 戻らない 戻る 日次バックアップ、手動スナップショット、PITR（時刻復元） db.migrate で加えたスキーマ変更戻らない 戻る 復元ポイントの時点の DB 構造になる Files SDK のファイル 戻らない 戻らない バックアップの対象外。アプリ側で保持する Media SDK のファイル 戻らない 戻らない 上書き不可。差し替えは新しいファイルを保存する 外部 DB（PostgreSQL など） 戻らない 戻らない 外部サービス側のバックアップで戻す 外部サービスへの変更（Slack 投稿、メール送信、決済） 戻らない 戻らない ロールバックでは取り消されない。再実行時の重複に注意 アプリ権限、IP 制御、公開 URL 戻らない 戻らない デプロイと独立した設定。手で戻す
トラブルシューティング デプロイに失敗したときや、アプリが期待どおりに動かないときの確認方法をまとめています。AI エージェントには、起きたこととエラーメッセージを伝えて、原因の調査を依頼できます。
このアプリで［操作］をすると［症状］が起きます。発生したのは［日時］です。状態とログを確認し、原因と対応方法を教えてください。
エラーコード（code）、メッセージ（message）、対処のヒント（hint）が表示されていれば、一緒に伝えます。サービス側の障害など、アプリの修正では解決しない場合は、サポートに問い合わせる の情報をまとめます。
コンソールでは、アプリ画面の「概要」に失敗の要約、「デプロイ」の「ログを表示」にデプロイログ、「ログ」にアプリログがあります。まず概要を確認し、必要に応じてエージェントに詳細を調べてもらいます。
deploy_id はデプロイを識別する ID で、CLI の出力やコンソールの「デプロイ」タブで確認できます。
keelson status # アプリと直近デプロイの状態
keelson diagnose <deploy_id> # 失敗したデプロイの診断
keelson logs deploy <deploy_id> # 進行ログと失敗したデプロイの詳細
keelson logs app <slug> # アプリの標準出力・標準エラー
起動中にアプリが終了した場合も、keelson logs deploy や keelson diagnose から保存済みの起動ログを確認できます。エラーが起きたコードの位置や、必要な設定が足りないことなどが記録されます。
保存されるログの範囲
失敗したデプロイでは、ビルドや起動の詳細が保存されます。依存パッケージや Dockerfile、シークレット、設定、マイグレーションのエラーを後から調べるときにも使えます。起動時の例外の記録（traceback）やプロセスエラーは、保存済みの起動ログを確認します。
成功したデプロイのビルド出力は保存されません。進行ログも保存済みの失敗詳細もない場合は、ログがない理由が表示されます。
止まった場所 見るもの よくある原因 アップロード前（CLI の事前チェック） コマンドの出力 Go アプリに go.mod がない、Node アプリに pnpm / yarn 用ロックファイルしかない、command に pip install、db.mode がない、env の値が引用符なし 検証 code と messageworkers / databases が残っている、予約名、プラン上限ビルド デプロイログ 依存の解決失敗、package.json と package-lock.json の不一致、非公開のパッケージ配布先（private registry）、cgo が必要な Go パッケージ、ビルドスクリプトのエラー 起動 keelson logs deploy <deploy_id> の保存済みのアプリの起動ログ0.0.0.0 で listen していない、PORT のハードコード、未設定のシークレットで例外ヘルスチェック 保存済みのアプリの起動ログ、その後にアプリログ アプリが起動中に終了、/ が 5xx、起動に 120 秒以上かかる マイグレーション デプロイログ db.migrate の SQL エラー。以前のバージョンへのアクセスは維持されますが、マイグレーションが加えた DB の変更は自動では戻りません 。DB の状態を確認してから直します動いているが期待どおりでない アプリログ、アクセスログ 下の「よくある失敗」
Ctrl-C で止まるのは、このクライアントによる監視だけです。デプロイはサーバー側で続いています。
そのまま新しいバージョンへ切り替わることがあるため、CLI に表示された deploy_id で進行状況を確認します。
keelson status <deploy_id>
新しいバージョンを使わない場合は、デプロイの完了後に以前のコードへ戻します。コンテナイメージが残っている過去の成功したデプロイには、次のコマンドで戻せます。DB の変更は戻りません。
keelson rollback --app <slug>
静的サイト / SPA はロールバックの対象外です。以前のファイルを再デプロイします。手順は更新と復元 を参照してください。
戻せるデプロイがない場合など、いったん利用を止めたいときは、デプロイ完了後にサスペンドします。
keelson app stop --app <slug>
手元と Keelson で設定や保存先が異なる可能性があります。エージェントには、次の点を確認してもらいます。
手元からの接続だけを受け付けている — 待ち受けアドレスを localhost から 0.0.0.0 に変える接続を受け付けるポート番号をコードで固定している — PORT 環境変数から読むローカルにしかないファイルに依存している — .env、ローカルの DB ファイル、.gitignore 済みのファイル。keelson deploy --check --json の archive.excluded で、何が除外されたか分かります環境変数が未設定 — ローカルの .env にだけある値は Keelson にはありません。secrets に宣言して値を設定するローカルの SQLite ファイルを使っている — /data も /tmp も再起動後にデータが残りません。Managed SQLite への移行を検討する
Keelson の Node ビルダーは npm を使うため、依存を固定するには npm 用の package-lock.json が必要です。エージェントに、プロジェクトのルートで npm install を実行して package-lock.json を生成し、依存関係の整合性を確認してから再デプロイするよう依頼します。生成したファイルはソースコードと一緒に管理します。
pnpm-lock.yaml や yarn.lock は削除しなくてかまいません。package-lock.json と同居していてもデプロイでき、ビルドには package-lock.json が使われます。
保存先がアプリのサーバー内のファイルになっていないか確認します。/tmp、/data、アプリディレクトリのファイルは、再起動・再デプロイ・アイドル停止で失われます。データベース か Files / Media SDK に置きます。
サーバー側でレスポンスを返した後に続ける処理は、最後まで実行されることが保証されません。また、アプリ内のタイマーは、アプリの停止中には動きません。
エージェントに、そのリクエストで必要な処理は応答を返すまでに完了させ、定期的な処理は Keelson の定期実行ジョブへ移すよう依頼します。後でまとめて処理する場合は、未処理の内容を DB に保存する方法もありますが、次の実行まで待ち時間が生じます。ブラウザ側のタイマーは、この制約の対象外です。詳しくはアプリが動くタイミング を参照してください。
スケジュールがプランの最小間隔より短くないか（デプロイ時に拒否されます）
前回の実行が終わっていないか（重複実行はスキップされます）
月間実行回数の上限に達していないか（当月はスキップ）
アプリがサスペンドされていないか
「定期実行」タブの実行履歴で、スキップの理由を確認できます
ブラウザに古いファイルが残っている可能性があります。デプロイの完了を確認し、ページを強制再読み込みします（Mac: Cmd + Shift + R / Windows: Ctrl + Shift + R）。
静的サイトの更新は配信先へ順次反映されるため、完了後も少し時間がかかることがあります。変わらない場合は、更新先のアプリとアップロードしたファイルが合っているか、エージェントに確認を依頼します。
ワークスペースのメンバーか（招待が未承諾でないか）
ブロックされていないか
アプリの閲覧権限があるグループに入っているか
登録されたアカウントでログインしているか
IP 制御で拒否されていないか（403 画面に送信元 IP が出ます）
詳細はメンバーとロール 。
「同時に使えるアプリ数」の上限です。直近 5 分にアクセスがあったアプリと、優先起動を設定したアプリが枠を使っています。予約していない枠を使うアプリへのアクセスが途絶えてから約 5 分待つか、重要なアプリに優先起動 を設定するか、プランを上げます。
応答までに時間がかかりすぎた場合などに表示されます。Keelson では、応答開始まで 120 秒、ストリーミングを含む全体で 300 秒、ストリーミングの応答間隔で 120 秒の上限があります（HTTP の時間上限 ）。
エージェントに、時間のかかっている処理を調べ、処理を短くする・結果を少しずつ返す・定期実行に分ける方法を検討してもらいます。ストリーミングでも時間上限はなくなりません。
504 が表示されても、サーバー側では保存や送信が完了している場合があります。再操作する前に結果を確認します。実装では、同じ依頼を繰り返しても重複して保存・送信しない仕組み（冪等性）が必要です。
パスが auth.endpoints に宣言されているか（/api/webhooks/ か /api/external/ で始まる必要があります）
メソッドが宣言と合っているか
トークンのスコープと許可 IP が合っているか
外部システムとの連携 。
シークレットは保存しただけでは、動いているアプリに反映されません。コードも更新する場合はデプロイし、値だけを反映する場合はコンソールの「適用」を押します。「適用」は、コードを再アップロード・ビルドせずに再デプロイします（環境変数とシークレット ）。
deploy.platform.error のようにプラットフォーム側のエラーが出た場合や、上記で解決しない場合は、お問い合わせ から連絡してください。
次を添えると、やり取りの往復が減ります。
添えるもの 取り方 ワークスペースの slug keelson workspaces list --json の slug（URL は名前の変更前のものが残る場合があります）アプリの slug keelson.yaml の slug、または keelson apps list --workspace <ワークスペース slug> --json の slugdeploy_idkeelson status --json の出力、またはコンソールの「デプロイ」タブエラーの code と message と hint CLI の出力をそのまま。--json を付けるとまとめて取れます 起きた日時とタイムゾーン ログを引くときに使います 利用者が開けない場合は、その人のメールアドレスと 403 画面に出た IP 利用者が「アクセスできません」と言う
アプリのソースコードやシークレットの値は送らないでください。必要になれば、こちらから範囲を指定して依頼します。
料金・契約・請求書についての問い合わせも同じ窓口です（料金と契約の運用 ）。
ユーザーと権限 認証とログイン Keelson では、社内アプリを利用できる人を、ワークスペースのメンバーのうち閲覧権限を持つ人に限定できます。利用者はアプリの URL を開き、Keelson のログイン画面でログインします。URL を知っているだけではアプリを開けません。
ログイン画面やログイン状態の管理は Keelson が用意するため、アプリ側で作る必要はありません。利用できる人の設定はチームにアプリを共有する で説明しています。
アプリの利用者は、次のいずれかでログインします。
Google アカウント Microsoft アカウント メールアドレス （ログイン用の使い捨てコードをメールで受け取る）
ワークスペースに登録されているメールアドレスでログインする必要があります。複数のアカウントを使い分けている場合は、登録されたアカウントを選んでください。
ワークスペースを作成する（コンソールにサインアップする）ときは、Google または Microsoft アカウントが必要です。
アプリの URL を開きます。
ログインしていなければ、Keelson のログイン画面が表示されます。
Google / Microsoft アカウント、またはメールで受け取ったコードでログインします。
元のアプリに戻り、閲覧権限があればアプリが表示されます。
ログイン状態が保持されている間は、同じワークスペースの別のアプリも、ログインし直さずに開けます。それぞれのアプリの閲覧権限は必要です。
開けない場合はアクセスできないときの確認 を参照してください。
アプリでは、ログインした人の名前を表示したり、その人のデータに絞って表示したりできます。AI エージェントには「Keelson が渡す利用者情報を使って、本人のデータだけを表示できるようにして」と依頼できます。
Keelson は、サーバー側のコードに利用者情報を渡します。その情報を使って、どのデータを表示・更新できるかを判断する処理はアプリ側で実装します。詳しくはログイン中のユーザー情報を使う を参照してください。
利用者情報の受け渡し（HTTP ヘッダー）
認証を通ったリクエストには、Keelson が利用者情報を HTTP ヘッダーという付加情報として付けます。主なヘッダーは次のとおりです。
ヘッダー 内容 X-Keelson-User-Id利用者の ID X-Keelson-User-Emailメールアドレス X-Keelson-User-Name名前 X-Keelson-User-App-Permsそのアプリの権限
クライアントが送った同名の利用者情報ヘッダーはエッジで除去され、認証ゲートウェイがプラットフォームの DB から取得した値を付けます。ブラウザから送られた Authorization と Cookie も除去されます。利用者の確認には、Keelson が付けた情報を使います。
ブラウザからアプリを開くと、Keelson がログイン状態や権限を確認します。アプリの手前でこの確認を行う仕組みをプロキシと呼びます。
①を満たさない場合は、ログイン画面へ移動します。
②③を満たさない場合は、「アクセスできません」の画面になります。
④を満たさない場合は、アクセスが拒否されたことを示す画面（HTTP 403）になり、接続元の IP アドレスが表示されます。
IP 制御は、接続元のネットワークでアクセスを制限する設定です。静的サイト・SPA・ハイブリッドアプリの静的ファイルには、IP 制御が適用されません。 ログイン・メンバー・閲覧権限の確認は行われます。詳しくはIP 制御 を参照してください。
外部サービスからの通知（Webhook）や API 呼び出しでは、ブラウザでログインする代わりに、アプリトークンや送信元の署名で呼び出し元を確認します。
AI エージェントには、連携したいサービスと受け取りたい通知・データを伝えて、設定と実装を依頼できます。ログインなしで受け付けるパスとメソッドは、keelson.yaml の auth.endpoints に設定します。詳しくは外部システムとの連携 を参照してください。
メンバーとロール アプリを一緒に使う人を、ワークスペースのメンバーとして追加できます。アプリを使う人、作って更新する人、メンバーや設定を管理する人に合わせて、役割を選びます。この役割を「ロール」と呼びます。
アプリを使うにはメンバーであることが必要です。利用できるアプリは、所属グループに割り当てられたアプリごとの権限 で決まります。
アプリを使うだけの人には App User、作って更新する人には Developer を選びます。メンバーやワークスペースの設定を管理する人には Admin、請求や Owner の管理も担う人には Owner を割り当てます。
ロール 主な用途・できること Owner ワークスペースの責任者。Owner を含むメンバー管理、設定、請求を扱う Admin チームの管理者。Owner 以外のメンバー管理とワークスペースの設定を扱う Developer アプリを作ってデプロイ・更新する。メンバー管理やワークスペースの設定変更はできない App User 閲覧権限のあるアプリを使う。コンソールでの管理操作は行わない
Owner・Admin・Developer の人数は、プランの開発・管理用の人数枠（Developers 席）に数えられます。App User はこの人数枠に含まれず、人数無制限です。詳しくはプランと制限 を参照してください。
ロールは「メンバー」画面から Owner / Admin が変更できます。Owner ロールの付与・変更は Owner だけができます。ワークスペースには最低 1 人の Owner が必要です。
方法 参加するまでの流れ 招待 Owner / Admin がメールアドレスを指定し、招待された本人がリンクを開いて招待を承諾する 参加 URL 許可されたメールドメインの人が URL を開き、ログインして参加する。管理者の承認は不要 ワークスペースを探して参加申請（Discover） 許可されたメールドメインの人が申請し、Owner / Admin が承認する
メールドメインは、メールアドレスの @ より後ろの部分です。会社のメールドメインを許可すると、そのアドレスを持つ人が参加 URL や Discover を使えるようになります。設定はドメインと参加ポリシー で説明しています（Team プラン以上）。ドメイン自動参加で入ったメンバーのロールは App User です。
退職などでワークスペース内のすべてのアプリへのアクセスを止めたいときは、Owner / Admin が「メンバー」画面でそのメンバーを無効化 します。異動などで利用できるアプリだけを変えたい場合は、所属グループやアプリの権限 を変更できます。
無効化がアクセス判定に反映されるまで、時間がかかることがあります。保存直後にすべてのアクセスが止まるとは限りません。
アカウントの削除ではありません。「再有効化」で戻せます。
自分自身と、最後の Owner は無効化できません。Admin は Owner を無効化できません。
ロールに応じて、次のグループに自動的に所属します。これらはシステムグループと呼ばれ、所属メンバーを手動では変更できません。
ロール 自動的に所属するグループ Owner owners developers everyoneAdmin admins developers everyoneDeveloper developers everyoneApp User everyone
新しいアプリには、everyone（全メンバー）に閲覧権限、developers（Owner / Admin / Developer）に管理権限が割り当てられます。管理権限には閲覧も含まれます。
アプリを利用・管理できるかは、このグループへの権限の割り当てで決まります。ロールを変更すると自動所属グループも変わるため、アプリへのアクセスにも影響します。特定のチームに利用を限定する手順はチームにアプリを共有する を参照してください。
利用者はまず、招待・登録されたメールアドレスでログインしているかを確認します。メンバーの状態は Owner / Admin に、アプリの権限はそのアプリを管理する人に確認を依頼できます。
登録されたアカウントでログインしているか — 複数の Google / Microsoft アカウントを使い分けている場合は、メールアドレスを確認します。メンバーになっているか — 「メンバー」画面で確認します。招待が未承諾なら、本人に承諾してもらいます。無効化されていないか — 「メンバー」画面の「無効化済み」で確認できます。アプリの閲覧・管理権限があるか — アプリ画面の「権限」で、その人の所属グループへの割り当てを確認します。IP 制御で拒否されていないか — IP 制御による拒否画面には、接続元の IP アドレスが表示されます。適用範囲はIP 制御 を参照してください。
チームにアプリを共有する アプリを使う人を特定のチームに限定して、URL を共有できます。このページでは、営業チームのメンバーと、アプリを管理する人が使えるように設定します。
招待とグループ作成には Owner / Admin、アプリの権限変更にはそのアプリの管理権限が必要です。全プランで利用できます。
ここで設定するのは、アプリを開ける人の範囲です。「自分の申請だけ見える」「上司だけ承認できる」といった業務上の権限は、アプリ側で実装します。
「メンバー」→「招待」で、営業チームのメールアドレスを入力し、ロールは App User を選びます。アプリを使うだけの人向けのロールで、開発・管理用の人数枠（Developers 席）には含まれません。
相手はメールのリンクを開き、招待されたアドレスと同じアカウントでログインして、招待を承諾します。詳細はメンバーを招待する を参照してください。すでに参加している人を再度招待する必要はありません。
社員が多い場合は、Team プラン以上でドメイン自動参加 を使うと、招待なしで参加できます。
グループは、アプリの権限をまとめて割り当てるためのメンバーの集まりです。「メンバー」→「グループ」で「営業」グループを作り、営業チームのメンバーを追加します。
グループには、表示名とは別に、設定やコマンドで指定する名前（キー）を付けます。この例では sales を使います。キーは作成後に変更できませんが、表示名とメンバーは変更できます。
アプリ画面の「権限」タブを開きます。閲覧権限はアプリを開いて使う権限、管理権限はアプリをデプロイしたり設定を変更したりする権限です。管理権限には閲覧も含まれます。
新しいアプリでは、everyone（全メンバー）に閲覧、developers（Owner / Admin / Developer）に管理が割り当てられています。「営業」に閲覧を追加するだけでは、everyone の閲覧が残り、全員が開ける状態が続きます。
閲覧グループから everyone を外します
閲覧グループに sales を加えます
この例では、管理グループを developers のままにして保存します。
これで、営業メンバーと developers のメンバーがアプリを開ける設定になります。営業以外の App User は開けません。すでに権限を変更したアプリでは、ほかの閲覧・管理グループが残っていないかも確認します。
管理する人の範囲も変えたい場合は、グループとアプリ権限 を参照してください。そのアプリの管理権限を持つ人は、閲覧グループに入っていなくてもアプリを開けます。
設定の保存後、アクセス判定への反映には時間がかかることがあります。ログイン中の利用者についても、反映後は変更した権限で判定されます。
アプリ画面の URL（https://<ワークスペース>--<アプリ>.keelson.run）をコピーして、チャットやメールで共有します。App User はコンソールでアプリの URL を確認できず、招待メールにもアプリの URL は含まれません。
「招待されたメールアドレスでログインしてください」と添えると、複数のアカウントを使う人にも伝わります。
共有したい人が開けることと、閲覧・管理のどちらの権限も持たない人が開けないことを確認します。
確認 期待する結果 営業グループの利用者が URL を開く ログイン後にアプリが表示される 営業グループに入っていないアプリ管理者が URL を開く ログイン後にアプリが表示される 営業グループに入っておらず、ほかのグループ経由でも閲覧・管理権限を持たない App User が URL を開く ログイン後に「アクセスできません」の画面になる ログインしていない人が URL を開く Keelson のログイン画面になり、アプリは表示されない
対象外の利用者に確認を頼めない場合は、自分の別のメールアドレスを App User として招待し、営業グループに追加せずに試せます。
保存した設定は、アプリ一覧の「アクセス範囲」で確認できます。全員に閲覧を許可していなければ、人数とグループが表示されます。実際に開けるかどうかは、上の手順で確認します。
症状 確認すること 営業の人が開けない 招待を承諾しているか、sales に所属しているか、登録されたメールアドレスでログインしているかを確認します 営業以外の人も開ける everyone やほかの閲覧グループが残っていないか、その人が管理グループに所属していないかを確認します保存した設定でアクセスが変わらない 反映に時間がかかることがあります。少し待って再読み込みし、「権限」タブの保存内容と、確認に使ったアカウントを見直します
メンバーの無効化や IP 制御など、その他の確認項目はアクセスできないときの確認 を参照してください。
グループ作成やアプリの権限設定は、CLI を使える AI エージェントにも依頼できます。対象のワークスペース、アプリ名、共有する人のメールアドレス、管理権限を残す人を伝えます。操作には、コンソールで設定する場合と同じ権限が必要です。
アプリ sales-tool を、営業チームとアプリ管理者が使えるように設定してください。招待済みの tanaka@example.com と suzuki@example.com を「営業」グループ（キー: sales）に追加し、閲覧は sales、管理は developers に設定してください。設定後に、閲覧・管理を許可したグループを教えてください。
AI エージェントによる設定後も、手順 5 のアカウントごとのアクセスを確認します。
CLI で設定する例
招待の承諾が済んだメンバーを、作成したグループに追加します。次のコマンドは、コンソールで行う手順 2・3 と同じ設定です。コンソールで設定済みの場合は実行不要です。
keelson groups create sales --name "営業"
keelson groups members add sales tanaka@example.com suzuki@example.com
keelson access set --app sales-tool --view sales --manage developers
access set には、残したい閲覧・管理グループを指定します。この例では閲覧を sales、管理を developers に設定します。
ここまでの設定で、アプリを開ける人の範囲を決められます。さらに「自分の申請だけを見せたい」場合は、AI エージェントに次のように依頼できます。
Keelson が渡すログイン中の利用者情報を使い、本人の申請だけを表示してください。他人の申請の URL や ID を指定しても、取得・更新できないようにし、その確認も行ってください。
利用者ごとの画面表示に加えて、データを取得・更新するサーバー側でも権限を確認する処理が必要です。AI エージェントには、別の利用者のデータを取得・更新できないことをどう確認したかも報告してもらうと、実装結果を確認できます。
判定には、Keelson が付けた利用者 ID（X-Keelson-User-Id）やグループ情報を使います。ブラウザから送られた値だけで本人と判断しないようにします。実装はログイン中のユーザー情報を使う を参照してください。
ワークスペース・アプリ・業務上の権限の違い
権限 設定する人・場所 例 ワークスペースの管理権限（ロール） Owner / Admin が付与。Owner の付与・変更は Owner のみ メンバーを招待できるか、請求を扱えるか アプリの閲覧・管理権限（view / manage） そのアプリの管理権限を持つ人が、グループに割り当てる アプリを開けるか、デプロイ・設定変更ができるか アプリ内の業務上の権限 アプリ側で実装する 自分の申請だけ見られるか、上司として承認できるか
アプリの管理権限は、デプロイや設定変更を行う人のための権限です。業務上の承認者と同じ人とは限りません。ロールの詳細はメンバーとロール を参照してください。
ワークスペースと契約 メンバーを招待する 作ったアプリを同僚に使ってもらうときは、メールアドレスを指定してワークスペースに招待します。アプリを使うだけの人と、作成や更新も行う人で、招待時に選ぶロールが異なります。
招待は Owner または Admin が行えます。全プランで利用できます。相手が招待を受け入れ、「メンバー」画面で参加を確認できれば完了です。
アプリを作る・管理する人の人数枠を「Developers 席」と呼びます。App User はこの枠を使いません。
招待する相手 ロール Developers 席 アプリを使う人 App User 消費しない アプリを作ってデプロイする人 Developer 消費する メンバー管理も任せる人 Admin 消費する ワークスペースの共同責任者 Owner 消費する
Admin は Owner ロールで招待できません。Developer と App User は他のユーザーを招待できません。
Developer 以上のロールで招待すると、招待を出した時点で Developers 席を 1 つ確保します（相手が招待を受け入れる前でも）。席が上限に達していると、これらのロールでは招待できません。App User は席に関係なく何人でも招待できます。
コンソールの「メンバー」を開き、「メンバーを招待」を選びます
メールアドレスを入力します（1 回に最大 50 件）
ロールを選びます
「招待を送信」を選びます
招待された人に、リンク付きのメールが自動で送られます。リンクはコンソールにも表示されるので、メールが届かない場合は直接共有できます。
有効期限は作成から 3 日間（72 時間） です。
メールのリンクを開きます
招待されたメールアドレスと同じ Google / Microsoft アカウント、またはメールのワンタイムコードでログインします「参加」を選び、招待を受け入れます
別のメールアドレスでログインしている場合は、招待されたアドレスでログインし直します。
参加後に使えるアプリは、アプリごとの権限 で決まります。既定では全メンバーが全アプリを使えます。
招待した人は、使ってほしいアプリの URL をチャットやメールで相手に送ります。招待メールには、アプリの URL は含まれません。
App User はコンソールを開けず、アプリの一覧も表示されません。参加後の画面には、アプリの URL を招待した人に確認する案内が表示されます。
「メンバー」画面では、招待を受け入れる前の人は「保留中」、参加した人は「アクティブ」と表示されます。
取り消し — まだ受け入れられていない招待を無効にします再送 — まだ受け入れられていない招待に新しいリンクを発行します。古いリンクは無効になり、有効期限は再送時から 3 日間（72 時間）です期限切れ・取り消し済みの招待は、同じアドレスで新しく作り直します
症状 確認すること 招待が作れない Owner / Admin か。既に参加済みでないか。Developer 以上なら席が空いているか メールが届かない 迷惑メールフォルダ。届かなければコンソールのリンクを直接共有 招待を受け入れられない 招待されたアドレスでログインしているか。期限切れ・取り消しになっていないか 参加したのにアプリが開けない アプリの閲覧権限、ログイン中のアカウント、IP 制御
自社ドメインのユーザーを招待なしで参加させるには、ドメインと参加ポリシー を設定します（Team 以上）。
グループとアプリ権限 「経理のアプリは経理チームに」「社内のお知らせは全員に」のように、アプリを使える人をグループで指定できます。アプリの更新や設定変更を行う人も、別に指定できます。
必要な権限 / プラン : グループの作成・メンバー変更は Owner / Admin。アプリの権限変更は、そのアプリの manage を持つ人。全プラン完了条件 : 対象の人でアプリが開け、閲覧・管理のどちらの権限も持たない人では「アクセスできません」になる
目的別の手順はチームにアプリを共有する にあります。
権限 できること 閲覧（view） 実行中のアプリを開いて使う 管理（manage） アプリのデプロイ、設定変更、シークレット編集、権限の変更。閲覧も含む
権限はユーザー個人ではなくグループ に割り当てます。グループのメンバーを変えると、そのグループを割り当てたアプリの利用者・管理者も変わります。
ロール（Owner / Admin / Developer / App User）は、ワークスペースで行える操作を決めます。アプリを使えるかどうかは、上の閲覧・管理権限で決まります。ただし、IP 制御 の設定は Owner / Admin が行い、アプリの管理権限だけでは変更できません。
アプリを作ると、次が自動で割り当てられます。
グループ 権限 everyone（全メンバー）閲覧 developers（Owner / Admin / Developer）管理
つまり何もしなければ、ワークスペースの全員がアプリを使え、開発者ロールの人が管理できます。絞りたいアプリだけ変更します。
特定のグループだけに絞るときは、everyone の閲覧を外す必要があります。 「経理」グループに閲覧を足しただけでは、everyone の閲覧が残っているので全員が開けたままです。また manage には閲覧が含まれるので、管理グループ（既定では developers）のメンバーは閲覧グループに入っていなくても開けます。
「メンバー」→「グループ」で管理します。
システムグループ — ロールから自動的に決まります。編集できません。
キー メンバー ownersOwner adminsAdmin developersOwner / Admin / Developer everyone全メンバー
カスタムグループ — 「経理」「営業」「店舗スタッフ」など、業務の単位で作ります。キー（経理 のような識別子。日本語も可）は作成後に変更できません。表示名とメンバーは変更できます。アプリに割り当てられている間は削除できません。
アプリ画面の「権限」タブで、閲覧グループと管理グループを選びます。
管理グループは最低 1 つ必要です（空にはできません。メンバーがいないグループだけにもできません）
自分の管理権限を外す操作は、他の管理グループに有効なメンバーがいる場合でも確認を求められます
保存した変更は、ログイン中のユーザーも含め、通常 2 分以内に反映されます
やりたいこと 設定 全員が使える社内ツール 既定のまま 経理チームとアプリを管理する開発者が使える 閲覧: keiri、管理: developers 利用は全員、設定変更は管理者だけ 閲覧: everyone、管理: admins
「上司だけが申請を承認できる」「部署ごとに見せる情報を変える」といったルールは、アプリ側に実装します。アプリを更新するための管理権限とは別に、誰がどの情報を見たり変更したりできるかを決めます。
AI エージェントには、たとえば「経理グループだけが経費の一覧を見られるようにして」と依頼します。作成後は、対象のグループの人と、それ以外の人で表示や操作を確認します。
実装では、部署などのグループは attributes.groups、アプリの管理権限は X-Keelson-User-App-Perms の manage で確認できます。詳しくは認証情報をアプリで使う を参照してください。
アプリ台帳の「アクセス範囲」に、全員に公開されていれば「全員」、限定されていれば対象の人数とグループが表示されます。
AI エージェントに設定を依頼するときは、グループに含める人と、アプリを使う人・管理する人を伝えます。次は CLI での操作例です。
keelson groups create keiri --name "経理"
keelson groups members add keiri tanaka@example.com suzuki@example.com
keelson access show --app my-app
keelson access set --app my-app --view keiri --view admins --manage admins
keelson access set --app my-app --view none # 閲覧を空にする。管理権限を持つ人は利用可能
ドメインと参加ポリシー 社員が多い場合は、同じ会社のメールアドレスを持つ人が、個別の招待メールなしで参加できるようにすると便利です。社内に参加リンクを配る方法と、Keelson の「参加」画面から申請してもらう方法があります。
設定と申請の承認は Owner または Admin が行います。Team プラン以上 で利用できます。
参加方法 メンバーになるタイミング 社内で共有された参加リンクを開く 対象のメールアドレスでログインし、「参加」を選んだとき。管理者の承認は不要 Keelson の「参加」画面から申請する Owner / Admin が申請を承認したとき
どちらの方法でも、参加時のロールは App User です。Owner / Admin が後からロールを変更できます。
参加できる人は、メールアドレスの @ より後ろの部分（メールドメイン）で決まります。たとえば name@example.co.jp のドメインは example.co.jp です。
設定する Owner / Admin と、ワークスペース作成者のメールドメインが一致している必要があります
Gmail や Outlook.com のように、誰でも取得できるメールサービスのドメインは登録できません
同じドメインを複数のワークスペースで利用できます（部署ごとのワークスペースなど）
参加リンクを有効にすると、操作した Owner / Admin のメールドメインが自動で登録されます。事前に手動で追加する必要はありません。登録内容は「設定」→「セキュリティ」→「アクセス制御」で確認できます。手動で追加する場合も、自分とワークスペース作成者のメールドメインに一致するものだけを登録できます。
「設定」→「セキュリティ」→「チーム参加リンク」を開きます
参加リンクを有効にします
URL をコピーして社内のチャットや案内ページで共有します
対象のメールアドレスを持つ人がリンクを開き、ログインして「参加」を選ぶと、その場でメンバーになります。「メンバー」画面で参加を確認できます。
参加リンクを有効にすると、対象のメールドメインでログインした人の「参加」画面にもワークスペースが表示されます。この画面で「参加をリクエスト」を選ぶと、Owner / Admin に申請が届きます。
申請は「設定」→「セキュリティ」の「保留中の参加リクエスト」から承認または却下します。申請しただけではメンバーにならず、承認されるまでアプリにアクセスできません。
参加リンクは、ワークスペースに参加するための URL です。使ってほしいアプリの URL は別途共有します。App User にはコンソールのアプリ一覧が表示されないためです。
参加後に使えるアプリは、アプリごとの権限 で決まります。
「リセット」で現在の URL を無効にし、新しい URL を発行できます。共有先を見直したいときに使います
参加リンクを無効にすると、個別の招待で参加する方式に戻ります。既に参加したメンバーには影響しません
設定の詳細では、参加方法を「参加ポリシー」と呼びます。参加リンクの有効・無効に連動するため、ポリシーを直接選ぶ操作はありません。
ポリシー 動作 招待のみ （既定）Owner / Admin の個別の招待で参加する 自動参加 対象のメールドメインの人は参加リンクから承認なしで参加できる。「参加」画面から申請した場合は管理者の承認が必要
IP 制御 アプリをオフィスや会社の VPN からだけ使えるようにします。利用者のログインとアプリの権限に加えて、接続元のネットワークを確認します。この仕組みを IP 制御と呼びます。
対象は、サーバー側で動く Web アプリと、画面の配信と処理を分けたハイブリッドアプリの API 部分です。静的サイト、SPA、ハイブリッドアプリの静的ファイル、Media の配信 URL には適用されません。 詳しくは適用範囲 を参照してください。
必要な権限 / プラン : アクセス元の作成、ワークスペースの既定、アプリごとの設定のいずれも Owner / Admin。アプリの manage 権限だけでは変更できません。全プラン完了条件 : 許可したネットワークからはアプリが開け、それ以外からはアクセスできない旨の画面（接続元の IP アドレスが表示される）になる
IP 制御は「アクセス元 」という単位で設定します。アクセス元は、許可するネットワークのアドレスを、名前を付けてまとめたものです。たとえば「東京オフィス」という名前で、複数の IP アドレスやアドレスの範囲を登録できます。範囲の指定には、203.0.113.0/24 のような CIDR という書き方を使います。
ワークスペースでアクセス元を作る
ワークスペースの既定 として適用するアクセス元を選ぶ（空なら制限なし）
アプリごとに「既定を引き継ぐ」か「このアプリ専用のアクセス元を選ぶ」かを決める
新しいアプリは既定を引き継ぎます。ワークスペースの既定を変更すると、それを引き継ぐアプリにまとめて適用できます。専用のアクセス元を設定したアプリには、その専用設定が使われます。
コンソールの「設定」→「セキュリティ」→「アクセス元の管理」で「アクセス元を登録」を選びます。
名前 — 「福岡オフィス」「VPN」などIP / CIDR — 1 行に 1 つ。IPv4 / IPv6 両方に対応。単一 IP（203.0.113.10）も範囲（203.0.113.0/24）も書けます。「現在の IP を追加」で自分の送信元を入れられますワークスペースの既定に追加 — チェックすると、作成と同時に既定に含まれます
ネットワーク管理者には「このアプリをオフィスと会社の VPN から利用できるようにしたい」と伝え、登録する固定 IP アドレスやアドレス範囲を確認します。
自宅や携帯回線では IP アドレスが変わることがあり、登録後にアクセスできなくなる場合があります。
アプリ画面の「設定」→「セキュリティ」で選びます。
モード 動作 ワークスペースの既定を引き継ぐ 既定のアクセス元を適用する。既定が空なら制限なし このアプリ専用のアクセス元 既定を置き換え、選んだアクセス元（1 つ以上）だけを適用する
「制限なし」にしたいアプリがある場合は、既定を空にしたうえでそれを引き継ぐか、制限したいアプリだけに専用のアクセス元を設定します。
設定はデプロイなしで反映されます。通常は 2 分以内に反映されます。障害中の変更は復旧後に反映されます。
許可されていないネットワークからブラウザで開くと、ログイン後に「このアプリは、許可されたアクセス元からのみ利用できます」という画面と、現在の接続元の IP アドレスが表示されます。
会社の VPN への接続が必要かを確認します。アクセス元への追加が必要な場合は、表示された IP アドレスを Owner / Admin に伝えます。
対象は、コンテナで動く Web アプリと、ハイブリッドアプリの API 部分への、ログインユーザーのアクセスです
静的サイト、SPA、ハイブリッドアプリの静的ファイル、Media の配信 URL（/__keelson/media/<ファイルID>）には適用されません 。Media ではログインとアプリの閲覧権限が確認されます（ファイルとメディア ）アプリトークンと Webhook には、ワークスペースやアプリの設定ではなく、トークンごとの許可 IP が適用されます（外部システムとの連携 ）
判定は ログイン → アプリの権限 → IP の順で行われます。IP 制御は、ログインとアプリの権限確認に追加される制限です。
許可されていないネットワークからのアクセスには HTTP 403 を返します。ブラウザでページを開く場合は案内画面を、ページ内の通信（fetch / XHR）や API 呼び出しには JSON を返します。
プランと制限 プランを選ぶときや、アプリの追加・更新ができなくなったときに、利用上限を確認できます。料金は料金ページ 、プラン変更・解約・請求書などの操作は料金と契約の運用 を参照してください。
まず、次の 3 つを確認すると、必要なプランを選びやすくなります。
同時に使えるアプリ数 — 同時に利用する Web アプリの数です。保存してあるアプリの総数とは異なりますアプリを作る・管理する人数（Developers） — Owner / Admin / Developer の人数枠です。アプリを使うだけの App User は数えませんストレージ — 保存したファイルなどの合計容量です。データベースの容量は別に扱います
Starter Plus Team 同時に使えるアプリ数 1 2 4 Developers（Owner / Admin / Developer の席） 1 2 3 定期実行 実行回数 / 月 1,000 5,000 15,000 定期実行ジョブの設定数 / アプリ 3 5 10 定期実行できる最短の間隔 60 分 15 分 5 分 定期実行 1 回あたりの実行時間上限 3 分 5 分 10 分 ビルド回数 / 月 100 回 300 回 1,000 回 ビルド時間 / 月 500 分 1,500 分 5,000 分 同時ビルド数 1 1 2 日次バックアップの保存数 1 世代 3 世代 7 世代 指定した時刻に復元できる期間（PITR） 24 時間 7 日 14 日 ストレージ（ワークスペース合計） 10 GB 20 GB 50 GB データベース容量（DB ごと） 固定上限なし 固定上限なし 固定上限なし 優先起動 — ○ ○ カスタムドメイン — — 最大 10 件 アクセスログの閲覧範囲 30 日 90 日 180 日 アプリログの閲覧範囲 7 日 14 日 30 日
Enterprise プランは準備中です。上記を超える要件はお問い合わせ ください。
アプリを実行できる形に準備する処理を「ビルド」、決まった時刻や間隔で動かす処理を「定期実行ジョブ（cron）」と呼びます。バックアップの「1 世代」は、保存されたバックアップ 1 回分です。
アプリの利用者数（App User）は無制限
有料プランではアプリの保存数は無制限。上限がかかるのは「同時に動かせる数」だけです。トライアル中は保有数と同時に動かせる数にそれぞれ上限があります（下の「トライアル中の制限」を参照）
認証・アクセス制御・IP 制御
日次バックアップ、手動スナップショット（1 アプリ 5 回/日）、PITR、バックアップのダウンロード
Managed SQLite（アプリ / ワークスペース単位で DB を分離）
14 日間の無料トライアル（1 アカウント 1 回）。Starter / Plus はカード登録なしで開始できます
静的サイトとしてデプロイ済みのアプリを除き、作成できるアプリは 3 個までです。未デプロイのアプリやサーバーを使うアプリはこの上限に数えます。4 個目の作成は拒否されます
同時に動かせるアプリは、プランを問わず 3 個までです。トライアル中はこの上限がプランの稼働アプリ枠となり、追加アプリのアドオンも加算されません。そのため Team は 4 個から 3 個に減ります
ビルドは 1 日 7 回までです
ビルドはトライアル期間の通算で 30 回までです。この 30 回は通算のため、月が変わってもリセットされません
ビルド時間と同時ビルド数は、ご契約プランの値がそのまま適用されます
有料プランへ移行すると、保有アプリ数の上限は外れ、稼働アプリ枠はプランの値と追加アプリのアドオンを合わせた数に戻ります
上限 挙動 同時に使えるアプリ数 空き枠が必要なアプリの起動・デプロイができなくなります。稼働中のアプリには影響しません。枠が空いていない状態でスリープ中のアプリにアクセスすると、起動できないことを知らせる案内ページ（HTTP 503）が表示されます。優先起動を設定していないアプリの枠は、最後のアクセスから約 5 分で解放されます Developers 開発者の席を使う招待や、新たに席を使うロール変更ができなくなります。App User の招待や、使用する席数を増やさないロール変更はできます 定期実行 実行回数 当月の残りの実行はスキップされ、翌月にリセットされます 定期実行ジョブの設定数・間隔・実行時間 keelson.yaml がプランに合わない場合、デプロイできません。AI エージェントに、表示された上限に合わせて設定の見直しを依頼しますビルド回数 / ビルド時間（月間） 新しいビルドが拒否されます。どちらの枠も翌月にリセットされます。トライアル中の通算 30 回はリセットされないため、続けるには有料プランへの移行が必要です 同時ビルド数 上限に達している間、実行中のビルドが終わるまで新しいビルドは拒否されます ストレージ すぐには停止しません。超過時はサポートから連絡します データベース容量 プランごとの固定上限はありません。ただし、基盤側の技術上限は適用されます。また、平常の業務利用を著しく超える負荷や、プラットフォームの安定運用・他のお客様の利用・当社の合理的な運用コストに影響を及ぼす利用を検知した場合、アプリの実行を制限または停止することがあります。緊急時は事前の通知なく制限することがあります
有料契約中は、必要な枠や容量を追加できます。追加の操作や請求は料金と契約の運用 を参照してください。トライアル中は追加できません。
アドオン 単位 追加ストレージ +50 GB 同時に使えるアプリ数の追加 +1 枠 追加 Developers +1 席
Web アプリが起動・利用のために確保する枠の数です。通常のアプリは、最後のアクセスから約 5 分で枠が自動的に解放されます。アクセスが続いている間は枠を使います。
スリープ中・サスペンド中のアプリは枠を消費しません
定期実行ジョブだけのアプリは枠を消費しません（Web アプリとは別に実行されます）
静的サイトは枠を消費せず、作成できる本数にも上限はありません
優先起動 を設定したアプリは、アクセスがなくても枠を常に予約します。Plus 以上で、利用できるアプリ枠の合計より 1 本少ない数まで設定できます。トライアル中は上記のトライアル用の枠数が基準になります
起動と停止の仕組みはアプリが動くタイミング を参照してください。
アプリを作る・管理する人の人数枠を「Developers 席」と呼びます。Owner / Admin / Developer のメンバーが 1 人につき 1 席を使います。App User は数えません。
Owner / Admin / Developer の招待は、相手が受け入れる前でも、有効期限内は 1 席を予約し、使用量に含まれます。不要になった招待は取り消すと予約が外れます。
操作によって異なる席数の数え方
Owner / Admin / Developer として新しく招待するときは、これらのロールの参加済みメンバーと、有効期限内の未受諾の招待を合計して上限を判定します。招待の受諾時や、新たに開発者の席を使うロール変更では、これらのロールの参加済みメンバーだけを数えます。既に席を使っているメンバーのロール変更など、席数が増えない変更はこの上限で制限されません。
デプロイ用に保存したアプリのファイル（アーティファクト）、Files / Media SDK のファイル、スナップショットの合計容量です。ワークスペース全体で集計し、ログは含みません。Managed SQLite の容量はこの集計枠とは別に管理され、プランごとの固定上限はありません。
画面の表示やデータの保存など、アプリに送る 1 回のリクエストには時間の上限があります。長い処理がある場合は、AI エージェントに上限内で完了する処理方法を相談できます。
項目 上限 応答を開始するまで（最初のレスポンスヘッダ） 120 秒。超えるとタイムアウト（HTTP 504） 1 リクエストの合計（結果を少しずつ返すストリーミングを含む） 300 秒 ストリーミングで次のデータを返すまでの間隔（チャンク間隔） 120 秒
タイムアウトが表示されても、アプリ側では保存などの処理が完了している場合があります。AI エージェントには「同じ操作を繰り返しても、申請や注文が二重に登録されないようにして」と依頼してください。
技術的には、HTTP 504 が返ってもアプリ側の処理が取り消されたとは限りません。Keelson は POST リクエストを自動再送しませんが、利用者やクライアントが再送する可能性があります。そのため、同じリクエストを繰り返しても結果が重複しない実装が必要です。
定期実行ジョブの時間上限は上のプラン別一覧、ビルドの時間上限は keelson.yaml リファレンス を参照してください。
料金と契約の運用 プランを変更したいとき、支払い方法や請求書を確認したいとき、Keelson の利用を終了したいときの手順を案内します。各プランの数値上限はプランと制限 、料金は料金ページ を参照してください。
必要な権限 : Owner または Admin。ワークスペースの削除は Owner だけ場所 : コンソールの「設定」→「課金と使用量」。ワークスペースの削除は「設定」→「危険な操作」
各アカウントは 1 回だけ 14 日間の無料トライアルを使えます。Starter / Plus はカード登録なしで開始でき、終了までにカードを登録しなければ課金されずに自動終了 します。Team はトライアル開始時にカード登録が要ります（期間中に解約すれば課金なし）
カード登録済みの場合、トライアル終了日が初回請求日になり、以降は契約日ベースで毎月請求されます
トライアルを使い切ったアカウントが 2 つ目のワークスペースを作る場合は、決済完了と同時に課金が始まります
通貨は請求先の国で決まります（日本は JPY 税込、それ以外は USD 税抜）。初回契約で固定され、後から変えるにはサポートへの連絡が要ります
請求書払い・銀行振込は未対応です
利用者（App User）の人数は料金に影響しません。
トライアル中は、保有アプリ数・同時に動かせるアプリ数・ビルド回数に、プラン共通の上限があります。具体的な数値と数え方は、トライアル中の制限 で確認できます。
終了時の状態 起きること カード登録済み そのまま有料プランに移行し、初回請求が発生する。保有アプリ数の上限は外れ、稼働枠はプランの値に戻る カード未登録（Starter / Plus） 課金されずに自動終了する。以後、新しいデプロイ・アプリの起動・定期実行はブロックされる。アプリとデータはすぐには削除されない（解約後のアプリとデータ ）
トライアル中のプラン変更は、アップグレード・ダウングレードとも直ちに適用され、料金は発生しません。
「課金と使用量」→「プラン変更」から選びます。確定前に金額が表示されます。
変更 適用 請求 アップグレード 直ちに 現在のプランの未使用期間分を差し引き、新しいプランの残り期間分を変更時に請求する。次回の請求日からは新プランの満額 ダウングレード 現在の請求期間の終わりに 日割り精算はしない。それまでは現在のプランのまま使える
ダウングレードは予約として表示され、「予約を取り消す」で切り替え前なら取り消せます。
現在の使用量が変更先の上限を超えている場合は警告が出ます。超えたまま切り替えると、次のようになります。
同時に使えるアプリ数 : スリープ中のアプリは、使用量が上限内に減るまで起動できないDevelopers 席 : 上限内に収まるまで、Developer 以上のロールでの招待や、App User から Developer 以上への変更ができない定期実行の回数 : 当月の残りはスキップされるストレージ : 超過してもすぐには止まらない「ソフト上限」です。デプロイ時に警告が出て、サポートから連絡します。継続的に大きく超過している場合は制限の対象になりますカスタムドメイン （Team のみ）: 登録済みのものは残るが、追加・再登録ができない
「課金と使用量」→「アドオン」で、追加アプリ枠（+1）、追加 Developers 席（+1）、追加ストレージ（+50 GB）を数量で指定します。トライアル中は変更できません （トライアル終了後に追加できます）。増やした分は、残りの契約期間に応じた金額が登録済みの支払い方法へすぐに請求されます。減らした場合の差額は次回以降の請求に充当されます。
「課金と使用量」の「請求書」に最近の請求書が並び、各行から Stripe の請求書ページと PDF を開けます。
支払い方法の変更、請求先情報の編集、過去の請求書の一覧は、「課金を管理」ボタンから開く決済サービス Stripe の契約管理画面（カスタマーポータル、別タブ）で行います。ポータルで解約もできますが、Keelson のコンソールから解約する方が、終了日と影響を確認したうえで進められます。
決済に失敗した場合（支払い遅延）は、Stripe が再試行する間、サービスは通常どおり使えます。再試行が終わっても支払われないと契約が停止し、新しいデプロイ・アプリの起動・定期実行がブロックされます。「支払い方法を更新」から更新してください。
利用を終了する場合は、契約が終了するまでに、必要なデータを取り出します。 ワークスペースやアプリを削除する場合は、削除操作の前に行います。解約の申し込み後も契約終了日までは利用できるため、その間に準備できます。
データ 取り出し方 Managed SQLite のデータ コンソールのアプリ画面「復元ポイント」から、復元可能な期間内の時点を選んでダウンロード。データを書き出したファイル（SQLite の dump）を取得できます。契約終了後の猶予期間中もダウンロードできます Files SDK のファイル アプリにファイル一覧とダウンロード処理を用意し、アプリが動いているうちに取り出します Media SDK のファイル アプリに保存したファイル ID からリンクを用意し、そのアプリを閲覧できるメンバーがログインして取り出します ソースコード Git。または「デプロイ」タブの各デプロイからダウンロード 環境変数とシークレット シークレットの値はコンソールに表示されません。必要なら元の管理場所から控えます アクセスログ・アプリログ 「ログ」タブからエクスポート（アプリログは最大 5,000 行）
Files / Media には、コンソールや CLI からファイルを一覧表示・ダウンロードする機能がありません。AI エージェントには「保存したファイルを一覧から取り出せる画面を作って。Files はダウンロード処理を、Media は保存済みの ID からリンクを用意して。アプリの閲覧権限がある人だけが使えるようにして」と依頼できます。取り出したファイルが開けることも確認します。使い分けはファイルとメディア で説明しています。
契約終了後はアプリを起動できなくなるため、Files / Media の取り出しは契約終了までに済ませます。
「課金と使用量」→「プランをキャンセル」から、終了日と影響を確認し、「キャンセルを確定」を選びます。
現在の請求期間の末日まではプランが有効なまま です。解約の申し込み後も終了日まで利用でき、残り期間分の返金もありません末日までは「再開」でいつでも取り消せます
末日を過ぎると、新しいデプロイ・アプリの起動・定期実行がブロックされます。アプリやデータはすぐには削除されず、削除の予告と猶予期間があります
契約が終了した（解約が末日を迎えた、未払いで停止した、トライアルがカード未登録で終了した）ワークスペースでは、アプリは起動できなくなりますが、すぐには消えません。
対象のアプリが見つかった時点で、Owner / Admin にコンソールとメールで削除の予告 が届きます。予告には削除予定日が書かれています
猶予は予告から 30 日 です。猶予中も利用制限は続きますが、コンソールにログインして DB のバックアップをダウンロードできます
猶予中に再契約（プランを選び直す）すると、予告は取り消され、アプリはそのまま残ります。アプリを残して使い続けたい場合は、この期間内に再契約します
猶予後、アプリは自動で削除されます。削除後の扱いは利用者が承認した削除と同じで、DB バックアップ・Files・秘密情報を含まない設定の記録が、通常の利用から切り離された状態で 7 日間保管されます。復元は保証されません
DB のバックアップは猶予期間中も取り出せます。Files / Media は契約終了までに取り出す必要があります（データの持ち出し ）。
削除予定日は予告で確認できます。契約終了後のデータの取り扱いと、終了までのエクスポートについては、利用規約の第20条 もご確認ください。
「設定」→「危険な操作」→「このワークスペースを削除」。Owner だけが実行でき、ワークスペース名を入力して確認します。
ワークスペースとすべてのアプリが削除され、メンバーはアクセスできなくなります。コンソールから削除を取り消すことはできません
各アプリの DB バックアップ・Files・秘密情報を含まない設定の記録は、通常の利用から切り離された状態で 7 日間保管されますが、復元は保証されません
削除するとログアウトします
有効な契約がある場合、削除時に契約のキャンセル処理も行われるため、先に解約する必要はありません。ただし、キャンセル処理に失敗する場合があるため、削除後に請求が続いていないことを Stripe のポータル（削除前に「課金を管理」から開けます）または請求書メールで確認してください
Keelson のアカウント自体は、コンソール右上のアカウントメニュー →「Account settings」→「Security」の Delete account から自分で削除できます。削除されるのは Keelson のアカウントで、ログインに使っていた Google / Microsoft のアカウントは削除されません。所属していたワークスペースのアプリやデータも残ります。
リファレンス Keelson Deploy Spec Spec version: 2026-09-02 / Raw text (AI向け): /ja/docs/reference/deploy-spec.txt
この文書は、Keelson にアプリをデプロイする際の対応ランタイム・制約・成立条件を定義する正本です。デプロイの可否判断は、この文書に従ってください。
クイックスタートや操作手順は デプロイする を参照してください。
Keelson におけるデプロイ成功とは、ビルドが完了することではありません。次の条件をすべて満たした場合にのみ、デプロイは成功とみなされます。
アプリのビルドが完了している
アプリのプロセスが起動している
ヘルスチェックに通過している
アプリ URL（https://<ワークスペース slug>--<アプリ slug>.keelson.run）が発行されている
アプリ URL にアクセスできる状態である
ビルドが成功しても、起動に失敗した場合やヘルスチェックに通らない場合は、デプロイ成功ではありません。
すべてのデプロイには keelson.yaml が必要です。プロジェクトのルートディレクトリに配置します。
最小構成:
db と db.mode（libsql または none）は必須です。
Flask などのフレームワークを使うアプリには本番用サーバーが必要です。本番環境向けの設定 を参照してください。
各フィールドの詳細は keelson.yaml リファレンス を参照してください。
アプリは作成時に 1 つの論理リージョンへ配置されます。リージョンの論理キーは jp-tokyo（日本）と us-oregon（米国西海岸）です。クラウド事業者のリージョン名ではなく、この表示名と論理キーを使います。
新規アプリでは keelson deploy --new --region <region>、または keelson.yaml のトップレベル region で配置先を指定できます。優先順位は CLI の指定、keelson.yaml、ワークスペースの既定リージョンの順です。rollout 中は一覧にあるリージョンでも新規作成に未開放の場合があり、未開放のリージョンを明示すると拒否されます。
リージョンはアプリ作成後に変更できません。既存アプリへ別のリージョンを指定しても移動は行われず、デプロイは拒否されます。別リージョンを使う場合は、新しいアプリとして作り直してください。
Keelson は、以下のランタイム上でのみアプリを実行できます。
ランタイム 言語 用途 python-slimPython 軽量。API、テキスト処理、自動化など python-mediaPython メディア処理向け。画像・動画ライブラリを含む node-slimNode.js 軽量。Web アプリ、API など node-mediaNode.js メディア処理向け。画像処理ライブラリを含む go-slimGo 軽量 go-mediaGo メディア処理向け
keelson.yaml の runtime フィールドで指定します。迷った場合は -slim から始め、メディア処理系ライブラリが必要になったら -media に切り替えてください。
slim — 言語ランタイムと標準ライブラリのみ。ビルドが速く、イメージサイズが小さいmedia — slim に加え、画像処理（Pillow、sharp 等）や動画処理に必要なシステムライブラリがプリインストールされている
特定のフレームワークに依存しません。command で起動でき、HTTP サーバーとしてリクエストを受け付けるアプリであれば動作します。
例: FastAPI、Flask、Express、Next.js、Hono、Gin など。
以下の言語・ランタイムはサポート対象外です。
Ruby
Java / Kotlin / Scala
PHP
Rust
.NET / C#
Elixir / Erlang
Swift
非対応ランタイムのアプリは、修正や変換を行っても Keelson へデプロイできません。
Keelson は固定されたビルド環境・実行環境を提供します。アプリはその環境上でビルドおよび起動できる必要があります。
OS: LinuxCPU: x86_64 (amd64)
アプリは非 root ユーザーとして実行されます。sudo、apt-get install、システムレベルの変更は実行できません。
使用できません。Keelson はランタイムを選択し、command で起動する方式です。Dockerfile の代わりに keelson.yaml でランタイムと起動コマンドを指定します。
パス 書き込み 永続化 用途 /data不可（Keelson も作らず、アプリからも作れない） 不可 アプリは UID 1000 で実行され、root 所有の / 直下にはディレクトリを作れません アプリディレクトリ 不可（書き込み先として使えません） 不可 ソースコード、依存関係 /tmp可（一時的） 不可 一時ファイル その他 不可 — —
ローカルファイルへの書き込みはすべてエフェメラルで、再起動・scale-to-zero で失われます
永続データの置き場所は 3 つだけです: Managed SQLite（db.mode: libsql）、Files SDK（アプリ内部の非公開ファイル）、Media SDK（利用者に配信する画像・添付）。いずれもパスではありません
/data のファイル SQLite は永続化されません。ファイル SQLite クライアントの使用はデプロイ時に検出され、db.local_sqlite で一時用途と宣言しない限り拒否されます
Web アプリは環境変数 PORT で指定したポートで HTTP リクエストを待ち受けてください
0.0.0.0 で listen する必要があります。127.0.0.1 や localhost ではリクエストが届きませんHTTPS 終端は Keelson が行います。アプリは HTTP で listen してください
Keelson は任意の OS パッケージ追加を前提とした環境ではありません。
-slim ランタイムには最小限のシステムライブラリのみ含まれます-media ランタイムには画像・動画処理に必要な一般的なライブラリが含まれますそれ以外のシステムライブラリが必要な場合、アプリは動作しない可能性があります
apt-get 等によるパッケージ追加はできません（非 root のため）
command で起動した単一プロセスが基本ですsystemd やデーモン管理は使えません
バックグラウンド処理が必要な場合は crons を使ってください（workers は廃止済みで、宣言するとデプロイが拒否されます）
言語ランタイムが対応していても、依存ライブラリやシステム要件によってはデプロイできない場合があります。
以下のパッケージマネージャで管理される純粋な言語パッケージは問題なくインストールできます。
Python: pip（requirements.txt）Node.js: npm（package.json）Go: go mod（go.mod）
依存関係はイメージのビルド時に Keelson が自動でインストールします（requirements.txt / pyproject.toml / package.json / go.mod を検出）。command ではインストールせず、アプリの起動だけを行ってください。command に pip install / npm install / go build があると、CLI の事前チェックが command_installs_dependencies でデプロイを止めます。
ビルドの制約: Node のロックファイルは package-lock.json のみ。公開レジストリのみ（private registry・認証付きインストール不可）。Go は CGO_ENABLED=0。ビルド対象は linux/amd64。ビルド時にシークレットは渡らない。上限 900 秒。
# Go (Keelson 側で deploy 時に `./app` がビルドされます)
一部のパッケージは、C ライブラリやシステムレベルの依存を必要とします。
-media ランタイムで動作するもの:動作しない可能性があるもの: ランタイムに含まれないシステムライブラリに依存するパッケージ
パターン 理由 apt-get install が必要非 root でパッケージ追加不可 特殊な C ライブラリに依存 ランタイムに含まれていない可能性 GPU を前提とした推論ライブラリ GPU インスタンス未提供 データベースサーバー（PostgreSQL、MySQL、Redis） 外部サービスとして接続は可能だが、Keelson 上での起動は不可 systemd やバックグラウンドデーモン前提 プロセスモデルが異なる
デプロイモードは選択するものではなく、command と assets という持ち物から自動的に決まる導出値です。CLI / API の出力は deploy_mode の生ラベルを返すため、対応表で読み替えてください。
呼称 deploy_mode 生ラベルcommandassets説明 Web アプリ containerあり なし 通常のアプリデプロイ 静的サイト edge-staticなし あり（fallback なし） 静的ファイルのみ SPA edge-spaなし あり（fallback あり） SPA（フォールバック付き） ハイブリッド hybridあり あり（fallback 必須） 静的ファイル + バックエンド API
Keelson がアプリのホスト上で予約する URL 名前空間は /__keelson/*/assets、/files、/static、/uploads、/api のような一般的なパスをプラットフォームが奪うことはありません。
/__keelson/* はプラットフォーム内部用ビルド出力の配信ルート直下に __keelson ディレクトリを出力しないでください。 予約パスを含むビルドはビルド時にエラーコード reserved_path_conflictそれ以外は予約されていません。 /assets/*（Vite の既定出力先）などのフレームワーク既定パスは、設定変更なしでそのまま配信されます。関連ルール: auth.endpoints のパスは /__keelson で始められません（/api/external/ または /api/webhooks/ で始める必要があります）。また slug に予約語は使えません。
主要フレームワークが既定で出力する静的パスの一覧です。いずれも /__keelson/* とは衝突しません 。参考情報であり、実測 = 本リポジトリで確認済み、それ以外は 要検証（知識ベースの推定。根拠として使わず、必要なら確認すること）です。
フレームワーク 既定の静的パス /__keelson と衝突状態 Vite（Vue / Svelte / React / Solid / Preact） /assets/*しない 実測 Remix v2 / VitePress /assets/*しない見込み 要検証 Angular /assets/*しない見込み 要検証 Next.js /_next/static/*しない見込み 要検証 Nuxt / SvelteKit / Astro /_nuxt/* · /_app/* · /_astro/*しない見込み 要検証 CRA / Django / Flask /static/*しない見込み 要検証
アプリの起動に必要な API キー、トークン、接続情報は、コードに直接埋め込まず、環境変数またはシークレットとして設定してください。
keelson.yaml の env — バージョン管理に含めてよい値コンソールのシークレット — API キーやトークンなど、コードに含めたくない値
必要な値が未設定の場合、アプリは正常に起動できないことがあります。
詳細は 環境変数とシークレット を参照してください。
変数名 説明 PORTアプリが listen するポート。読み取り専用で、自分で設定しない TZワークスペースのタイムゾーン。ワークスペース作成時にブラウザから自動決定される KEELSON_MODEKeelson 上で動作していることを示す印（値は keelson） KEELSON_APP_IDアプリの内部 ID KEELSON_WORKSPACE_IDワークスペースの内部 ID KEELSON_TENANT_IDKEELSON_WORKSPACE_ID の互換用別名（値は同じ）KEELSON_DEPLOY_ID現在のデプロイの内部 ID
旧 tenant 名の変数も互換のため受け付けます。撤去時期は未定です。
db.mode: libsql のときは KEELSON_DB_URL / KEELSON_DB_AUTH_TOKEN（別名 TURSO_DATABASE_URL / TURSO_AUTH_TOKEN）が追加で注入されます。KEELSON_ で始まる名前はプラットフォーム予約で、env や secrets には使えません。
Keelson のアプリは Cloud Run 上で動作し、通常運用中にも起動と停止が発生します。停止時にはプロセスへ SIGTERM が送られ、10 秒後に SIGKILL が送られます。本番用サーバーを使い、この時間内にドレイン処理を完了してください。
Flask: app.run() は Werkzeug 開発サーバーを起動します。ローカル用の __main__ エントリーポイントの中に残すことはできますが、debug=False でもデプロイ先のサーバーにしてはいけません。gunicorn を requirements.txt に追加し、次のコマンドを使います。
command : "gunicorn --bind 0.0.0.0:$PORT --workers 1 --threads 8 --timeout 0 --graceful-timeout 9 app:app"
Keelson は 1 vCPU のため、worker は 1 にします。graceful timeout を 9 秒にすると、10 秒の SIGTERM 猶予内に収まります。app:app はプロジェクトのモジュール名とアプリケーションオブジェクト名に置き換えてください。
Django: gunicorn で Django を起動します。
command : "gunicorn --bind 0.0.0.0:$PORT --workers 1 --threads 8 --timeout 0 --graceful-timeout 9 config.wsgi:application"
DEBUG は既定で無効にします。DEBUG=False の場合、Django 自身は静的ファイルを配信しません。whitenoise を MIDDLEWARE に追加し、STATIC_ROOT を設定して、collectstatic 済みの成果物を配信対象に含めてください。ALLOWED_HOSTS = ["*"] は維持してください。制限するとヘルスチェックが HTTP 400 になることがあります。config.wsgi:application はプロジェクトの WSGI モジュールに置き換えてください。
FastAPI / uvicorn: 0.0.0.0:$PORT にバインドし、worker 数は既定の 1 のままにします。
command : "uvicorn main:app --host 0.0.0.0 --port $PORT"
--reload は使わないでください。ファイル監視がメモリを消費し、アプリが二重起動することがあります。main:app はプロジェクトのモジュール名とアプリケーションオブジェクト名に置き換えてください。
Next.js: 開発サーバーではなく、ビルド済みのアプリを起動します。
package script は次のように設定します。
"start" : "next start -p $PORT"
package.json に "start": "next dev" がある場合、回避策を加えるのではなく、その script を修正してください。next dev は本番用サーバーではありません。
Node.js: Keelson は NODE_ENV を自動設定しません。keelson.yaml で本番モードを宣言してください。未設定の場合、Express などのフレームワークがスタックトレースを返すことがあります。
Go: ビルド済みバイナリを command: "./app" で起動します。ListenAndServe を停止処理なしで放置せず、signal.NotifyContext と server.Shutdown を使って新規リクエストの受付を止め、処理中のリクエストを 10 秒の猶予内に完了させてください。
既定値は本番で安全な向きにします。Python の DEBUG は false を既定にします。
DEBUG = os.environ.get( "DEBUG" , "false" ).lower() == "true"
true を既定にしてはいけません。
DEBUG = os.environ.get( "DEBUG" , "true" ).lower() == "true"
デバッグ画面は、データベースの認証トークンを含む環境変数を表示することがあります。
Keelson が値 keelson で設定する KEELSON_MODE を使って、プラットフォーム上での実行を判別します。
ON_KEELSON = os.environ.get( "KEELSON_MODE" ) == "keelson"
本番設定の不足を即時エラーにする検査は、ON_KEELSON が true の場合だけ適用してください。DEBUG をプラットフォーム判別に使うとローカルで起動できなくなるため、代用しないでください。
対象 制限 HTTP リクエスト 120 秒以内にレスポンスを開始（超過で 504）。ストリーミングは開始後、無通信 120 秒・合計 300 秒まで 定期実行ジョブ（cron） 1〜600 秒（既定 300 秒。プラン上限がそれより低ければ切り詰め） ビルド 900 秒
アプリから外部 API やサービスへの通信はデフォルトで可能です
症状 原因 対処 ビルド成功、起動後すぐ落ちる 0.0.0.0 で listen していないhost="0.0.0.0" を明示ポートに接続できない ポート番号がハードコード 環境変数 PORT から読み取る モジュールが見つからない 依存マニフェストに記載がない、またはイメージのビルド時にインストールが失敗 ビルドログを確認し、依存を requirements.txt または package.json に記載する ネイティブモジュールのビルド失敗 システムライブラリ不足 -media ランタイムに変更、または依存を見直す起動コマンドが見つからない エントリポイントのパスが間違い ファイル名・パスを確認 事前チェックが command_installs_dependencies で止まる command に pip install / npm install がある削除して起動コマンドだけにする 検証が db 不足で止まる db.mode が無いlibsql または none を宣言するビルドが reserved_path_conflict で失敗 ビルド出力の配信ルート直下に __keelson（予約 URL プレフィックス）がある ディレクトリ名を変更（予約は /__keelson/* のみ、それ以外はアプリのもの） 定期ジョブが一度も発火しない（エラーも出ない） スケジュールがアプリのプロセス内にある（in-process スケジューラ）。予定時刻にはアプリがゼロにスケールしている crons エントリとして宣言するUI は成功と表示されたのにメール・通知が届かない レスポンスを返した後に回した処理が走っていない レスポンスを返す前に済ませる。または DB のキュー表に書いて crons エントリでドレインし、最大 1 間隔ぶん遅れることをユーザーに伝える
ビルドログを確認 — 依存関係のインストールが成功しているか実行ログを確認 — 起動時エラーやランタイムエラーがないかkeelson.yaml を確認runtime、command、env の設定が正しいか
AI エージェントは、Keelson へのデプロイ時に以下の順序で判断してください。
ランタイム確認 — アプリの言語がこの仕様の対応ランタイムに含まれるか確認する依存関係確認 — ネイティブ依存やシステムライブラリの要件が制約内か確認するkeelson.yaml 確認 — ファイルの有無と設定内容の妥当性を確認する。なければ作成する環境変数確認 — 必要な環境変数やシークレットが不足していないか確認するデプロイ実行 — CLI または Skill を使ってデプロイを実行する完了確認 — ビルド完了だけでなく、起動・ヘルスチェック・URL アクセスまで確認する失敗時対応 — ログを確認し、修正可能な範囲で対処する。制約違反がある場合は理由を明示して停止する
非対応ランタイムの場合は、デプロイを試行しない。理由を明示して停止する
必須設定が不足している場合は、必要事項を提示する
ビルド成功のみで完了扱いにしない
起動失敗時は必ずログを参照する
Web 上の最新 Keelson Deploy Spec（この文書）
Web 上の最新 CLI バージョン情報
Skill 同梱版の仕様
一般知識・推測
Web 上の正本と Skill 同梱の情報が矛盾する場合は、Web 上の正本を優先してください。
keelson.yaml
keelson.yaml はプロジェクトルートに置くデプロイ設定ファイルです。ランタイム、起動コマンド、環境変数、データベース、定期実行ジョブ、静的アセットなどを定義します。
デプロイ時に Keelson はこのファイルを読み、ビルドと実行環境を決めます。入門は keelson.yaml の設定 を参照してください。
フィールド 型 必須 既定値 説明 slugstring はい — アプリの識別子。アプリ作成時に使われる workspacestring — nullプロジェクト単位の CLI 操作で使う既定ワークスペース。ワークスペースの slug を推奨。所属が 1 つだけなら CLI が自動選択するため書かなくてよい。明示した --workspace はこの値より優先し、apps list の一覧は絞り込まない descriptionstring — nullアプリの説明（300 文字以内） typestring — nullアプリ種別。"web" のみ runtimestring はい — 実行環境。対応ランタイム を参照 commandstring | list 条件付き — 起動コマンド。cron のみ・静的のみの構成では省略可 envmap — {}秘密でない環境変数 dbobject はい — データベースとローカル SQLite の方針 cronslist 条件付き []定期実行ジョブ。command も静的 assets も無い場合は必須 assetsobject — null静的アセット配信 healthobject — nullデプロイ時ヘルスチェックのパス secretsobject — {}シークレットの宣言と必須条件 authobject — null対話ログインを通さない外部向けエンドポイント emailobject — {}受信メール verifystring | list — []デプロイ後に追加で検証するパス regionstring — null新規アプリの配置リージョン storageobject — {}廃止された disk_id だけを受理する互換ブロック
廃止されたトップレベルキー databases と workers は、値が null や空リストでも拒否されます。永続的な関係データは db.mode: libsql、時刻起点の処理は crons で表現してください。
旧名のトップレベル tenant も workspace の互換用別名として受け付けます。撤去時期は
未定です。両方を書く場合、生の文字列値が完全に一致している必要があります。
上の表にないトップレベルキー(build、port、scaling など)や、各オブジェクトの中の未知のキーは拒否されます。独自のキーを足せる拡張可能な形式ではありません。crons / email / secrets / storage に null を書くと省略と同じにはならず拒否されます。省略したいときはキーごと書かないでください。
keelson.yaml は CLI(YAML 1.2)と API(YAML 1.1)の 2 つの実装が解析します。引用符のないスカラーの型解決が食い違うため、次の文字列は引用符で囲む必要があります。囲まないと string_value_not_portable で拒否されます。
数字で始まる値(slug: "123-app")
日本語など ASCII 英字以外で始まる値(description: "営業向けアプリ")
- で始まる値。コマンドをリストで書くときのフラグ(command: [python, app.py, "--port", "8080"])YAML が真偽値や null と解釈する語(yes / no / on / off / true / false / null とその大文字違い)
: を含む値(":memory:")
英字で始まる通常の値(python app.py、my-app、dist)は引用符なしで書けます。env だけは規則が強く、値をすべて引用符かブロックスカラー(| / >)で書きます(env を参照)。
アプリの識別子です。アプリ作成時の公開 URL（https://<ワークスペース slug>--<slug>.keelson.run）の一部になります。
ルール:
小文字英数字とハイフン（a-z、0-9、-）のみ
1〜63 文字
先頭と末尾は英数字
ハイフンの連続（--）は不可
予約語: admin api assets auth console health static www
public_slug は廃止された互換フィールドで、無視されます。
アプリが誰向けで何をするかを示す 1〜2 文です。
description : "営業チーム向けの日報・週報作成アプリ。週次サマリーを自動集計します"
前後の空白を除いて 300 文字（Unicode コードポイント）以内。超えるとデプロイが失敗します。アプリ台帳の説明欄に表示され、説明がまだ空のときだけ 適用されます。コンソールで編集した説明がデプロイで上書きされることはありません。
アプリ種別です。省略可能です。
指定できる値は web だけです。type: web を指定すると、assets だけで command なしのデプロイができます。
制約:
type: web と crons は併用できませんWeb アプリと cron を両方持つアプリでは type を省略します
実行環境です。静的サイトだけのデプロイでも必須ですが、静的サイトではビルドに使われません。静的サイトは手元や CI でビルド済みの assets.dir をそのまま配信します。
ランタイム 言語 用途 python-slimPython 軽量。API、テキスト処理など python-mediaPython 画像・動画処理（Pillow、opencv、ffmpeg 関連など） node-slimNode.js 軽量 node-mediaNode.js 画像処理（sharp など） go-slimGo 軽量 go-mediaGo メディア処理
迷ったら -slim から始め、メディア処理系ライブラリが必要になったら -media に切り替えます。
コンテナ型とハイブリッド型では、依存パッケージはビルド時に Keelson が自動でインストールします。静的サイト(command なし)ではこの処理は走らず、アップロードされるのも assets.dir と keelson.yaml だけです。command には起動コマンドだけを書いてください。command に pip install / npm install / go build を含めると、CLI の事前チェックが command_installs_dependencies でデプロイを止めます。
ランタイム 検出するファイル ビルド時に実行される処理 python-*requirements.txtpython -m pip install --user -r requirements.txtpython-*pyproject.toml（[project] または [build-system] あり）。requirements.txt がない場合のみpython -m pip install --user .node-*package-lock.json / package.jsonnpm ci（ロックファイルあり）または npm install、続けて npm run build --if-presentgo-*go.mod / go.sumgo mod download、go build -o /workspace/app .（command: "./app" で起動）
ビルドの制約:
requirements.txt と pyproject.toml が両方あるときは requirements.txt だけを使います。pyproject.toml 側だけに書いた依存や自作パッケージのインストールは行われないので、必要なものは requirements.txt に含めてくださいインストール可能な Python の pyproject.toml には、対応するロックファイル（requirements.txt / poetry.lock / uv.lock / Pipfile.lock）のいずれかが必要です
Node のビルドは npm のみを使い、package-lock.json が必要です。pnpm-lock.yaml / yarn.lock だけの場合は事前チェックが lockfile_unsupported でデプロイを止めます。package-lock.json と併存している場合はそのまま残してかまいません
サードパーティ依存を宣言する Go モジュールには go.sum が必要です。標準ライブラリだけを使うモジュールには必要ありません
公開レジストリからのみ取得できます。private registry、git+ssh 依存、認証が必要なインストールは失敗します
Go は CGO_ENABLED=0 でビルドされます
ビルド対象は linux/amd64 のみ
ビルド時にシークレットは渡りません
ビルドの上限時間は 600 秒
アプリ起動時に実行するコマンドです。文字列（シェル経由）またはリスト（直接実行）で指定します。
ルール:
command、crons、静的 assets のいずれかが必要ですcron だけのアプリに command は不要です
type: web で assets がある静的サイトに command は不要です空文字列・空リストは「起動コマンドなし」として扱われます。通常の Web アプリでは指定が必要です。crons[].command は空にできません
依存関係のインストールは含めません（依存関係のインストール を参照）
秘密でない環境変数をキーと値で定義します。値はすべて文字列です。
PORT は Keelson が実行時に設定します。env に書いても無視されます。
値は必ず引用符で囲むか、ブロックスカラー(| / >)で書いてください。 引用符のない値は env_value_not_string で拒否され、デプロイは開始されません。数値・真偽値も同様です。
引用符が必須なのは、keelson.yaml を CLI（YAML 1.2）と API（YAML 1.1）の 2 つの実装が解析しており、引用符のないスカラーの型解決が食い違うためです。たとえば K: 0o123 は経路によって "83" にも "0o123" にもなります。引用符で囲めば両方で同じ文字列になります。
引用符を付けないキーは、英字か _ で始まり、英数字と _ だけで構成される必要があります。NODE_ENV や DB_POOL のような通常の環境変数名はそのまま書けます。
次の語は YAML 1.1 で真偽値・null と解釈されるため、引用符なしでは使えません:
yes Yes YES no No NO true True TRUE false False FALSE on On ON off Off OFF null Null NULL
ハイフンを含む名前や予約語は、キーを引用符で囲みます。
KEELSON_ で始まるキー（大文字小文字を区別しない）はプラットフォーム予約で、env には設定できません。env の重複宣言、env 内のキー重複、YAML の merge key（<<）も拒否されます。
秘密の値は env ではなく secretsenv と同じ名前のシークレットが設定されている場合はシークレットの値が優先され、env の変更は反映されません。
データベースの扱いを選びます。db と db.mode は必須です。
フィールド 型 必須 既定値 説明 modestring はい — libsql または none。旧名 turso は libsql に正規化migratestring — nullデプロイ時に実行するマイグレーションコマンド。libsql のときのみ有効 auto_adoptboolean — false旧設定との互換のため受理されるが、現在は何もしない。DB を引き継ぐ機能ではない local_sqliteobject — null再生成可能な一時 SQLite ファイルの明示宣言
mode意味 libsqlKeelson がアプリ専用の Managed SQLite を用意し、KEELSON_DB_URL / KEELSON_DB_AUTH_TOKEN（別名 TURSO_DATABASE_URL / TURSO_AUTH_TOKEN）を注入する noneKeelson は DB を管理しない。DB 不要のアプリ、または外部 DB を使うアプリ
mode: libsql は契約も接続設定も不要で、scale-to-zero に対応します。永続的な関係データにはこれを推奨します。
PostgreSQL、MySQL、自前の libSQL を使う場合は mode: none にし、接続情報をシークレットで渡します。外部 DB の接続情報を Keelson が注入することはありません。
/data のファイル SQLite を永続化するモードはありません。ファイル SQLite を使うコード（sqlite3、better-sqlite3 など）はデプロイ時に検出され、local_sqlite の宣言がなければ拒否されます。
db.migrate は、新しいイメージでトラフィックを切り替える前に 1 回だけ実行されるコマンドです。
migrate : "python migrate.py"
mode: libsql のときのみ有効。文字列で指定しますコンテナ型・ハイブリッド型でのみ実行されます。静的サイトにはコンテナがないため、宣言しても実行されません
候補リビジョンがヘルスチェックを通った後、トラフィック切り替えの前に、デプロイ対象のイメージ上で実行されます。アプリの起動コードは移行前のスキーマで動く必要があります
終了コードが 0 以外ならデプロイは deploy.runtime.migration_failed で失敗し、旧リビジョンが維持されます
毎回のデプロイで実行されるため、冪等に書きます（CREATE TABLE IF NOT EXISTS、ON CONFLICT DO NOTHING）
再生成できるキャッシュ用途のファイルだけを db.local_sqlite で宣言します。宣言してもファイルは永続化されません。
reason : "外部 API から再構築できる派生キャッシュ"
フィールド 型 必須 制約 policystring はい ephemeral のみpathslist はい 空でないこと。各パスは /tmp/ 配下か :memory: reasonstring はい 消えても問題ない理由
廃止された databases ブロックは常に拒否されます。
定期実行ジョブを定義します。各ジョブは Web サービスとは別のインスタンスで実行されます。
command : "python cleanup.py"
フィールド 型 必須 既定値 説明 namestring はい — ジョブ名。小文字英数字とハイフン、1〜63 文字、重複不可 schedulestring はい — 5 フィールドの cron 式 commandstring | list はい — 実行コマンド timeoutinteger — 300タイムアウト秒。1〜600 enabledboolean — truefalse にするとスケジュールされない
ルール:
1 アプリ最大 10 本。プランによりさらに少ない上限があります
type: web と併用できません別インスタンスで実行されるため、ローカルファイル（/data を含む）は Web と共有されません。共有する状態は db.mode: libsql に置きます
前回の実行が継続中なら、その回はスキップされます
スケジュールはワークスペースのタイムゾーンで評価されます
timeout の絶対上限は 600 秒。省略時は 300 秒ですが、プランの上限がそれより低ければプラン上限に切り詰められます
本数・最小間隔・timeout 上限のプラン別の値はプランと制限 を参照してください。
式 意味 0 * * * *毎時 0 分 */15 * * * *15 分ごと 0 3 * * *毎日 3:00 0 9 * * 1-5平日 9:00 0 0 1 * *毎月 1 日 0:00
* * * * *（毎分）は全プランの最小間隔より短いため拒否されます。実行の挙動と設計は定期実行ジョブ を参照してください。
workers（バックグラウンドワーカー / 定期ドレイン）は廃止されました。トップレベルに workers があると、値が空リストや null でも workers_not_supported で拒否されます。
同じ処理は crons で表現します。ドレイン型の処理は、短い間隔のスケジュールを 1 本立て、1 回の実行で未処理分を片付けて終了する形にします。
command : "python worker.py"
command : "python drain.py"
静的サイト、SPA、静的ファイル + バックエンド API（hybrid）の配信設定です。
フィールド 型 必須 既定値 説明 dirstring はい — アセットディレクトリ（プロジェクトルートからの相対パス） static_dirstring — nulldir の廃止された別名。両方ある場合は一致が必要fallbackstring 条件付き nullSPA 用フォールバック（例: index.html）。dir 配下の相対パス apistring — null（ハイブリッドでは実効値 /api）バックエンドへ転送するパスプレフィックス。command と assets の両方があるハイブリッドで省略すると /api が使われる
ハイブリッドでは api のパス配下がバックエンドへ転送され、それ以外は静的アセットとして配信されます。省略時のプレフィックスは /api です。別のパスにしたいときだけ指定します。
ルール:
dir に .. は使えませんapi は / で始まり、/ そのものではなく、/__keelson 配下でないことapi はトップレベルの command がある場合のみ有効assets と command の両方がある hybrid では fallback が必須
CLI はデプロイ用アーカイブを作るとき、パスに .git、.venv、__pycache__、.pytest_cache、node_modules、dist、build、.idea、.vscode、.DS_Store を含むものを除外します。宣言した assets.dir とその祖先は免除されるので、dist などのビルド出力は含まれます。ただし assets.dir 配下でも dist/node_modules/** のように除外名に再び一致するものは除外されます。.git、シンボリックリンク、通常ファイル以外、--secrets-from-env-file で指定したファイルは名前によらず常に除外されます。CLI はそのプロジェクト相対パスだけを、秘匿値を含めず、自動除外される .keelson-config/previous-secrets-files.json に保存します。
env 系のファイル（最後の要素が .env で始まるか終わるもの。.env、.env.production、.envrc、.secrets.env など）は assets.dir の中でも除外されます。
プロジェクト固有の除外は、プロジェクト直下の .keelsonignore に書きます。gitignore に似た記法（1 行 1 パターン、# コメント、/、末尾 /、*、?、**、[abc]、[a-z]、先頭 ! の否定）が使え、最後に一致した行が優先されます。!.env.production で env ファイルを意図的に再同梱できますが、.git、組み込み除外、.keelsonignore 自身、--secrets-from-env-file のファイルは再同梱できません。.gitignore は読みません。
assets があり、文字列形式・配列形式のどちらの command もない静的アプリでは、既定で assets.dir 配下のファイルと keelson.yaml だけをアーカイブします。assets.dir へ到達するため、その祖先ディレクトリは走査できます。外側のファイルを意図的に戻すには .keelsonignore の先頭 ! を使います。ディレクトリと中身を戻すには !keep/ と !keep/** の両方が必要です。コンテナ型・ハイブリッド型ではビルドに必要なソースを従来どおり同梱します。
assets.dir: . や同じ意味の ./ は避けてください。プロジェクト直下が公開 assets になるため、アーカイブされた全ファイルが配信され得ます。CLI はデプロイ前に警告しますが、この設定は禁止しません。
keelson deploy --check はアーカイブ内容と主要な設定を手元で検証しますが、API 側の検証より緩い項目があります(assets / crons / auth / email / secrets の未知キー、cron 式の妥当性、verify のパス形式など)。--check が通っても、デプロイ時に deploy.config.invalid で止まることがあります。
アップロード前に keelson deploy --check --json を実行し、archive.excluded、archive.excluded_env_files、archive.secret_like_files、archive.embedded_credentials、archive.unscanned_files、archive.unscanned_binary_count を確認してください。embedded_credentials は値を出さずパスと種別だけを報告します。プレビュー資格情報やアプリ用トークンが検出された場合はアップロードを停止し、Webhook 署名鍵のみの一致であれば警告を表示して続行します。16 MiB を超えるファイルとバイナリ判定されたファイルは本文検査をせず、除外ファイルも検査対象外です。secret_like_files は credentials.json や *.pem のような秘匿値を含みそうな名前に加え、過去に --secrets-from-env-file で指定したものの今回は除外指定しなかった実在ファイルも警告します。prod-secrets.txt のような env 系でない名前も対象で、警告されたファイルは除外されず同梱されます。
ファイル名にコンテンツハッシュが入った JavaScript / CSS（例: index-B7hK2mQ1.js）は 1 年間キャッシュされます。Keelson は、ASCII 英数字と _ からなり英字と数字の両方を含む 8〜64 文字の末尾セグメントをハッシュと認識します。HTML、style.css や app.js のようなハッシュなしのファイル、画像などは、アクセスのたびに ETag で更新を確認します。
静的サイト（edge-static / edge-spa）の再デプロイは、新しいファイルがエッジに反映されるまで 25〜30 秒かかります。
デプロイ時のヘルスチェックに使うパスです。/ が重い、DB に依存する、などの場合に軽量なエンドポイントを指定します。
省略時は / を確認します
/ で始まり、.. を含まず、/__keelson で始まらない 2048 文字以内のパスHTTP 2xx / 3xx / 404 で合格、それ以外の 4xx と 5xx で不合格。404 が通るため、合格は「起動した」ことの確認であり、そのパスが実装されていることの証明ではありません
候補リビジョンの内部 URL へ直接送られ、公開ホストや認証は経由しません。公開パスの検証は verify
アプリが必要とするシークレットと、必須の組み合わせを宣言します。値はここには書かず、コンソール、CLI、またはデプロイ時の env ファイルで設定します。
description : "OpenAI API key"
- name : ANTHROPIC_API_KEY
description : "Anthropic API key"
- any_of : [ OPENAI_API_KEY , ANTHROPIC_API_KEY ]
message : "AI プロバイダのキーを少なくとも 1 つ設定してください"
フィールド 型 必須 既定値 説明 itemslist — []シークレットの定義 items[].namestring はい — 名前。環境変数の形式(大文字英字か _ で始まり、A-Z0-9_ のみ、255 文字以内)で書く。KEELSON_ で始まる名前は予約 items[].descriptionstring — ""用途の説明。コンソールに表示される requiredlist — []設定済みシークレットに対して検証するルール
| required[].any_of | list | 条件付き | null | いずれか 1 つが設定されていればよい名前の空でないリスト |
| required[].all_of | list | 条件付き | null | すべて設定されている必要がある名前の空でないリスト |
| required[].message | string | — | "" | 未設定時に表示する案内 |
required の各エントリは any_of または all_of のどちらか一方だけを持ちます。参照できるのは items で宣言した名前だけです。
名前は値を設定するときに大文字に正規化され、required の照合は大文字小文字を区別します。name: api_key と書くと値は API_KEY として保存され、required の条件が満たされません。最初から大文字で書いてください。MY-KEY のようにハイフンを含む名前は宣言できても値を設定できません。
新しいアプリでは keelson deploy --new --secrets-from-env-file <path> で、アプリ作成・シークレット設定・初回デプロイを 1 回で行えます。既存アプリのシークレット変更は次のデプロイで反映されます。
Webhook の受信など、対話ログインを通さずに外部システムから呼ばれるエンドポイントを宣言します。
- path : /api/external/status
auth がある場合、endpoints は空でないリストが必須です各エントリはパス文字列、または path と省略可能な methods を持つオブジェクト
パスは /api/external/ または /api/webhooks/ で始まり、重複しないこと。/__keelson 配下は不可
パスは前方一致 です。/api/external/status は /api/external/status-extra にも一致します
methods を指定する場合は空でないリスト。省略時は全メソッドを許可。大文字小文字は区別しませんmethods が効くのは /api/external/ だけです。/api/webhooks/ には適用されず、メソッドを絞りたければアプリ側で判定します
「対話ログインを通さない」は「Keelson の認証が不要」という意味ではありません。宣言しただけでは外部から届かず、呼び出し側は Keelson が発行する資格情報を付ける必要があります。
パス 必要な資格情報 /api/external/...api スコープのアプリトークンを Authorization: Bearer で送る/api/webhooks/...webhook スコープのアプリトークンを X-Webhook-Secret ヘッダーで送るか、/api/webhooks/<secret>/... の形の URL を外部サービスに登録する
トークンの発行は keelson apps tokens create、URL の組み立ては外部連携 を参照してください。Stripe の署名だけを送る通常の Webhook や、アプリ独自の API キーだけを送るクライアントは、アプリに届く前に拒否されます。
これらのパスへのリクエストには X-Keelson-User-Id が付きません。Keelson の資格情報に加えて、アプリ側でも Webhook 署名や API キーによる検証を行ってください。
受信メールの設定です。
email.inbound.enabled は boolean で、既定は false です。受信メールを処理するにはコンテナが必要です。静的サイト(type: web + assets、command なし)で有効にすると、設定は受理されますがデプロイが deploy.config.invalid で失敗します。
デプロイ後の検証で追加で確認するパスです。既定では / だけを確認します。
単一のパスは文字列でも 1 要素のリストでも指定できます
最大 20 パス(前後の空白を除き、重複を除いた数)。各パスは / で始まり、// で始まらず、パス要素としての .. と制御文字を含まないこと
コンテナ / hybrid では公開ホスト経由で候補リビジョンから取得し、静的 / SPA では公開前にリリースマニフェスト上で解決します
どちらの種類でも、宣言したパスが 2xx / 3xx 以外（404 / 401 / 403 / 405 など）なら verification_declared_path_unreachable でデプロイに失敗します
verify: にはアプリ自身のログインを必要としないパスを書いてください。検証リクエストにはアプリのユーザー情報が付かないため、アプリが返す 401 / 403 も不合格です/ は verify: にも書かれていても従来どおり寛容です。API だけのアプリが / で 404 を返しても合格します
クライアント側ルーティングでしか到達できない画面など、/ から辿れないエントリを確認したいときに使います。
これは health.path とは別の判定です。health.path は候補リビジョンを内部 URL で直接確認し、プロセスが起動した証拠として 404 でも合格します。verify は宣言した公開パスが実際に配信できるかを確認するため、404 では不合格です。
新規アプリを作るときの配置リージョンを任意で指定します。
クラウド事業者のリージョン名ではなく、Keelson の論理キーを指定します。
論理キー 表示名 jp-tokyo日本 us-oregon米国西海岸
新規アプリでは CLI の --region、keelson.yaml の region、ワークスペースの既定リージョンの順で優先されます。明示したリージョンが未定義または新規作成に未開放の場合は、別リージョンへ切り替えずに拒否されます。
アプリのリージョンは作成時に確定し、後から変更できません。既存アプリと異なる region を指定したデプロイは拒否されます。別リージョンへ移す場合は、新しいアプリとして作り直してください。
storage は廃止された disk_id だけを受理します。値は無視され、永続ストレージや /data の同期を有効にしません。残っていたら削除してください。
フィールド 型 必須 既定値 説明 disk_idstring — null無視される旧識別子。小文字英数字とハイフン、1〜32 文字
デプロイモードは command、assets、fallback の有無から導出されます。直接は選べません。keelson status --json などの出力は deploy_mode の生ラベルを返します。
呼称 deploy_modecommandassetsfallback説明 Web アプリ containerあり なし — 通常のアプリ 静的サイト edge-staticなし あり なし 静的ファイルのみ SPA edge-spaなし あり あり フォールバック付き静的ファイル ハイブリッド hybridあり あり 必須 静的ファイル + バックエンド API
ルール 内容 実行面が必要 command、crons、静的 assets のいずれかを指定するtype: web は cron 不可type: web と crons を併用しない静的サイトにはコンテナがない command のない静的サイト・SPA では、crons、db.migrate、email.inbound は動かない。宣言が受理されても実行されない(email はデプロイ失敗)ので、これらが要るならコンテナ型かハイブリッドにするworkers は廃止crons で書き直すdb.migrate は libsql のみdb.mode: libsql が必要ローカル SQLite は一時領域のみ db.local_sqlite.paths は /tmp/ 配下か :memory:assets.api にはバックエンドが必要トップレベルの command を設定する hybrid には fallback が必要 assets と command が両方あるとき assets.fallback を設定する
description : "顧客と案件を管理する社内 CRM"
migrate : "python migrate.py"
手元で npm run build などを実行して dist を作ってからデプロイします。Keelson 側ではビルドしません。
command : "python report.py"
Web アプリが pending 行を Managed SQLite に書き、cron が別インスタンスで処理します。共有する状態はローカルファイルではなく db.mode: libsql に置きます。
command : "python drain.py"
command : "node server.js"
- name : STRIPE_WEBHOOK_SECRET
description : "Stripe の Webhook 署名シークレット"
- all_of : [ STRIPE_WEBHOOK_SECRET ]
- path : /api/webhooks/stripe
Stripe に登録する URL には webhook スコープのアプリトークンを含めます(https://<host>/api/webhooks/<token>/stripe)。methods は Webhook には適用されないので、POST 以外を拒否したければアプリ側で判定します。
Keelson がデプロイ時に Linux 向けにビルドし、バイナリを ./app に置きます。
原因 対処 db または db.mode がないdb.mode を libsql か none で宣言する廃止された databases がある 削除する。永続データは Managed SQLite、一時 SQLite は db.local_sqlite で宣言 workers がある（workers_not_supported）削除して crons で書き直す command に pip install / npm install がある（command_installs_dependencies）削除する。依存はビルド時に自動インストールされる 依存マニフェストがない（missing_dependency_manifest） Go ではプロジェクトルートに go.mod を置く。Python または Node.js では、外部ライブラリを使う場合に適切なマニフェストを置く。標準ライブラリだけなら不要 runtime と command の言語が合わない（runtime_command_mismatch）ランタイムを合わせるか、起動コマンドを直す env の値が引用符なし（env_value_not_string）すべての値を引用符で囲む（数値・真偽値も） 環境変数名が KEELSON_ で始まる 名前を変える。この名前空間はプラットフォーム予約 local_sqlite.paths が /tmp/ の外/tmp/、:memory:、または Managed SQLite を使うcommand、crons、静的 assets のどれもないいずれかを追加する crons[].timeout が 600 を超える600 以下、かつプランの上限以下にする assets.api が / で始まらない/api のような絶対パスにするhybrid で assets.fallback がない index.html などを設定するビルドが reserved_path_conflict で失敗 ビルド出力直下の __keelson ディレクトリを改名する
環境変数一覧 Keelson がアプリのコンテナに設定する環境変数の一覧です。いずれも keelson.yaml の env には書きません。KEELSON_ で始まる名前はプラットフォーム予約で、env / secrets には使えません。
変数 内容 PORTアプリが listen するポート。読むだけで、設定しない TZワークスペースのタイムゾーン（例: Asia/Tokyo） KEELSON_MODEkeelson。「Keelson 上で動いているか」の判定に使う。ローカルでは未設定KEELSON_APP_IDアプリの内部 ID KEELSON_WORKSPACE_IDワークスペースの内部 ID KEELSON_TENANT_IDKEELSON_WORKSPACE_ID の互換用別名（値は同じ）KEELSON_DEPLOY_ID現在のデプロイの内部 ID KEELSON_APP_URLアプリの公開 URL（https://<ws>--<app>.keelson.run）。絶対 URL が必要な場面で使う。ホストを解決できる場合に設定される KEELSON_DIRECTORY_BASE_URLDirectory API のベース URL。Identity SDK が使う。KEELSON_APP_URL と同じ条件（ホストを解決できる場合）で設定される
旧 tenant 名の変数も互換のため受け付けます。撤去時期は未定です。
変数 条件 内容 KEELSON_DB_URLdb.mode: libsqlManaged SQLite の接続 URL KEELSON_DB_AUTH_TOKENdb.mode: libsqlManaged SQLite の認証トークン TURSO_DATABASE_URL / TURSO_AUTH_TOKENdb.mode: libsql上 2 つの別名（互換用） KEELSON_FILES_BUCKET / KEELSON_FILES_PREFIXコンテナ型のデプロイで、ファイル保存先が構成されているとき（通常のデプロイでは自動） Files SDK が使う保存先。直接は使わない KEELSON_INTERNAL_MEDIA_BASE_URL / KEELSON_APP_MEDIA_TOKENコンテナ型のデプロイで、Media 機能が有効なとき（通常のデプロイでは自動） Media SDK が使うアップロード先と認証。直接は使わない KEELSON_MEDIA_URL_PREFIX上と同じ Media の配信 URL プレフィックス（/__keelson/media/） KEELSON_DIRECTORY_TOKENkeelson apps directory enable 後Directory API のトークン。Identity SDK が使う。サーバー側だけで扱う KEELSON_EMAIL_WEBHOOK_SECRETemail.inbound.enabled: true受信メール Webhook の署名シークレット。Email SDK の署名検証が使う KEELSON_EMAIL_API_URL / KEELSON_EMAIL_TOKENメール送信が有効なとき Email SDK の送信先と認証。直接は使わない KEELSON_EMAIL_BASE_URLメール送信が有効で、ホストを解決できるとき Email SDK がゲートウェイ経由で送るときの接続先。直接は使わない
静的サイト（command なし）にはコンテナがないので、これらの変数は注入されません。Files / Media / Email の SDK は静的サイトからは使えません。
NODE_ENVkeelson.yaml の env で "production" を宣言してください外部 DB の接続情報 — db.mode: none のときは何も注入されません。シークレットで渡します
SDK をローカルで動かすときの変数です。Keelson 上では設定しません。
変数 内容 KEELSON_FILES_DIRFiles SDK のローカル保存先（既定 ./.keelson/files） MEDIA_DIRMedia SDK のローカル保存先（既定 ./media） KEELSON_LOCAL_MODE=1Identity SDK をダミーデータで動かす KEELSON_LOCAL_USER_ID / KEELSON_LOCAL_USER_EMAIL / KEELSON_LOCAL_USER_NAMEダミーユーザー KEELSON_LOCAL_WORKSPACE_ID / KEELSON_LOCAL_WORKSPACE_ROLE / KEELSON_LOCAL_APP_IDダミーのワークスペース・ロール・アプリ
旧名の KEELSON_LOCAL_TENANT_ID と KEELSON_LOCAL_TENANT_ROLE も互換のため
受け付けます。撤去時期は未定です。
CLI コマンド keelson CLI の主なコマンドと、スクリプトやエージェントから使うときに知っておくべき挙動をまとめています。通常は AI エージェントが Skill を通じて実行するので、すべてを覚える必要はありません。各コマンドの全フラグと既定値は keelson <コマンド> --help で確認できます。
インストールはクイックスタート 、更新は keelson upgrade で行います。
対応するコマンドで使えるフラグです。login / logout / install-agent / dev ... など一部のコマンドは受け付けません。app curl は --json と --quiet を明示的に拒否します。
フラグ 内容 --app <slug>対象アプリ。省略時はカレントディレクトリの keelson.yaml から解決。access show / access set / apps tokens create / apps tokens rotate / feedback は省略できない --workspace <slug|name|id>対象ワークスペース。--workspace → keelson.yaml の workspace → 前回使った既定 → 所属が 1 つならそれ、の順で決まる。複数に属していて前段で決まらないときだけ必要。同名のワークスペースがあるときは slug か ID で指定 --json結果を JSON で出力。スクリプトやエージェントから使うときに --quiet説明や進捗を抑える。出力の形はコマンドごとに違う(secrets set は key ごとに 1 行、deploys list は ID ごとに 1 行、deploy --check は成功時に何も出さない) --timeout <duration> / --retry <n>API 呼び出しのタイムアウト(既定 15 秒)と再試行回数(既定 0) --no-browserブラウザを開かず URL を表示する(login、承認が必要な操作)
--json でコマンドが失敗すると、標準出力に {"error":{"code","message","hint","retryable"}} が返ります。hint に従ってください。retryable が false なら同じコマンドを繰り返しても結果は変わりません。
旧名の --tenant と keelson tenants list も互換のため受け付けます。撤去時期は未定です。
コマンド 内容 keelson login [--no-browser]ブラウザでログインし、この端末を紐付ける keelson logout [--all-devices]この端末の保存済みログイン情報を削除し、サーバー側のセッションを失効させる。--all-devices ですべての端末をログアウト。KEELSON_TOKEN で渡したトークンは失効しない keelson whoamiログイン中のユーザーと、現在選ばれているワークスペース。ワークスペースの slug を確実に取るには workspaces list --json を使う keelson workspaces list [--query <text>] [--exact]所属ワークスペースの一覧・検索。--json の slug が --workspace に渡す値 keelson doctor [--fix-path]PATH・ログイン・Skill の状態を確認。--fix-path はシェルの設定ファイルに PATH を追記 keelson install-agent <claude-code|codex|cursor> [--global]AI エージェントに Skill を入れる。引数なし + --yes で入れてある Skill をすべて更新 keelson upgradeCLI を最新版に更新 keelson versionバージョン表示 keelson telemetry status|off|onCLI の利用状況データ の状態確認、停止、有効化keelson feedback --app <slug> [--deploy <id>] < feedback.jsonCLI や Skill の使い勝手を標準入力の JSON で送る。形式は keelson feedback --help
コマンド 内容 keelson deployカレントディレクトリのアプリをデプロイ。完了まで待つかどうかは下の表を参照 keelson deploy --new [--region <region>] [--secrets-from-env-file <path>]アプリを作成して初回デプロイ。env ファイルの値をシークレットとして登録し、そのファイルはアーカイブから除外 keelson deploy --check [--json]アップロードせず、設定の検証とアーカイブ内容(除外ファイル、秘匿値らしきファイル)を表示。ローカル検証なので、プランの上限に当たるかどうかまでは分からない keelson deploy --ndjson --yesスクリプト向け。進捗を 1 行 1 JSON で流し、完了時に {"result":"success"|"failed"} keelson status [deploy_id] [--wait] [--max-wait <duration>]指定したデプロイ(省略時はアプリの最新デプロイ)の状態。最新デプロイが失敗していても前の成功リビジョンが動いていることはあるので、いま動いているものの状態は app info で見る keelson diagnose [deploy_id]失敗したデプロイの診断(id あり。起動失敗時は保存済みのアプリの起動ログを含む)/ 稼働中アプリの診断(id なし) keelson deploys list [--limit] [--offset]デプロイ履歴 keelson deploys download <deploy_id> [-o <path>]そのデプロイに使ったソースアーカイブをダウンロード(保持期間内のみ) keelson rollback [deploy_id] [--yes]前の成功デプロイ(または指定したデプロイ)に戻す。対象はコンテナイメージを持つ成功デプロイだけで、静的サイトは以前のソースを再デプロイして戻す。ビルドせずに戻すが db.migrate は再実行される。受け付けた時点で返るので、返ってきたデプロイ ID を status --wait で確認する。--json や非対話端末では --yes が必要
実行のしかた 挙動 対話端末で keelson deploy 完了まで待つ(既定 30 分。--watch-timeout で変更) パイプや CI など非対話で keelson deploy 受け付けた時点で返る。待つなら --watch --json受け付けた時点で返る。--watch と併用不可 --ndjson完了まで待つ(--no-watch と併用不可) --no-watch対話端末でも受け付けた時点で返る
待ち時間の上限を超えても監視をやめるだけで、サーバー側のデプロイは止まりません。status --wait で続きを確認できます。
段階の実行中は {"stage":"health_check","status":"progress",…} のような行が流れます。進捗行の status で成否を判定しないでください。判定は次の 3 つで行います。
監視まで進んだ場合、最後に result を持つ行が出る
keelson.yaml が無い、設定が不正など、監視に入る前の失敗は {"error":{…}} の 1 行だけで、result 行は出ないプロセスの終了コード。0 以外は失敗
コマンド 内容 keelson app curl <path> [-i] [--method] [--data] [--form] [--header]認証済みでアプリにリクエストを送る。GET / HEAD の一時的な失敗は既定で最大 2 回再試行(--retry 0 で止める)。--data を付けるときは --method も指定する。--form は省略時 POST。-i の status / header は標準エラー、body は標準出力。デプロイ後の確認 keelson preview [--ttl] [--allow-writes] [--json]認証済みの短命な券を発行する keelson app info / start / stop / restartアプリの情報表示、起動、サスペンド、再起動。restart は完了まで待つ(--no-watch で受付後に返る)
preview と app curl は、いま動いているデプロイを行った本人以外が実行すると、読み取りだけでもブラウザでの承認が要ります。この承認は下の「ブラウザでの承認が必要な操作」とは別の流れで、承認しても操作は実行されません。承認後に同じコマンドへ --confirmation <id> を付けて再実行します(期限 30 分)。
コマンド 内容 keelson logs app <slug> [--mode live|history] [--severity] [--previous] [--limit] [--since]アプリの標準出力・標準エラー keelson logs cron <slug> [--severity] [--limit] [--since]cron の実行ログ keelson logs access [--limit] [--since]アクセスログ keelson logs deploy [deploy_id] [--limit] [--since]デプロイの進行ログと保存済みの失敗詳細。アプリが起動中に終了した場合は、アプリの起動ログも表示。成功時のビルド出力は保存されないため、表示できるログがなければ理由を表示
--since は 1h や 1d12h のような期間(1 秒〜30 日)です。--json の各行は文字列ではなく、時刻や severity を持つオブジェクトです。
値はコマンド引数ではなく標準入力または env ファイルから渡します。
コマンド 内容 keelson secrets list設定済みの名前と更新日時。値は表示しない echo -n "<value>" | keelson secrets set <KEY> [--apply]1 件設定。--apply で再デプロイまで要求(受付後に返る) keelson secrets set --from-env-file <path> [--apply]env ファイルからまとめて設定。key ごとに保存するので、途中で失敗すると一部だけ保存された状態になる(エラーに保存済みの key が入る) keelson secrets unset <KEY>削除
シークレットは次のデプロイ(または --apply)で反映されます。
コマンド 内容 keelson apps list [--workspace <slug>] [--query <text>] [--exact]アプリ一覧。--workspace を省略すると所属する全ワークスペースを対象にする(keelson.yaml や前回の既定では絞らない)。--json の形は --workspace あり({apps: […]})となし({workspaces: […]})で違う keelson apps duplicate <slug> --name <new> [--copy-secrets] [--enable-schedule]アプリを複製。cron のスケジュールは既定で無効のまま複製 keelson apps rename <new_slug>公開 URL の slug を変える。旧 URL は 410 を返し、自動リダイレクトはされない 。反映まで時間がかかる。手元の keelson.yaml の slug も書き換える keelson apps delete [slug]アプリを削除。ブラウザでの承認が必要 keelson quotasプランの上限と使用量
コマンド 内容 keelson crons list [--include-disabled]ジョブ一覧 keelson crons trigger <name> [--wait]今すぐ実行。--wait で実行結果まで待つ keelson crons enable <name> / disable <name>有効化 / 無効化 keelson crons runs list [--cron <name>] [--limit] [--offset]実行履歴 keelson dev cron run <name> [--file] [--dir]keelson.yaml の cron をローカルで 1 回実行(スケジューラではない)
コマンド 内容 keelson db apply [file.sql]Managed SQLite に SQL を実行(省略か - で標準入力)。既にテーブルなどがある DB へはブラウザでの承認が必要 。テーブル・インデックス・ビュー・トリガーを 1 つも持たない初回の DB には承認なしで適用される keelson snapshots list復元ポイントと実行中の取り出し（exports）の一覧 keelson snapshots create手動スナップショット keelson snapshots download <id> [-o <file>]バックアップのダウンロード。-o を省くとダウンロード URL を表示するだけでファイルは書かない keelson snapshots export --at <RFC3339>任意時点(PITR)のエクスポートを作成。完了後に download で取得 keelson snapshots restore <id>復元。ブラウザでの承認が必要 。72 時間以内なら取り消し可 keelson snapshots restore-status最新の復元の進捗と結果を確認 keelson db revoke-tokens [app] [--yes]DB の認証トークンを失効させる(破壊的)。端末内で確認を求める。非対話端末では --yes。失効後、新しいリビジョンに切り替わるまで DB は一時的に使えない keelson db recover [app] / credential-status [app]認証情報の復旧と状態
コマンド 内容 keelson groups listグループ一覧 keelson groups create <key> [--name] [--description] [--if-not-exists]カスタムグループを作成 keelson groups members list <key>グループのメンバー keelson groups members add|remove <key> <email>...既存メンバーの所属を変更(招待ではない) keelson access show --app <slug>アプリの閲覧 / 管理グループ keelson access set --app <slug> [--view <key>...|--view none] [--manage <key>...] [--allow-self-lockout]権限を設定。指定した側は丸ごと置き換え、指定しなかった側は保持。管理は空にできない。自分の権限が失われる変更は --allow-self-lockout が要る
コマンド 内容 keelson apps tokens create --app <slug> --name <n> --scope <scope> [--scope …] [--allowed-ip <cidr>…]アプリトークンを発行(1 回だけ表示)。--app は省略できない keelson apps tokens list一覧(メタデータのみ) keelson apps tokens rotate --app <slug> --token-id <id>ローテーション。旧トークンは猶予付きで失効 keelson apps tokens delete <token_id>失効 keelson apps directory enableDirectory API のトークンを発行し、KEELSON_DIRECTORY_TOKEN として登録(要再デプロイ) keelson domains listカスタムドメインの一覧と状態 keelson domains add|verify|remove <hostname> [--yes]カスタムドメインの追加・検証・削除(Team)。remove は非対話端末では --yes keelson dev email --to ... --subject ...ローカルのアプリに受信メールをテスト送信
--scope に指定できる値は次のとおりです。受信用と Directory 用は同じトークンに混在できません。
scope 用途 api外部システムからアプリの /api/external/... を呼ぶ webhook外部サービスからアプリの Webhook を受ける directory:members:read / directory:identity:read / directory:groups:read / directory:group-members:readアプリから Directory API を呼ぶ(通常は apps directory enable が付与する)
アプリの削除、既存スキーマがある DB への SQL の実行、スナップショットからの復元は、CLI だけでは完了しません。コマンドは承認用 URL を表示し(confirmation_required)、ブラウザで承認すると操作がサーバー側で実行されます。コマンドを再実行する必要はありません。承認の期限は 15 分です。
URL を表示したあとの挙動は実行のしかたで変わります。
対話端末: 既定で承認と実行の完了まで待つ。--wait=false で待たずに返る
--json または非対話端末: 既定で待たずに返る。--wait を付ければ待つ
preview / app curl の承認は、これとは別の再実行方式です(「確認」の節を参照)。rollback / db revoke-tokens / domains remove はブラウザ承認ではなく端末内の確認で、非対話端末では --yes が要ります。
変数 内容 KEELSON_TOKENログインの代わりに使うトークン(CI 向け)。保存済みログインより優先。設定してあると空文字でもエラーになる KEELSON_NO_UPDATE_CHECK=1 / KEELSON_NO_SKILL_SYNC=1更新確認 / Skill の自動更新を止める(KEELSON_NO_SKILL_SYNC は空でなければ 0 でも止まる) KEELSON_NO_TELEMETRY=1CLI の利用状況データ を止めるKEELSON_CONFIG_DIR設定ファイル(credentials.json / config.json)を置くディレクトリ KEELSON_API_BASE_URL / APP_DOMAIN_BASE接続先 API とアプリドメインの上書き(通常は不要)
エラーコード CLI とデプロイのエラーは code と hint(対処方法)を伴って返ります。AI エージェントにそのまま渡せば対処できます。hint がある場合はこのページより hint を優先してください。workspace 名のコードへ移行したエラーでは、旧 tenant 名のコードを互換用の error.aliases に載せます。撤去時期は未定です。ここでは人が読むための一覧を、発生する場所ごとにまとめます。
このページは日常的に遭遇するコードの一覧で、全コードの網羅ではありません。掲載していないコードが出たときも、code と hint の形は同じです。
経路によって、理由を読む場所が違います。
経路 形 CLI(--json) 標準出力に {"error":{"code","message","hint","retryable"}} デプロイの失敗(status / diagnose) failure_code と hintKeelson API の通常のエラー {"detail": "..."}。入力検証エラーでは detail が配列。code / hint は付かないアプリの URL に対する認可の拒否(ゲートウェイ) ブラウザには HTML の案内。fetch / XHR には {"detail":"ip-restricted"} のような JSON と、理由を入れた X-Keelson-Auth-Error ヘッダー 稼働枠不足・停止中(ゲートウェイ) 503。x-keelson-platform-error ヘッダー(capacity-full / app-suspended)。稼働枠不足は X-Keelson-Error-Code: CAPACITY_FULL も付く 存在しない URL・停止中・予約パス(エッジ) 404 / 410 / 503 / 403 の平文と x-keelson-platform-error ヘッダー。ゲートウェイに届かないので X-Keelson-Auth-Error は付かない Files / Media の配信 x-keelson-error ヘッダーに理由。一部のコードだけ {error, hint, doc} の JSON
retryable は HTTP のステータスからは決められません。同じ 503 でも false のことがあり、ビルドの 429 にはトライアルの累積上限のように待っても解除されないものがあります。
アップロード前に報告され、keelson deploy --check でも確認できます。エラーはデプロイを止めますが、警告は止めません。依存マニフェストがない場合、Go ではエラー、Python と Node.js では警告になります。
コード 原因 対処 missing_dependency_manifest選択したランタイムの依存マニフェストがない Go ではプロジェクトルートに go.mod を置く。Python または Node.js で外部ライブラリを使う場合はマニフェストを置く。標準ライブラリだけのアプリでは依存マニフェストは必須ではありません command_installs_dependenciescommand に pip install / npm install / go build がある削除し、起動コマンドだけにする runtime_command_mismatchruntime と command の言語が合わない(例: python-slim で node)どちらかを直す assets_dir_emptyassets.dir が無い、空、またはパスの大文字小文字が違うビルドを実行する。パスを確認する assets_fallback_missingassets.fallback のファイルが assets.dir にないビルド出力を確認する db_wiring_fail(警告)db.mode とコードの DB 接続が食い違う(接続先、ローカル開発用のフォールバック、宣言の不一致など複数の規則がある)表示された hint に従う。多くは KEELSON_DB_URL を読む libSQL クライアントに直す file_wiring_fail(警告)状態ファイルやアップロードをローカルディスクに書いている Files / Media SDK に置き換える
コード 原因 対処 invalid_keelson_configYAML が不正、db.mode が libsql / none 以外、db.migrate を none と併用、KEELSON_ で始まる env、/__keelson 配下のパス、不明な runtime、cron が 10 本超、など message の内容を直すconfig_missing_field必須フィールドがない(slug、runtime、db など。静的サイトでは type と assets も) 追加する env_value_not_stringenv の値が文字列でない、YAML が曖昧に解釈するキー、キーの重複、merge key(<<)値は引用符かブロック文字列にする。曖昧なキー(on / yes / 数字など)は引用符で囲む。重複は削除する。merge key は展開して書く。重複と merge key は引用符で囲んでも拒否される description_too_longdescription が 300 文字超短くする workers_not_supportedworkers: がある削除して crons で書く DB_DATABASES_REMOVEDdatabases: がある削除する。永続データは db.mode: libsql SQLITE_LOCAL_SQLITE_INVALID_PATHdb.local_sqlite.paths が /tmp/ の外/tmp/ か :memory: にするCRON_TIMEOUT_EXCEEDS_STANDARD_LIMITcrons[].timeout が 600 秒超下げる、処理を分割する plan_cron_limit / plan_cron_min_interval / plan_schedule_timeoutcron の本数・間隔・timeout がプラン上限を超える 減らすか、プランを上げる ARTIFACT_SQLITE_FILE_DRIVERファイル SQLite クライアント(sqlite3、better-sqlite3 など)が検出された libSQL クライアントへ移行。一時用途なら db.local_sqlite で宣言 ARTIFACT_EXEC_NODE_CRON / ARTIFACT_EXEC_APSCHEDULER / ARTIFACT_EXEC_BACKGROUND_TASKS / ARTIFACT_EXEC_SET_INTERVAL(注意)アプリ内スケジューラが検出された crons に移す
ビルド出力の直下に __keelson ディレクトリがあるとビルドが失敗します。このときの failure_code は deploy.build.failed で、ビルドログに reserved_path_conflict が出ます。ディレクトリ名を変えてください。
keelson status / keelson diagnose に failure_code として表示されます。
コード 原因 対処 deploy.config.invalidkeelson.yaml の内容が不正指摘されたキーを直して再デプロイ deploy.config.secret_missingsecrets.required で宣言したシークレットが未設定keelson secrets set <KEY>(値は標準入力)で全て設定してから再デプロイdeploy.artifact.invalidアーカイブの問題(ロックファイルなし、ブロック対象の検出) 指摘された箇所を直す deploy.artifact.assets_invalidassets.dir / assets.fallback で宣言したファイルがアップロードに含まれていない手元でビルドしてから再デプロイ deploy.build.failedビルド失敗(依存の解決失敗、ビルドスクリプトのエラー、予約パスの衝突) keelson logs deploy <deploy_id> でビルド出力の末尾を見るdeploy.build.timed_outビルドが制限時間内に終わらなかった 不要な依存を減らす、重い前処理をビルドの外に出す deploy.build.image_too_largeイメージが大きすぎる 不要な依存やファイルを減らす deploy.runtime.start_failedアプリが起動中に終了、またはコンテナが起動状態にならなかった keelson logs deploy <deploy_id> で保存済みのアプリの起動ログを読み、PORT と 0.0.0.0 を確認deploy.runtime.health_check_failed起動・ヘルス検証の制限時間内に、/(もしくは health.path)から期待する応答(2xx / 3xx / 404)を得られなかった。アプリが起動中に終了した場合や、401 / 403 / 5xx を返し続ける場合を含む keelson logs deploy <deploy_id> で保存済みのアプリの起動ログを読み、待ち受けポートと health.path を確認deploy.runtime.migration_faileddb.migrate が 0 以外で終了。旧リビジョンが配信を継続マイグレーションを直して再デプロイ。途中まで適用された DB の変更は自動では戻らない deploy.verify.failedverify のパスが取得できない、または JS / CSS の Content-Type が不一致パスとビルド出力を確認。詳細は failure_logs の verification_* コードに出る deploy.plan.limit_exceededプランの上限超過 減らすか、プランを上げる deploy.plan.cron_count_exceededcron の本数がプラン上限を超えている 減らすか、プランを上げる deploy.plan.cron_interval_too_shortcron の間隔がプランの最小間隔より短い 間隔を伸ばすか、プランを上げる deploy.plan.schedule_timeout_exceeded明示した crons[].timeout がプラン上限を超えている timeout を下げるか、プランを上げる deploy.app.suspendedアプリまたはワークスペースが Keelson 側の制限措置を受けている サポートへ連絡する。利用者や管理者による再開では解除されない deploy.app.operation_in_progressこのアプリで別の操作が進行中だったため、デプロイを開始できなかった 別の操作が完了してから再デプロイ deploy.platform.temporarily_unavailable一時的な障害 待ってから再試行する。追加で 3 回まで。それでも失敗するなら deploy_id を添えてサポートへ deploy.platform.errorプラットフォーム側のエラー 再試行しても直らない。deploy_id を添えてサポートへ deploy.cancelledデプロイが取り消された 必要なら再デプロイ deploy_in_progress(409)別のデプロイまたはアプリ操作が進行中 進行中の操作が完了してから同じコマンドを再実行 build_rate_limit_exceeded / build_guardrail_exceeded(429)ビルド回数・ビルド時間・同時実行・連続失敗の上限 メッセージが解除条件を示す。連続失敗は原因を直して記載の時刻を待つ。トライアルのビルド枠は累積で、待っても解除されない ので、その場合はプランを変更する saved_config_unsupported(409)再デプロイ / ロールバック対象の keelson.yaml が現在のスキーマに合わない 直して通常のデプロイをする
keelson crons runs list と keelson logs cron に出ます。
コード 意味 cron.failed.command_failedコマンドが 0 以外で終了した cron.failed.timed_outtimeout を超えたcron.failed.terminated_no_callback実行が終了したが結果が報告されなかった dispatch_failed実行の起動に失敗した cron.skipped.schedule_disabledジョブが無効化されている cron.skipped.quota_exceededプランの実行枠を超えた cron.skipped.due_to_lock / cron.skipped.lease_held前回の実行がまだ終わっていない cron.skipped.missed_run予定時刻を過ぎたため飛ばした cron.skipped.app_suspendedアプリが停止中 cron.skipped.plan_downgradeプラン変更で実行できなくなった
keelson snapshots ... のエラーです。名前が snapshot_export_ で始まるものは snapshots export の同じ条件です。
コード 意味 対処 snapshot_plan_not_included手動スナップショットがプランに含まれない プランを変更する snapshot_no_managed_dbManaged SQLite を使っていない db.mode: libsql で DB を作ってからsnapshot_db_name_invalid / snapshot_db_name_unknownDB 名が不正、または存在しない hint に出る名前を使うsnapshot_already_running / snapshot_export_already_running前の処理が実行中 終わってから再試行 snapshot_rate_limited / snapshot_export_rate_limited回数上限 hint の時刻まで待つsnapshot_export_invalid_timestamp復元可能な範囲の外の時刻 範囲内の時刻を指定する snapshot_app_deleting / snapshot_export_app_deletingアプリが削除中 — snapshot_launch_failed / snapshot_export_launch_failed起動に失敗 再試行。続くならサポートへ snapshot_disabled / snapshot_storage_unconfigured(export 系も同様)プラットフォーム側で無効 サポートへ snapshot_not_readyまだダウンロードできない(X-Keelson-Error-Code ヘッダー) 完了を待つ
コード 意味 対処 not_logged_in未ログイン keelson loginmultiple_workspaces / workspace_ambiguous / workspace_not_found / no_workspacesワークスペースを特定できない --workspace <slug>。keelson workspaces list --query で検索app_not_foundアプリが見つからない slug を確認。新規なら --newapp_manage_requiredアプリは存在するが、管理権限がない 現在の管理者に、管理権限を持つグループへ自分を追加してもらう。ワークスペースの OWNER / ADMIN なら keelson groups members add <グループ> <メール> で自分を追加する app_deleting削除中のアプリ 完了を待つ forbidden権限がない。CONSOLE_ONLY_OPERATION ならコンソール限定の操作 ロール・アプリ権限を確認 confirmation_requiredブラウザでの承認が必要な操作 表示された URL を開いて承認。削除・SQL・復元は承認と同時に実行されるので再実行は不要。preview / app curl は承認後に --confirmation <id> を付けて同じコマンドを再実行する confirmation_expired / confirmation_rejected承認の期限切れ(削除・SQL・復元は 15 分、preview / app curl は 30 分)/ 却下 コマンドをやり直す deploy_failedデプロイ失敗 keelson diagnose <deploy_id>sql_faileddb apply の SQL エラー。ロールバック済みSQL を直す usage(access set。API の 409 detail.reason が last_manage_binding_removed / no_effective_manager / self_lockout)管理グループが空になる、有効な管理者がいなくなる、自分の権限が失われる 管理グループを残す。--allow-self-lockout で解除できるのは自分が外れる場合だけで、管理グループや有効な管理者がゼロになる変更は解除できない transient一時的なネットワークエラー --retry を付けて再試行skill_outdated(meta.skill_outdated。doctor の警告でもある)Skill が CLI より古い。コマンドは失敗しない keelson install-agent --yes
表示 状態 対処 ログイン画面 未ログイン ワークスペースに登録されたアカウントでログイン 「アクセスできません」(403) メンバーでない、ブロック済み、アプリの閲覧権限がない 管理者にメンバー登録・権限を依頼 「このアプリは、許可されたアクセス元からのみ利用できます」(403) IP 制御で拒否。画面に送信元 IP が表示される 管理者にその IP のアクセス元への追加を依頼 「アプリの稼働枠が空いていないため起動できません」(503) 同時に使えるアプリ数の上限 枠を使っている別のアプリへのアクセスが約 5 分途絶えると空く。使われ続けていれば空かないので、管理者がアプリの停止・優先起動・プラン変更で調整する 「アプリを起動しています」 スリープからの起動中 数秒待つ(自動で再読み込み) 「このアプリは停止中です」(503) サスペンド中、または Keelson 側の制限措置 管理者が再開する。再開しても直らない場合は制限措置なのでサポートへ 「App not found」(404) URL が間違っている、またはアプリが削除された URL を確認 410 Gone 公開 URL が変更された(旧 URL は 30 日間予約) 新しい URL を案内 504 アプリが 120 秒以内に応答ヘッダーを返し始めなかった。ストリーミングの全体時間ではない 処理を短くする、cron に逃がす 501 WebSocket は未対応 SSE やポーリングに変える
API や XHR から同じ状況になると、ゲートウェイの拒否では JSON の detail と X-Keelson-Auth-Error ヘッダーに理由(ip-restricted、app-view-denied など)が入ります。稼働枠不足と停止中は x-keelson-platform-error ヘッダー(capacity-full、app-suspended)です。
詳しい理由は X-Keelson-Auth-Error で返ります。IP 許可範囲による拒否でも、互換性のため JSON の detail は machine-forbidden または webhook-forbidden のままです。
machine-forbidden と webhook-forbidden は、アプリが存在しない場合、トークンが別のアプリのものである場合、経路が消失した場合を意図的にまとめ、応答からアプリの存在を判定できないようにしています。
X-Keelson-Auth-Error原因 invalid-app-tokenトークンが無効、または失効済み machine-scope-deniedトークンのスコープ(api / webhook)がパスと合わない machine-endpoint-deniedauth.endpoints で宣言されていないパス・メソッドmachine-forbidden / webhook-forbiddenアプリが存在しない、トークンが別のアプリのもの、または経路が消失した machine-ip-not-allowedアプリトークンの許可 IP の外から呼ばれた invalid-webhook-secretWebhook シークレットが一致しない webhook-scope-deniedトークンに webhook スコープがない webhook-ip-not-allowedWebhook トークンの許可 IP の外から呼ばれた
/api/webhooks/email などプラットフォーム予約のパスへの Webhook は、ゲートウェイより手前のエッジが 403 の平文で拒否します。このときのヘッダーは X-Keelson-Auth-Error ではなく x-keelson-platform-error: auth-webhook-endpoint-blocked です。
CLI の利用状況データ Keelson は、どの操作が成功しているかを把握し、信頼性の問題を見つけて CLI を改善するために、CLI の利用状況データを収集します。この機能は既定で有効です。
サブコマンド名
終了コードと、利用できる場合は公開済みの失敗符号
コマンドの所要時間
使用したフラグの名前（値は含みません）
対話端末（TTY）で実行されたかどうか
CLI のバージョン
CLI を起動したエージェントの種別（判別できない場合は不明として記録）
一覧系コマンドでは、結果が 0 件、1 件、複数のいずれかだけ
重複を除くためのイベントごとの識別子
コマンドを実行した日時
セッション識別子。端末側で作る乱数で、コマンドが 30 分記録されないと作り直されます。保存されるイベントの行には、アカウント、ワークスペース、アプリの識別子は含まれません。イベントの送信にはログイン済みの資格情報を使い、送信回数はアカウント単位で数えるため、送信経路自体は匿名ではありません。
アプリのソースコードやデプロイアーカイブの中身
ログ、標準出力、標準エラーの本文
環境変数の値やフラグに渡した値
ファイルパス、ワークスペース名、アプリ名
keelson.yaml の本文AI エージェントとの会話
設定を保存して停止するには、次を実行します。
環境変数で停止するには、次を設定します。
環境変数は保存済みの設定より優先されます。環境変数が設定されている間は、keelson telemetry on を実行しても有効にできません。停止すると未送信のイベント記録は削除され、現在の状態はいつでも keelson telemetry status で確認できます。
停止するのはイベントの記録と送信、および X-Keelson-Client ヘッダーです。通常の User-Agent ヘッダーには、停止後も keelson-cli/<version> として CLI のバージョンが含まれます。
初めて利用状況データを送信する直前に、対話端末で実行している場合だけ 1 行の告知を表示します。対話端末ではない自動実行では表示しません。
keelson feedback は、利用者が提供するフィードバックを共有するための別の仕組みです。明示的に実行し、フィードバック共有が有効な場合にだけ送信します。フィードバック共有は既定で無効です。CLI の利用状況データを有効または無効にしても、フィードバック共有の設定は変わりません。
