Stavrobot

Stavrobotは「AIアシスタントに必要なアクセス権はすべて、それ以上は与えない」という原則に基づいて構築されたパーソナルAIアシスタントです。

AIアシスタントとしての便利な機能をすべて備えつつ、サンドボックス化、分離、最小権限に重点を置いています。軽量で、docker compose up だけでデプロイできます。

機能

• セキュア。 すべてがコンテナ内で動作し、ホストOSはAIから完全に見えません。AIは、あなたが望まない限り、いかなるシークレットも見ることができません。
• 軽量。 コンポーネントごとにコンテナを動かすことはありません。プラグインはすべて単一のコンテナ内で、Unixパーミッションによって分離されて動作します。
• 好きなモデルを使用可能。 ローカル、OpenRouter、Anthropic/OpenAI。Pi がサポートするものであれば、このボットは何でも利用できます。
• Signal/Telegram/WhatsApp/Email連携。 フォーマットや添付ファイルなどを備えた双方向メッセージング。
• Pebble Index連携。 リングの録音をエージェントに直接キューイングできます。
• 3層のナレッジ。 コンテキストを溢れさせることなく、すべてを記憶します。メモリからインテリジェントかつ透過的にデータを取得します。
• 低トークン使用量。 トークン使用量を抑えるためのさまざまな最適化が施されています。内部的には TOON さえ使用しています。
• プラグイン。 gitリポジトリのURLを渡すだけで、プラグインをインストールしてStavrobotの機能を拡張できます。プラグインは互いに分離されており、それぞれが専用のシステムユーザーとして動作し、他のプラグインのファイルや設定にアクセスできません。
• サブエージェント。 メインエージェントは、独自の会話コンテキスト、システムプロンプト、制限されたツールアクセスを持つサブエージェントを作成できます。外部の人と話してタスクを完了したり物事を調整したりする際に、外部の人とメインエージェントの間にバッファを設けたい場合に便利です。
• 自己プログラミング。 エージェントは自分自身をプログラムし、拡張できます。
• サンドボックス化されたPython実行。 uv を介したpip依存関係を伴う任意のPythonを、ホスト環境から分離して実行できます。
• スケジューリング。 エージェントは自身の定期的または単発のタスクをスケジュールできます。

クイックスタート

AI支援インストール: コーディングAI（Claude Code、Cursor、Windsurfなど）に https://stavrobot.stavros.io/INSTALL.md を取得して従うよう指示してください — セットアップ全体を対話的に案内してくれます。

手動インストール:

1. Telegramで @BotFather にメッセージを送ってボットを作成し、トークンをコピーします。@userinfobot にメッセージを送ってTelegramユーザーIDを取得します（これがチャットIDとして使用されます）。

2. env.example を .env にコピーし、POSTGRES_PASSWORD を安全なものに、TZ をあなたのタイムゾーンに変更します。

3. config.example.toml を data/main/config.toml にコピーし、必須フィールドを入力します: apiKey、password、publicHostname、[owner].name、[owner].telegram（あなたのチャットID）、[telegram].botToken。ファイル内のそれ以外はすべて任意です。

4. docker compose up --build

以上です。Telegramでボットにメッセージを送れば応答します。Signal、WhatsApp、メール、その他のオプションについては、以下の詳細なセットアップセクションを参照してください。

セットアップ

設定

1. config.example.toml を data/main/config.toml にコピーします。
2. APIキーと設定を入力します。サンプルファイルには各セクションを説明するコメントがあります。
3. 最低限、authFile（または apiKey）と publicHostname を設定します。それ以外はすべて任意です。
4. env.example を .env にコピーし、タイムゾーン（TZ）を設定します。Postgresの認証情報やその他の環境設定もそこで上書きできます。POSTGRES_PASSWORD は必ず安全なものに設定してください — デフォルトは弱いプレースホルダーであり、本番環境で使用すべきではありません。

設定エディタ

アプリの起動後、/settings/config を開くとブラウザで config.toml を編集できます。この ページはHTTP Basic認証で保護されており、含まれるシークレットを含む生の設定を表示します。 有効な保存は単一の <CONFIG_PATH>.bak バックアップを作成し、新しい内容を保存して、 アプリを再起動します。これは進行中のエージェントのターンを中断します。

plugin-runner、coder、signal-bridge、python-runner は起動時にのみ config.toml を読み込みます。パスワードなど、これらに影響する変更は、それらのコンテナを 手動で再起動する必要があります。

カスタムおよびOpenAI互換エンドポイント

Stavrobotは、config.toml で baseUrl を設定することで、任意のOpenAI互換エンドポイント（Ollama、LiteLLM、vLLMなど）やカスタムのAnthropic互換プロキシを指定できます。必須フィールドと設定例については config.example.toml を参照してください。

認証

アプリは2つの認証モードをサポートしています: APIキーまたはOAuthです。

• APIキー: config.toml で apiKey を設定します。ログインやログアウトは不要です。
• OAuth: config.toml で authFile を設定します（認証情報が保存されるパス）。ログインページはPiがサポートする任意のOAuthプロバイダーで動作します。
  • ログイン: ブラウザで <your-hostname>/login にアクセスします。ページのプロンプトに従うと、認証情報が認証ファイルに保存されます。ボットの実行中に認証が期限切れになった場合、メッセージングプラットフォーム経由でログインURLを含むメッセージがあなたに送信されます。
  • ログアウト: authFile パスにあるファイルを削除します。ボットは次のメッセージで認証情報の欠落を検出し、再度ログインするよう促します。

Claude Codeのセットアップ

coder コンテナは任意です（自己プログラミング機能にのみ必要です）。これはメインアプリのAPIキーとは別に、サブスクリプション認証（OAuth）でClaude Codeを使用します。

Docker Composeのプロファイルはカンマ区切りなので、組み合わせることができます（例: COMPOSE_PROFILES=signal,coder）。

1. .env ファイルの COMPOSE_PROFILES に coder を含めます（例: COMPOSE_PROFILES=coder、Signalも使用する場合は COMPOSE_PROFILES=signal,coder）。
2. コンテナを起動します: docker compose --profile coder up --build
3. ログインします: docker compose exec -u coder coder claude（まだログインしていない場合はログインを促されます）。
4. ブラウザベースのOAuthフローに従います。
5. 設定の [coder].model をClaude Codeのモデルエイリアス（sonnet、opus、haiku）に設定します。

Signalのセットアップ

Signalには別の電話番号が必要です — あなたの個人番号ではありません。プリペイドSIMやVoIP番号で動作します。

1. .env ファイルの COMPOSE_PROFILES=signal をコメント解除して、signal-bridgeコンテナを有効にします。
2. コンテナをビルドします: docker compose --profile signal build
3. コンテナでSignalを登録します（いずれかを選択）:
   • 既存のSignalアカウントにリンクする: docker compose --profile signal run --rm --entrypoint bash signal-bridge -c 'signal-cli link -n "Stavrobot" | tee >(xargs -L 1 qrencode -t utf8)' — スマートフォンでQRコードをスキャンします（Signal > 設定 > リンクされたデバイス）。
   • 新しい番号を登録する: docker compose --profile signal run --rm --entrypoint bash signal-bridge -c 'signal-cli -u +YOUR_NUMBER register'、その後 docker compose --profile signal run --rm --entrypoint bash signal-bridge -c 'signal-cli -u +YOUR_NUMBER verify CODE' で確認します。
4. 設定で [signal].account を設定します。
5. コンテナを起動します: docker compose up --build
6. 初回起動後、/settings Web UIで許可する番号を追加します。
7. 重要: signal-cliは、まだメッセージを送っていない連絡先の電話番号を解決しません。ボットがそれらからの受信メッセージを受信して識別できるようになる前に、各連絡先へ電話番号宛に最初のメッセージを送る必要があります。オーナーに対してこれをトリガーするには、次を実行します: ``` docker compose exec app node -e "fetch('http://localhost:3001/chat',{method:'POST',headers:{'Content-Type':'application/json'},body:JSON.stringify({message:'Send the message "Hello from Stavrobot" to my Signal number.'})}).then(r=>r.text()).then(console.log)"

8. 詳細については、signal-cli quickstartを参照してください。

Telegram のセットアップ

1. Telegram で @BotFather にメッセージを送り、新しいボットを作成して、トークンをコピーします。
2. Telegram で @userinfobot にメッセージを送り、ユーザー ID を取得します（これがチャット ID として使用されます）。
3. 設定の [telegram].botToken を設定します。
4. 設定の [owner].telegram にチャット ID（携帯電話番号ではありません）を設定します。
5. 初回起動後、/settings Web UI から許可するチャット ID を追加します。
6. アプリの起動時に Webhook が自動的に登録されます。

WhatsApp のセットアップ

WhatsApp には別の電話番号が必要です。そうでないと自分自身にメッセージを送ることになり、実際にはうまく機能しません。

WhatsApp は Baileys を使用します。これは WhatsApp Web のようにコンパニオンデバイスとしてリンクする非公式の WhatsApp Web ライブラリです。別の電話番号は不要で、既存の WhatsApp アカウントにリンクします。

リスク: Baileys は非公式 API を使用しています。WhatsApp はこれを使用するアカウントを BAN する可能性があります。自己責任で使用してください。

1. config.toml に [whatsapp] セクションを追加します（形式については config.example.toml を参照してください）。
2. コンテナを起動します: docker compose up --build
3. アプリのログに QR コードが表示されます（docker compose logs -f app）。
4. スマートフォンで WhatsApp を開き、リンク済みデバイスに移動して、QR コードをスキャンします。
5. セッションは ./data/whatsapp に保存され、再起動後も維持されます。
6. /settings Web UI から許可する電話番号を追加します。

メールのセットアップ

メールは受信配信に Cloudflare Email Worker を、送信に SMTP を使用します。完全な worker コードと詳細なセットアップ手順については config.example.toml を参照してください。

1. config.toml に SMTP 認証情報とランダムな webhookSecret を含む [email] セクションを追加します。
2. Cloudflare Email Worker（コードは config.example.toml 内）をデプロイし、worker に WEBHOOK_URL と WEBHOOK_SECRET 環境変数を設定します。
3. Cloudflare Email Routing で、受信メールを worker に転送するルールを追加します。
4. /settings Web UI から許可する送信元アドレスを追加します。

Pebble Index のセットアップ

Pebble Index を設定して、Stavrobot で設定されたパスワードを使用した HTTP Basic 認証で POST /pebble-index/webhook にリング Webhook を送信するようにします。マルチパートリクエストには recordedAt（エポックミリ秒）と client を含める必要があり、transcription と audio/mp4 の audio ファイルを含めることもできます。音声録音は .m4a 添付ファイルとしてエージェントのキューに追加されます。

実行```bash

docker compose up --build

API は `http://localhost:10567/chat` で利用できます。エンドポイントの完全なリストについては [HTTP API](#http-api) を参照してください。

**注意:** Docker Compose はアプリを `localhost:10567` でのみ公開します。外部からアクセスできるようにするには（Telegram/Signal の Webhook および `publicHostname` 設定に必要）、`localhost:10567` を指すリバースプロキシ（例: Nginx、Caddy）を設定してください。ポートを直接公開することもできますが、トラフィックが暗号化されないため推奨されません。

### Docker を使用しない場合

Node.js >= 20 と、稼働中の PostgreSQL インスタンスが必要です。```bash
npm install && npm run build && npm start

注: Python の実行と Signal 連携は Docker コンテナ内でのみ動作します。

HTTP API

すべてのエンドポイントは config.toml の password を使った HTTP Basic 認証を必要とします (ユーザー名は無視されます)。ただし、以下で public と記されたものを除きます。エラー応答は {"error": "..."} という形式の JSON オブジェクトです。

POST /chat