メインコンテンツへ移動
AIチュートリアル

フルスタックAIチャットアプリ「Whirl」をセルフホストする方法

Whirlをローカルにインストールして実行し、必要なサービスに接続して最初のAI会話を始める方法と、オプション機能について説明します。リポジトリの構成、プライバシー機能、設定方針、セルフホスト環境を準備するための実践的なヒントも紹介します。

約12分で読了
フルスタックAIチャットアプリ「Whirl」をセルフホストする方法

Whirlとは？

Whirlは、Next.jsとConvexで構築されたオープンソースのフルスタックAIチャットアプリケーションです。whirl.chatのコードベースであり、MITライセンスの下で提供されています。そのため、コードを確認したり、自分のインスタンスを実行したり、改善に貢献したりできます。

このプロジェクトは、複数のAIモデル、永続メモリ、編集可能なアーティファクト、ウェブ調査、カスタムツール、プライバシーを重視した会話を1つのインターフェースに統合します。モデルはOpenRouterを通じてルーティングされ、Convexがデータベース、バックエンド関数、ストリーミング、スケジュール済みジョブを提供します。

主な機能

  • 複数の主要モデル：1つの会話で主要なAIモデルを使い分け、思考レベルを調整できます。
  • 常に進化するアーティファクト：ドキュメント、チャート、インタラクティブなページを作成できます。これらはサイドパネルで編集を続けられ、リンクで共有できます。
  • ツールとスキル：OAuthベースの連携を含む外部ツールをMCP経由で接続し、Whirlの動作を拡張するスキルをインストールできます。
  • 長期メモリ：会話をまたいで好みやプロジェクトのコンテキストを引き継げます。
  • 最新のウェブ情報：ウェブを検索してページを読み取り、最近の情報源に基づいた回答を生成できます。
  • プライベートな会話：ロックされたチャットは、サーバーがパスワードを受け取らない仕組みにより、ユーザーのデバイス上で暗号化されます。保持ゼロモデルのみを使用します。
  • 生産性向上機能：Whirlには、シークレットモード、メッセージのキューイング、音声入力、画像生成、ファイル添付、フォルダー、共有機能が含まれています。
  • カスタマイズ可能なインターフェース：ライトモードまたはダークモードを選択し、アクセントカラーを設定して、Whirlをモバイルウェブアプリとしてインストールできます。

技術スタック

本番用ウェブアプリケーションでは、Next.js 16、React 19、Tailwind CSS v4、Motionを使用しています。Convexがバックエンドを提供し、Clerkが認証を処理し、OpenRouterがAI SDK経由でモデルへのアクセスを提供します。リポジトリはBunワークスペースとして構成され、TypeScriptで記述されています。

コアセットアップに必要なのはConvex、Clerk、OpenRouterのみです。その他のサービスは任意です。

  • 課金用のAutumn
  • ウェブ検索用のExa
  • メモリ用のSupermemory
  • 分析用のPostHogとAxiom
  • トレース用のBraintrust
  • メール用のResend
  • サポートエージェント用のMedian

任意のサービスが設定されていない場合、Whirlはアプリケーションの実行にそのサービスを必須とするのではなく、そのサービスを利用する機能を非表示にします。

前提条件

Whirlをインストールする前に、次のものを用意してください。

  • コンピューターにインストールされたBun
  • 無料のConvexアカウント
  • Clerkアプリケーション
  • OpenRouter APIキー
  • リポジトリのクローンに使用するGit

ステップ1：Whirlをクローンしてインストールする

リポジトリをクローンし、そのディレクトリに移動して、Bunですべてのワークスペース依存関係をインストールします。

git clone https://github.com/whirlchat/whirl.git
cd whirl
bun install

ステップ2：Convexバックエンドを作成する

バックエンドパッケージに移動し、Convexの開発プロセスを開始します。

cd packages/backend
bunx convex dev

初回実行時、Convexがプロジェクトと開発用デプロイメントの作成手順を案内します。開発中にバックエンドの変更を同期できるよう、このプロセスは実行したままにしてください。

ステップ3：バックエンドのシークレットを設定する

packages/backendで別のターミナルを開きます。ClerkのJWT発行者ドメインとOpenRouter APIキーをConvexの環境に追加します。

bunx convex env set CLERK_JWT_ISSUER_DOMAIN https://your-instance.clerk.accounts.dev
bunx convex env set OPENROUTER_API_KEY sk-or-v1-...

例の値を、自分のClerkおよびOpenRouterアカウントの認証情報に置き換えてください。詳しいセルフホスティングのドキュメントでは、Convexに必要なClerk JWTテンプレートについて説明しています。

APIキーや認証シークレットをリポジトリにコミットしないでください。バックエンドのシークレットはConvexの環境コマンドで、ローカルウェブ設定は適切な環境ファイルで管理してください。

ステップ4：ウェブアプリケーションを設定する

本番用ウェブアプリケーションに移動し、提供されているサンプルからローカル環境ファイルを作成します。

cd ../../apps/v2
cp .env.example .env.local

.env.localを開き、ConvexとClerkに必要な4つの値を入力します。変数名を新しく作成するのではなく、正確な変数名についてはサンプルファイルを参照してください。

ステップ5：開発環境を起動する

リポジトリのルートに戻り、開発コマンドを実行します。

cd ../..
bun run dev

サービスが起動したら、localhost:3000を開きます。設定済みのClerkアプリケーションからサインインし、会話を始めてください。

基本的な使い方

会話を始める

チャット入力欄にリクエストを入力し、設定したモデルに送信します。次の簡単な初回プロンプトで、ウェブアプリ、認証、Convexバックエンド、OpenRouter接続が連携して動作していることを確認できます。

このアプリケーションの主なコンポーネントを、簡潔な5つのポイントで説明してください。

モデルを使用する

Whirlでは、会話中にOpenRouterを通じて複数の主要モデルを利用できます。また、アプリケーションと選択したモデルが対応している場合は、調整可能な思考レベルも使用できます。

アーティファクトを作成・改良する

Whirlにドキュメント、チャート、またはインタラクティブページの作成を依頼できます。これらの編集可能なアーティファクトはサイドパネルに表示され、リンクで共有できます。一度きりのチャット応答ではなく、継続的な改良が必要な成果物に便利です。

ファイル、音声、整理機能を使う

Whirlでは、テキストメッセージに加えてファイルの添付や音声入力にも対応しています。会話はフォルダーで整理でき、共有機能を使えば選択した作業を他の人にも公開できます。

リポジトリを理解する

このモノレポには、複数のアプリケーションと共有バックエンドが含まれています。

  • apps/v2: Whirlが使用する本番用のNext.jsウェブアプリケーション。
  • apps/console: モデル、インテグレーション、スキルを管理するViteベースの管理コンソール。
  • apps/mobile: Expoで構築されたネイティブアプリケーション。
  • apps/waitlist: 独立したウェイトリストページ。
  • apps/remotion: プロモーション動画のコンポジション。
  • apps/legacy: 以前のウェブアプリケーション。参照用に残されていますが、現在はメンテナンスされていません。
  • packages/backend: Convexのスキーマ、関数、AIパイプライン。
  • docs: セルフホスティング、設定、アーキテクチャのガイド。
  • brand: ロゴ、カラー、バナー、アプリケーションアイコン。

現在のウェブ開発では、apps/v2とpackages/backendに注力してください。apps/legacyはメンテナンスされていないため、新しい開発には使用しないでください。

高度なヒント

オプションサービスを段階的に追加する

まず、必須のConvex、Clerk、OpenRouterの設定から始めます。コアとなるチャットフローが動作したら、オプションのプロバイダーを一つずつ追加してください。Whirlは、必要なキーがない機能を自動的に非表示にするため、より小規模な構成でも実用的に運用できます。

課金、検索、メモリ、分析、トレーシング、メール、サポートに関連する環境変数については、リポジトリの設定ガイドを参照してください。

適切なプライバシーモードを選ぶ

通常の永続的な会話ワークフローを使用したくない場合は、シークレットモードを使用してください。より強固な保護が必要な場合は、ロック済みチャットを使用できます。ロック済みチャットは、サーバーが知ることのないパスワードで端末上に暗号化され、ゼロリテンションモデルのみが応答します。クライアント側で保持するパスワードを失うと、暗号化されたコンテンツにアクセスできなくなる可能性がある点に注意してください。

メッセージパイプラインを確認する

ストリーミング、ツール呼び出し、またはモデルの動作をデバッグする際は、プロジェクトのアーキテクチャガイドを読んでください。コンポーザーからモデルへ、そしてモデルから戻ってくるまでのメッセージの流れが説明されています。関連する実装は主に本番用ウェブアプリとConvexバックエンドに分かれています。

本番環境に向けて慎重に準備する

クイックスタートで作成されるのは開発環境です。一般公開する前に、Clerk JWTテンプレートと本番デプロイに関する手順を含む、完全なセルフホスティングガイドに従ってください。

安全にコントリビュートする

プルリクエストを作成する前に、規約とチェック項目についてプロジェクトのコントリビューションガイドを確認してください。行動規範に従い、セキュリティ上の問題は公開Issueではなく、SECURITY.mdに記載された手順で報告してください。

まとめ

Whirlは、Next.jsのインターフェース、Convexバックエンド、Clerk認証、OpenRouterのモデルアクセスを組み合わせた、セルフホスト型AIチャットワークスペースの機能豊富な出発点です。まず3つの必須サービスから始め、localhost:3000でローカルチャットを確認してください。その後、デプロイのニーズに応じて、検索、メモリ、分析、課金などのオプション連携を有効にします。