クイックスタート

サンプルアプリを Keelson にデプロイし、ログインした人だけが使えることを確認します。

• 所要時間: 約 15 分。ビルドの待ち時間を含みます。
• 必要なもの: Keelson のアカウントと、コマンドを実行するターミナル。サンプルアプリ用に外部サービスの API キーを用意する必要はありません。
• 完了の目安: ログイン後は挨拶の画面が表示され、ログインしていないシークレットウィンドウではログイン画面が表示されます。

このガイドでは、Claude Code / Codex / Cursor のいずれかを使ってデプロイします。AI エージェントを使わず、CLI から直接デプロイすることもできます。その場合は手順 3 を省き、手順 4 の CLI コマンドを実行してください。

Keelson のアカウントがまだない方は、Keelson コンソールでアカウントを作成してください。

1. CLI をインストールしてログインする

Keelson CLI は、ターミナルからログインやデプロイを行うためのツールです。使っている OS のタブを選び、次のコマンドでインストールしてください。

macOS / Linux

curl -fsSL https://keelson.dev/install.sh | sh

keelson コマンドが見つからない場合

インストーラーは、コマンドを探す場所（PATH）を変更しません。次の行を ~/.zshrc や ~/.bashrc に追加し、ターミナルを開き直してください。

export PATH="$HOME/.keelson/bin:$PATH"

Windows (PowerShell)

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 のアカウントでログインしてください。

keelson login

2. サンプルアプリをダウンロードする

1. サンプルアプリをダウンロード（ZIP）します。
2. ZIP を展開します。
3. 展開した keelson-hello フォルダを Claude Code / Codex / Cursor で開きます。AI エージェントを使わない場合は、このフォルダでターミナルを開いてください。

サンプルの中身を見る

main.py

from html import escape

from fastapi import FastAPI, Request
from fastapi.responses import HTMLResponse

app = FastAPI()

@app.get("/", response_class=HTMLResponse)
def index(request: Request):
    email = escape(request.headers.get("X-Keelson-User-Email") or "ゲスト")
    return f"""
    <!doctype html>
    <html lang="ja"><body style="font-family: sans-serif; padding: 2rem">
      <h1>こんにちは、{email} さん</h1>
      <p>このアプリは Keelson で動いています。</p>
    </body></html>
    """

requirements.txt

fastapi
uvicorn

keelson.yaml

slug: hello
runtime: python-slim
command: "uvicorn main:app --host 0.0.0.0 --port $PORT"
db:
  mode: none

このアプリは、Keelson が付けるヘッダーからログイン中のユーザーのメールアドレスを読んで表示します。認証のコードは 1 行もありません。

3. AI エージェント用スキルをインストールする

スキルは、AI エージェントが参照する Keelson の設定・デプロイ手順です。Keelson CLI に同梱されています。展開した keelson-hello フォルダでターミナルを開き、使っているエージェントのタブを選んで、次のコマンドを実行してください。

Claude Code

keelson install-agent claude-code --global

--global を付けると、同じユーザーのほかのプロジェクトでも使えるようになります。付けない場合は、現在のプロジェクトにだけインストールします。

Codex

keelson install-agent codex

現在のプロジェクトにインストールします。

Cursor

keelson install-agent cursor

現在のプロジェクトにインストールします。

公開リポジトリからスキルをインストールする場合

インストール方法は、keelson install-agent、Claude Code プラグイン、npx skills add のどれか 1 つだけを使ってください。方法を組み合わせると、同じスキルが 2 つ入ったり、互いに上書きしたりすることがあります。

Claude Code では、マーケットプレイスを追加してからプラグインをインストールします。

/plugin marketplace add keelsonhq/skills
/plugin install keelson@keelson-skills

ほかのエージェントでは、次を実行します。

npx skills add keelsonhq/skills

これらの方法でインストールされるのはスキルだけです。手順 1 の CLI のインストールとログインも必要です。Claude Code プラグインとして入れたスキルは keelson login では自動更新されず、Claude Code のプラグイン更新で追随します。

配置先や更新方法は CLI コマンドを参照してください。

4. デプロイを依頼する

エージェントのチャットに次のように依頼します。

このアプリを Keelson にデプロイして

エージェントがデプロイを開始します。初回の完了には数分かかります。デプロイの開始時には、デプロイ ID と、次のようなアプリの URL が発行されます。

https://<ワークスペース>--hello.keelson.run

AI エージェントを使わない場合は、keelson-hello フォルダで次のコマンドを実行します。

keelson deploy --new

URL はデプロイの完了前にも発行されます。URL が表示された時点では、まだビルドや起動の途中の場合があります。URL を開く前に、次のコマンドで状態を確認してください。<deploy-id> は、デプロイ時に表示された ID に置き換えます。

keelson status <deploy-id>

たとえば ID が d1 なら、keelson status d1 を実行します。status: completed と表示されれば、デプロイの処理は完了しています。続けて手順 5 でアプリが実際に開けることを確認してください。

queued、building_image、starting などの場合は処理中です。少し待ってから、同じコマンドでもう一度確認してください。failed や rolled_back の場合は成功していません。表示された理由と次に必要な操作を確認してください。詳しくはトラブルシューティングを参照してください。

5. アプリの表示とログインを確認する

1. 発行された URL をブラウザで開きます。ログイン画面が表示された場合は、Keelson にログインしてください。「こんにちは、… さん」と本文が表示されることを確認します。
2. Keelson にログインしていないシークレットウィンドウで同じ URL を開きます。アプリではなく、Keelson のログイン画面が表示されることを確認します。

「ゲスト」と表示される場合も、未ログインという意味ではありません。このサンプルでは、ログイン方法によってメールアドレスを取得できない場合に「ゲスト」と表示します。

これで、ログインした人だけが使えるアプリを専用 URL で開けるようになりました。デプロイしたアプリは Keelson コンソールにも表示されます。

次のステップ

• 同僚に共有する — 同僚を招待し、相手のアカウントでアプリを開けることを確認します。手順はチームにアプリを共有するを参照してください。
• 表示を変えて更新する — main.py の文言を変えて、もう一度「デプロイして」と頼みます。更新内容を反映する方法と、以前のバージョンに戻す方法は更新と復元を参照してください。
• 自分のアプリをデプロイする — 対応アプリと制約で対応状況を確認し、持ち込みガイドで準備を進めます。
• 仕組みを理解する — 基本コンセプトで、ワークスペースやアクセス権、Keelson とアプリの役割分担を確認します。