# Keelson

> Keelson は、Claude Code や Codex などの AI ツールで作った社内アプリを、社員が安全に使える状態にして運用し続けるための基盤(PaaS)です。アプリには業務ロジックだけを書き、公開 URL・ログイン・権限・シークレット・データベース・定期実行は Keelson が持ちます。

このファイルは AI エージェント向けの日本語ドキュメント索引です。**下の「ページ一覧」のリンク先は各ページの Markdown**なので、質問に関係するページを辿って読んでください。デプロイ可否の判定と書き換えは Keelson Deploy Spec を正本としてください。

- Deploy Spec(raw text): https://keelson.dev/ja/docs/reference/deploy-spec.txt
- 全ページの全文(1 ファイル): https://keelson.dev/ja/llms-full.txt
- 各ページの Markdown: ページ URL の末尾の `/` を `.md` に変える(例: https://keelson.dev/ja/docs/introduction/quickstart.md)。人が読む HTML は `.md` を `/` に戻した URL
- 英語版の索引: https://keelson.dev/llms.txt

## 要約

### 載るもの
- Python / Node.js / Go で書かれ、環境変数 `PORT` で `0.0.0.0` に listen する HTTP サーバー(FastAPI / Flask / Django / Express / Hono / Next.js / Go net/http など)
- ビルド済みの静的サイト / SPA(`assets` モード)、静的フロント + API のハイブリッド
- 定期実行だけのジョブ(`crons`)
- 外部の DB / API(PostgreSQL, Supabase, OpenAI, Slack など)への接続。外部通信に制限はない

### 書き換えが要るもの(AI エージェントの Skill が自動で行う範囲)
- ファイル SQLite(`sqlite3`, `better-sqlite3`) → libSQL クライアント + `db.mode: libsql`(Managed SQLite)
- ローカルファイルへの保存 → Managed SQLite か Files / Media SDK。ローカルディスクは再起動で消える
- アプリ内のタイマー / バックグラウンドスレッド → `crons`

### 載らないもの
- Streamlit(WebSocket 必須)。Gradio は検証中
- Ruby / PHP / Java / Rust / .NET / Elixir、Dockerfile での apt 追加、常駐プロセス / WebSocket サーバー前提、自前の Redis / Kafka、GPU

### 実行モデル(最重要)
サーバー側コードが動くのは「リクエストを処理している間」と「宣言した cron の実行中」だけ。アイドル時は停止(scale-to-zero)し、次のアクセスで起動する。レスポンス後の処理、常駐タイマー、監視ループは動かない。HTTP は 120 秒以内にレスポンスを開始する。

### 認証と権限
デプロイしたアプリは全て Keelson のログインの後ろに置かれる。URL を知っているだけでは開けない。アプリのコードに認証は不要で、Keelson が付けるヘッダー `X-Keelson-User-Id` / `X-Keelson-User-Email` / `X-Keelson-User-App-Perms`(`view` または `view,manage`)で「誰か」「運用者か」を判断する。誰がどのアプリを開けるかは、アプリごとにグループへ割り当てた view / manage で決まる(既定: 全員に view、開発者に manage)。

### keelson.yaml の最小構成
```yaml
slug: my-app
runtime: python-slim        # python-slim | node-slim | go-slim(画像処理は -media)
command: "uvicorn main:app --host 0.0.0.0 --port $PORT"
db:
  mode: none                # 永続データを持つなら libsql
```
`command` に `pip install` / `npm install` は書かない(ビルド時に自動)。秘密の値は `secrets` に名前だけ宣言し、値はコンソールか `keelson deploy --secrets-from-env-file` で渡す。

### プランの上限(抜粋)
同時に使えるアプリ数: Starter 1 / Plus 2 / Team 4。Developers 席(Owner / Admin / Developer): 1 / 2 / 3。App User は無制限。有料契約中の保存アプリ数は無制限。トライアル中は保有 3 個(静的サイトとしてデプロイ済みのものは数えない)・稼働 3 個まで。

## ページ一覧

### はじめに

- [ドキュメントガイド](https://keelson.dev/ja/docs/introduction/what-is-keelson.md): Keelson でできること、できないこと、目的別の入口
- [クイックスタート](https://keelson.dev/ja/docs/introduction/quickstart.md): サンプルアプリを Keelson にデプロイして、ログイン保護が効くところまで確認する
- [基本コンセプト](https://keelson.dev/ja/docs/introduction/core-concepts.md): ワークスペース・アプリ・グループの関係と、Keelson とアプリの役割分担
- [FAQ](https://keelson.dev/ja/docs/introduction/faq.md): 導入前によく聞かれること

### アプリを作る

- [対応アプリと制約](https://keelson.dev/ja/docs/building-apps/supported-app-types.md): Keelson にデプロイできるアプリと、対応ランタイム・実行環境の制約
- [アプリが動くタイミング](https://keelson.dev/ja/docs/building-apps/how-apps-run.md): Web アプリの起動と停止、リクエスト処理と定期実行ジョブの使い分け
- [他のツールで作ったアプリを持ち込む](https://keelson.dev/ja/docs/building-apps/bring-your-app.md): 手元のアプリを AI エージェントで確認し、データやログインの設定を整えてデプロイする
- [keelson.yaml の設定](https://keelson.dev/ja/docs/building-apps/keelson-yaml.md): AI エージェントが作成する設定ファイルの役割と、確認しておきたい項目
- [データベース（Managed SQLite）](https://keelson.dev/ja/docs/building-apps/persistent-storage.md): 顧客情報や業務データを残すための保存先と、データベースの使い方・バックアップ・復元
- [ファイルとメディア](https://keelson.dev/ja/docs/building-apps/files-and-media.md): アプリ内部で使う Files と、画像や添付ファイルを URL で表示する Media の使い分け
- [定期実行ジョブ](https://keelson.dev/ja/docs/building-apps/scheduled-jobs.md): 決まった時刻・間隔で処理を動かす方法と、実行結果の確認
- [ログイン中のユーザー情報を使う](https://keelson.dev/ja/docs/building-apps/using-identity.md): ログインユーザーの識別、運用者だけの画面、グループごとの分岐と業務上の権限
- [外部システムとの連携](https://keelson.dev/ja/docs/building-apps/external-integrations.md): Webhook の受信、API トークン、受信メール、外部 DB
- [フレームワーク別の注意点](https://keelson.dev/ja/docs/building-apps/frameworks.md): FastAPI / Flask / Express / Next.js / Go の起動方法と、未対応フレームワークの注意点

### デプロイと運用

- [デプロイする](https://keelson.dev/ja/docs/deploy/deploy.md): AI エージェントまたは CLI でアプリをデプロイし、完了を確認する
- [デプロイ後の確認](https://keelson.dev/ja/docs/deploy/verify-deploy.md): デプロイ後に確認する操作と、AI エージェントが画面や API の応答を調べる方法
- [環境変数とシークレット](https://keelson.dev/ja/docs/deploy/environment-variables.md): 設定値と API キーをアプリに渡す
- [アプリ URL とドメイン](https://keelson.dev/ja/docs/deploy/public-url.md): アプリに割り当てられる URL、アプリ内からの参照、URL の変更、カスタムドメイン
- [アプリの状態とログ](https://keelson.dev/ja/docs/deploy/app-status-and-logs.md): アプリの状態、サスペンドと再開、優先起動、ログ、デプロイ履歴とロールバック
- [更新と復元](https://keelson.dev/ja/docs/deploy/update-and-restore.md): アプリを安全に更新する手順と、事故が起きたときに何が戻り、何が戻らないか
- [トラブルシューティング](https://keelson.dev/ja/docs/deploy/troubleshooting.md): デプロイやアプリが失敗したときに、どこを見て何をするか

### ユーザーと権限

- [認証とログイン](https://keelson.dev/ja/docs/access-control/auth-and-login.md): アプリを利用できる人の制限と、利用者のログイン方法・流れ
- [メンバーとロール](https://keelson.dev/ja/docs/access-control/members-and-permissions.md): アプリを使う人・作る人・管理する人の役割と、メンバーの参加・無効化
- [チームにアプリを共有する](https://keelson.dev/ja/docs/access-control/share-with-team.md): 営業メンバーとアプリ管理者が使えるように設定し、URL を共有してアクセスを確認する

### ワークスペースと契約

- [メンバーを招待する](https://keelson.dev/ja/docs/workspace/invite-members.md): メールアドレスでメンバーを招待し、招待を管理する
- [グループとアプリ権限](https://keelson.dev/ja/docs/workspace/groups-and-app-access.md): 誰がどのアプリを使えるか・管理できるかを決める
- [ドメインと参加ポリシー](https://keelson.dev/ja/docs/workspace/domain-join.md): 自社ドメインのユーザーを招待なしで参加させる
- [IP 制御](https://keelson.dev/ja/docs/workspace/ip-allowlist.md): 許可したネットワークからのアクセスだけを受け付ける
- [プランと制限](https://keelson.dev/ja/docs/workspace/plans-and-limits.md): プランごとの上限と、上限に達したときの挙動
- [料金と契約の運用](https://keelson.dev/ja/docs/workspace/billing.md): プラン変更、トライアル、解約、請求書、ワークスペースの削除、データの持ち出し

### リファレンス

- [Keelson Deploy Spec](https://keelson.dev/ja/docs/reference/deploy-spec.md): Keelson にアプリをデプロイする際の対応ランタイム、制約、成立条件の正本仕様書
- [keelson.yaml](https://keelson.dev/ja/docs/reference/keelson-yaml-reference.md): keelson.yaml の全フィールドの型・既定値・制約
- [環境変数一覧](https://keelson.dev/ja/docs/reference/environment-variables.md): Keelson がアプリに自動設定する環境変数
- [CLI コマンド](https://keelson.dev/ja/docs/reference/cli.md): keelson コマンドの一覧
- [エラーコード](https://keelson.dev/ja/docs/reference/error-codes.md): CLI・デプロイ・実行時に表示されるエラーコードと対処
- [CLI の利用状況データ](https://keelson.dev/ja/docs/reference/telemetry.md): Keelson CLI が収集する情報と停止方法