Odysseus 実戦デプロイ：30分で自前ホストのAI作業スペースを組み上げる

一言でいうと：ChatGPT／Claude のWeb画面から「脱出」して、AI作業スペース一式を自分のマシンに丸ごと載せたいですか？ この記事では Odysseus を実際に動かしながら解説します。ローカル重視・プライバシー重視の ChatGPT 自前ホスト代替品です。

プロジェクト概要

Odysseus は、**自前ホスト型の AI 作業スペース（Self-hosted AI Workspace）**で、GitHubユーザー pewdiepie-archdaemon による MIT ライセンスのオープンソースです。やりたいことはシンプルで、あなたのPC上で ChatGPT / Claude のような UI 体験を得つつ、データ・会話・ツール呼び出しはすべてローカルに留めること。

従来の ChatGPT 系アプリと比べると、違いはかなり明確です：

• チャット：任意のローカル/リモートモデル（vLLM / llama.cpp / Ollama / OpenRouter / OpenAI / GitHub Copilot）を接続可能
• エージェント：本当に「手を動かす」代理機能。MCP / Web / ファイル / Shell / Skills / 記憶（opencode ベース）に対応
• Cookbook：あなたのマシンのハードウェアを自動スキャンし、動かせるモデルを提案。ワンクリックでダウンロード＋起動サービス（llmfit に基づく、VRAM対応）
• Deep Research：多段階リサーチ。取得＋読み込み＋統合して、可視化されたレポートを出力（改造：Tongyi DeepResearch）
• Compare：複数モデルを盲テストで比較し、偏りなく「本当に使えるもの」を選別
• Documents：あなたが文章を書く。AIが横で補助する。逆ではない
• Memory / Skills：長期記憶＋スキルシステム。使うほど代理があなたを理解する（ChromaDB + fastembed ONNX）
• Email：IMAP/SMTP の受信ボックス。AI が自動で分類・要約・下書き返信・迷惑メール対策
• Notes & Tasks / Calendar：ノート＋タスク＋カレンダー。CalDAV 同期（Radicale / Nextcloud / Apple / Fastmail）
• PWA対応：スマホでもデスクトップに負けない使い勝手。ホーム画面にも追加可能

一言でいうと：チャットボックスではありません。あなたのAI作業環境そのもので、全部あなたのマシン上で動き、クラウドには上げません。

難易度 / 所要時間 / 得られるもの

• 難易度：⭐︎⭐︎⭐︎（中級。Docker / Python の基礎が必要）
• 所要時間：30–45分（Docker 経路）／1時間（ネイティブ導入＋ローカルモデル接続）
• 得られるもの：
  • 機能がフルの自前ホスト型 AI 作業スペースを一式動かせる
  • ローカル優先の AI アプリにありがちな典型アーキテクチャを理解できる（FastAPI + ChromaDB + SearXNG + ntfy）
  • Ollama / vLLM / OpenAI 互換 API を同じ画面にまとめて接続できる
  • Cookbook の「自動モデル選定」「GPU透過」「記憶システム」など、いわゆる“ロングテール”だけど気持ちいい能力を把握できる

対象読者

• ChatGPT Plus / Claude Pro をもう払い続けたくない。AIデータはローカルに置きたい
• NUC / ワークステーション / サーバ（8G / 16G / 24G のVRAM）でオープンモデルを回し、統一UIがほしい
• フルスタック／独立開発者。チャット／メール／カレンダー／エージェントのタスクを1つのパネルにまとめたい
• 「自前ホスト」に興味のある運用担当／プラットフォームエンジニア。実運用レベルの FastAPI アプリのエンジニアリング雛形を見たい
• クラウドのLLMに既に課金していて、もう少し痛くない使い方を探している人

軽量なチャットUIだけ欲しいなら、Odysseus は必ずしも最適ではありません。機能が多く、Open WebUI より少し複雑に見えるはずです。ただ、その代わりにメール、記憶、Cookbook、エージェント一式が手に入ります。

コア依存関係と環境

最低構成：

任意 / 強化依存：

完全なプロジェクト構造ツリー

odysseus/
├── app.py                    # FastAPI の入口
├── setup.py                  # 初期化スクリプト（admin／DB／ディレクトリ作成）
├── requirements.txt          # コア Python 依存
├── requirements-optional.txt # 任意依存（PDF/Office/音声/STT）
├── docker-compose.yml        # デフォルト編成（CPU）
├── docker-compose.gpu-nvidia.yml  # NVIDIA GPU 用のオーバーライド
├── docker-compose.gpu-amd.yml     # AMD ROCm 用のオーバーライド
├── Dockerfile
├── core/                     # インフラ層
│   ├── auth.py               # 認証／セッション
│   ├── database.py           # SQLAlchemy の初期化
│   ├── middleware.py
│   ├── constants.py
│   └── atomic_io.py
├── src/                      # 業務ロジック層
│   ├── llm_core.py           # 大規模モデルの抽象
│   ├── agent_loop.py         # エージェントループ
│   ├── agent_tools.py        # エージェントツールセット
│   ├── chat_processor.py     # チャット処理
│   ├── cookbook_serve_lifecycle.py  # Cookbook のモデルサービスライフサイクル
│   ├── memory_vector.py      # ChromaDB の長期記憶
│   ├── deep_research.py      # 深掘りリサーチ
│   └── ...
├── routes/                   # FastAPI ルーティング（40+ モジュール）
│   ├── chat_routes.py
│   ├── agent_routes.py
│   ├── cookbook_routes.py    # モデル推薦／ダウンロード
│   ├── memory_routes.py
│   ├── email_routes.py
│   ├── calendar_routes.py
│   └── ...
├── services/                 # バックエンドサービス
│   ├── docs/                 # ドキュメント処理
│   ├── hwfit/                # ハードウェアスキャン（Cookbook）
│   ├── memory/               # 記憶サービス
│   ├── research/             # リサーチサービス
│   ├── search/               # 検索
│   ├── stt/ tts/             # 音声→文字／文字→音声
│   └── shell/                # Shell ツール
├── static/                   # フロントエンド（index.html + JS/CSS）
├── docs/                     # ドキュメントサイト + スクリーンショット + デモ
├── config/                   # SearXNG などサブサービスの設定
├── companion/                # デスクトップ伴走（macOS）
└── data/                     # ユーザーデータ（gitignored、実行時に生成）
    ├── app.db                # SQLite
    ├── chroma/               # ベクトルDB
    ├── uploads/
    ├── personal_docs/
    └── huggingface/          # モデルキャッシュ

フォルダ内で気にするのは app.py / docker-compose.yml / .env の3ファイルだけです。ほかは Docker が面倒を見てくれます。

手順

ステップ 1：リポジトリをクローン

git clone https://github.com/pewdiepie-archdaemon/odysseus.git
cd odysseus

ステップ 2：.env を準備（任意ですが推奨）

cp .env.example .env

最小限で使える .env はこんな感じです：

# === LLM 接続ポイント ===
LLM_HOST=localhost
# クラウドAPIを使うなら、コンテナ内で host.docker.internal を使ってローカルOllamaにアクセス
OLLAMA_BASE_URL=http://host.docker.internal:11434/v1

# === ポートとバインド ===
APP_BIND=127.0.0.1
APP_PORT=7000

# === セキュリティ（重要！） ===
AUTH_ENABLED=true
LOCALHOST_BYPASS=false
SECURE_COOKIES=false   # リバースプロキシでHTTPSを使う場合のみ true に
ODYSSEUS_ADMIN_USER=admin
# ODYSSEUS_ADMIN_PASSWORD=  # 設定しないと初回起動時にランダム生成され、ログに出力

# === 検索（SearXNG） ===
SEARXNG_INSTANCE=http://searxng:8080

OLLAMA_HOST=0.0.0.0:11434 ollama serve

ステップ 3：Docker で一発起動（推奨ルート）

docker compose up -d --build

ビルドではベースイメージの取得＋Python依存のインストールを行います。初回はだいたい 3〜5分です。odysseus／chromadb／searxng／ntfy の4つのコンテナがすべて healthy または running になったら完了です：

docker compose ps

http://localhost:7000 を開きます。最初の画面はログインページです。初期 admin パスワード はターミナルログに出ます：

docker compose logs --tail=200 odysseus | grep -i "temporary\|admin\|password"

例えば、次のように表示されるはずです：

[odysseus] Created admin user 'admin' with temporary password: aB3x-9pQz-2vRt

ステップ 4：サービスが全てヘルシーか確認

# 1. コンテナ状態
docker compose ps

# 2. Odysseus 自身のログ確認（初回はモデル取得で遅延あり）
docker compose logs --tail=120 odysseus

# 3. ChromaDB が本当に起動しているか（HTTP にフォールバックしていないか）
docker compose logs odysseus | grep -E "ChromaDB|MemoryVectorStore|DEGRADED"

DEGRADED が出た場合、ほとんど chromadb-client と chromadb の競合が原因です。調べ方は後述の「よくある質問」を参照してください。

ステップ 5：最初のモデルを接続

Settings → Models / Providers に入って、あなたの環境に応じて次のどれかを選びます：

ルートA：すでに Ollama が起動済み（最も簡単）

Base URL:  http://host.docker.internal:11434/v1
API Key:   （空欄のままでOK）
Model:     qwen2.5:7b（または手元の任意のモデル）

ルートB：Cookbook による自動ダウンロード＆起動

Cookbook に入ると、GPU（VRAM）をスキャンして、動かせるオープンモデルを提案します。スコア（fit score）付き。「Download」 を押すと huggingface-cli でモデルを ./data/huggingface/ にダウンロードし、その後 llama.cpp / vLLM を直接 serve して起動します。

ルートC：クラウド側APIを接続 — ここは今日じっくり話します

Odysseus の Provider 設定は **プロトコル駆動（protocol-driven）**です。つまり、v1/chat/completions または v1/messages の2つのエンドポイントに対して正しく応答できるサービスであれば、そのまま Base URL を入れて接続できます。OpenAI / Anthropic の公式だけでなく、自作ゲートウェイやサードパーティの中継も同様です。

私のデプロイでは、「日常の Agent がコード実行／長文ドキュメント」という用途はクラウド側APIを使っています。理由は2つです：

1. ローカルの24G GPUで70B量子化を回すだけでもきつい。さらに Agent を多段呼びすると OOM になりがち
2. Claude / GPT のような最先端モデルは、複雑な推論では Qwen2.5-Coder より一段上

ただし問題もあります — 公式APIが高すぎる。Claude Opus は週の請求だけで簡単に100ドルを超えます。個人が遊ぶ分には、完全に Anyscale のために働くことになります。

そこで、私は Defapi を使い、v1/messages に対応したエンドポイントで接続しています：

# Odysseus Settings → Custom Anthropic Provider
Base URL:  https://api.defapi.org
API Key:   sk-xxxxx                    # defapi.org の管理画面で取得
Model:     anthropic/claude-sonnet-4.5 # または haiku-4.5 / opus-4.6

設定例：Defapi Claude Sonnet 4.5（プログラミング／長文ドキュメントの主力）、Claude Haiku 4.5（日常の Agent 呼び出し向け、安い）。

実測では、同じ会話量／タスク量でも、月額請求は Anthropic の公式に接続した場合よりかなり下がります。しかもモデル能力、Agent のツール呼び出し、prompt フォーマットなどの差はありません。これは、Defapi がプロトコル層の代理であり、モデル自体は結局同じだからです。こうした Odysseus の 「プロトコル駆動」設計とも自然に噛み合います。

ルートD：GitHub Copilot / OpenRouter などを接続

これらも OpenAI プロトコル互換です。Base URL をそれぞれ https://api.githubcopilot.com / https://openrouter.ai/api/v1 に入れるだけなので、ここでは深掘りしません。

ステップ 6：最初のチャット＋最初の Agent タスク

メイン画面に戻って、モデルを選び、簡単なプロンプトで疎通テストします：

あなた自身を3文で紹介して、それから今日使えるLinuxの性能トラブルシューティング用チェックリストをください。

通れば、LLM 経路は確実に繋がっています。

次に Agent モード を試します。新規セッションを作り、「Agent」に切り替えて、こう入力：

現在のディレクトリ配下のすべての .py ファイルについて行数を列挙し、どのファイルが最もリファクタリングに値するか教えてください。

Agent は勝手に段取りを組みます：

1. shell ツールで find . -name "*.py" | xargs wc -l を実行
2. 結果を受け取って判断
3. 提案を返す

これがローカル優先の Agent と ChatGPT Web の決定的な違いです。実際に手を動かします。あなたのコードやファイル、ターミナルに対してアクセス権を持つからです。

ステップ 7（任意）：GPU を有効化

このステップはvLLM / SGLang / llama.cpp CUDA のような“重い”ローカル推論を使う場合に限って必要です。Ollama やクラウドAPIだけならスキップしてください。

NVIDIA：

# 一括診断
scripts/check-docker-gpu.sh

# NVIDIA Container Toolkit を導入（Ubuntu/Debian、sudo が必要）
scripts/check-docker-gpu.sh --install-nvidia-toolkit

# GPU の透過が成功してから overlay を有効化
scripts/check-docker-gpu.sh --enable-nvidia-overlay

# 確認
docker compose exec odysseus nvidia-smi -L

.env に次の設定を追加します：

COMPOSE_FILE=docker-compose.yml:docker/gpu.nvidia.yml

AMD ROCm：

scripts/check-docker-amd-gpu.sh
# 出力された RENDER_GID を .env に書き込む

COMPOSE_FILE=docker-compose.yml:docker/gpu.amd.yml
RENDER_GID=989

ステップ 8（任意）：Playwright MCP（ブラウザ代理）を有効化

Odysseus にはいくつかの MCP server が同梱されていますが、ブラウザ側のものは先に npx で取得する必要があります：

npx -y @playwright/mcp@latest --version

Odysseus コンテナを再起動すると、Agent でブラウザの MCP が使えるようになります（スクリーンショット、ナビゲーション、フォーム入力など）：

https://news.ycombinator.com を開き、先頭10件のタイトルとリンクを取得して、5つのコア話題に要約してください。

ステップ 9（任意）：Windows でネイティブに実行

git clone https://github.com/pewdiepie-archdaemon/odysseus.git
cd odysseus
powershell -ExecutionPolicy Bypass -File .\launch-windows.ps1

スクリプトが自動で venv を作成→依存をインストール→setup → uvicorn 起動まで行います。http://localhost:7000 を開きます。

ステップ 10（任意）：スマホからも使えるようにする

Tailscale がすでに接続済みの前提で：

ODYSSEUS_HOST=0.0.0.0 docker compose up -d
# もしくは .env に書く
APP_BIND=0.0.0.0

ただし、素のHTTPをLAN／Tailscaleにそのまま露出するのは危険なので、強く mkcert の HTTPS を追加することをおすすめします：

mkcert -install
mkcert -cert-file cert.pem -key-file key.pem 100.x.y.z   # あなたの Tailscale IP

python -m uvicorn app:app --host 0.0.0.0 --port 7000 \
  --ssl-certfile=cert.pem --ssl-keyfile=key.pem

スマホから https://<tailscale-ip>:7000 を開き、PWA をホーム画面にインストールすれば、体験はほぼネイティブアプリ同等です。

よくある問題の切り分け

Q1：7000ポートが占有される（macOSでよくある）

macOS の AirPlay がデフォルトで 7000 を使っています。解決策は2つです：

# 方法1：.env でポートを変更
APP_PORT=7001
docker compose up -d
# ブラウザは http://localhost:7001 を開く

# 方法2：Appleメニュー → システム設定 → 一般 → AirPlay レシーバ → オフ

Q2：ChromaDB は起動するが、ログに DEGRADED と出る

通常、chromadb-client と chromadb を同時にインストールしており、静かに HTTP のみのモードにフォールバックして、ベクトル機能が落ちています。修復：

# 実行しているコンテナ内（またはローカルの venv）で
./venv/bin/pip uninstall chromadb-client -y
./venv/bin/pip install --force-reinstall chromadb
docker compose restart odysseus

修復の検証：docker compose logs odysseus | grep -E "ChromaDB|MemoryVectorStore" で初期化成功が見えるはずで、DEGRADED は出なくなります。

Q3：Cookbook で私の GPU が見えず、iGPU か CPU しか表示されない

Docker は通常、ホストの GPU を全部公開しますが、iGPU だけや別のカードしかマウントできていない場合がほとんどです。たいていは NVIDIA Container Toolkit が未導入／未設定で、nvidia-ctk runtime configure --runtime=docker ができていません。

# 診断
scripts/check-docker-gpu.sh
# 出力を見れば、どこが欠けているか分かります

# 一括インストール＆設定（Ubuntu/Debian）
scripts/check-docker-gpu.sh --install-nvidia-toolkit
sudo nvidia-ctk runtime configure --runtime=docker
sudo systemctl restart docker

Q4：GPU は透過できたのに、llama.cpp のログに Unable to find cudart が出る

問題はありません。足りないのは **CUDA 実行時（runtime）**です。この部分は Docker が面倒を見るところではないので、Cookbook → Dependencies で llama-cpp-python の CUDA ビルドを再インストールしてください。

Cookbook → Dependencies を開き、llama-cpp-python を見つけて Reinstall（CUDA ビルド）

それが自動で pip install --no-cache-dir llama-cpp-python[cuda] を行い、約2〜3分です。

Q5：Outlook / Office 365 のメールに接続できない

Odysseus のメールモジュールは現在 IMAP + ユーザー名／パスワード 認証のみ対応しています。Microsoft は2024年以降、通常のパスワードログインをほぼ全面的に禁止しており、OAuth が必要です。これは現時点での既知の制限です。

暫定策：Gmail / Fastmail / 自前のメールを使うか、2FA付きのアカウントなら Microsoft App Password を作って「パスワードログインの代わり」にします。

Q6：インターネット公開したい。どうすれば安全？

直接 APP_BIND=0.0.0.0 でインターネットに露出するのは災害です。LOCALHOST_BYPASS は認証を迂回し、Agent には shell ツールもあります。Shodan なら24時間で裸のインスタンスが大量に見つかります。

正しいやり方：

[Internet] → Cloudflare Access / Tailscale / WireGuard
            → Caddy / Nginx / Traefik（HTTPS終端）
            → http://127.0.0.1:7000（Odysseus：localhostバインドのまま）

さらに .env で：

AUTH_ENABLED=true
LOCALHOST_BYPASS=false
SECURE_COOKIES=true

Q7：クラウドAPIの課金をどう抑える？

ここでは、手順5のルートCについてもう少し具体化します。

個人で使ってみた感想を、コストの高い順から3つの発想で並べます：

1. 公式APIに接続 — 体験は最も完全、ただし課金が最も高い。Claude Opus + Agent の頻繁な呼び出しで、週100ドル超えは普通に起こります
2. プロトコル互換の中継層を接続（私は Defapi を使用） — 同じ Claude / GPT / Gemini モデルでも、公式に比べて月額が一段下がります（どれくらいかは厳密に計算していませんが、週100ドル台が月額100ドル台に収まるようなオーダーです）。利点はプロトコル層が完全互換なこと。Odysseus 側の設定はそのままで、prompt や Agent のコードを一切変える必要がありません
3. ローカル量子化モデル — Cookbook で Q4_K_M の GGUF を入れれば、16G VRAMで30B級が動かせます。APIコストはゼロですが、推論速度はクラウドより遅く、複雑タスクの品質も一段落ちます

私の実運用の組み合わせ：チャット＋Deep Research は Defapi の Claude Sonnet 4.5、Agent のツール呼び出しは Claude Haiku 4.5（安い）、そして簡単な分類／要約はローカルの Qwen2.5 量子化版。3つの Provider はそれぞれ別課金で干渉せず、1ヶ月で人民元の二桁（数十元）です。

追加の読み物 / 進む方向

• MCP エコシステム：Odysseus が自動登録する内蔵 MCP は playwright（ブラウザ）／filesystem／shell を含みます。自分で MCP server を書いて mcp_servers/ に登録すれば、Agent から使えます
• Skills システム：routes/skills_routes.py で再利用可能な「スキル断片」を管理。OpenClaw の Skills 類似で、1回書けばあらゆるセッションから呼び出せます
• Tailscale + mkcert の HTTPS：前のセクションで基本手順を示しました。発展として自動更新や DNS-01 チャレンジも追加できます
• リバースプロキシ構成：Caddy の HTTPS 設定＋Cloudflare プロキシで、運用ゼロのインターネット公開が可能になります
• CalDAV 同期：自前の Radicale（軽量 CalDAV サービス）を使えば、Odysseus のカレンダーをスマホのシステムカレンダーと双方向同期できます
• Email AI 自動振り分け：IMAP を接続したら、一定期間トレーニングすることで「緊急／一般／迷惑」といった分類を自動化できます。下書きも先に書かれるので、あなたは送信するだけ
• Cookbook のリモートサーバ：Cookbook → Settings → Servers で遠隔の GPU マシンを設定し、推論／モデル取得を SSH 経由で行えるようにする（ホストは小さく、GPUは遠く、設定もきれいに整う）
• Deep Research：多段レポート：Alibaba の Tongyi DeepResearch を改造。SearXNG で複数ソース取得→要約→統合。競合調査／業界リサーチに向いています
• 複数 Provider ルーティング：Odysseus でチャット／Agent／リサーチに別々の Provider を割り当てる。ローカル Ollama が日常の会話の80%を担当し、複雑な問題だけクラウドに投げる。コストも体験もバランスできます

GitHub リポジトリ：pewdiepie-archdaemon/odysseus。ドキュメントは docs/ ディレクトリ、ロードマップは ROADMAP.md。貢献したい場合は CONTRIBUTING.md を参照してください。