オデッセウス バージョン 1.0：自己ホスト型 AI ワークスペース

オデッセウス (Odysseus) は、ご自身の環境で動作する自己ホスト型 AI ワークスペースです。ChatGPT や Claude などの体験をローカルに再現しつつ、「意図的な乱暴さ」や独自性を追求した設計思想を持っています。

🛡️ 基本方針

• ローカルファースト – データと処理を自環境で完結させます。
• プライバシーファースト – プライバシーを最優先の原則にします。
• トロジャン・ホース非搭載 – 外部サーバーへのデータ送信は行いません。

🚀 主要機能一覧

• チャット

  • ローカルモデルや API を問わずチャットが可能です。
  • 追加設定も極めて簡単です。
  • サポート対応：vLLM · llama.cpp · Ollama · OpenRouter · OpenAI

• エージェント

  • ツールを付与し、タスクを完全に自律させて実行します。
  • 基盤技術：opencode · MCP · Web · ファイル · シェル · スキル · メモリ

• レシピ本（Cookbook）

  • ハードウェアのスキャンを行い、推奨モデルのダウンロード・起動を自動で行います。
  • GGUF / FP8 / AWQ 等形式をサポートし、VRAM 最適化に対応しています。
  • 採用技術：llmfit · フィットスコアリング · vLLM / llama.cpp サービング

• ディープリサーチ

  • 複数のステップに分けてソースの収集・読解・統合を行い、見やすいビジュアルレポートを生成します。
  • 開発ベース：Tongyi DeepResearch の機能を実装。

• 比較

  • モデル同士を並べて比較する楽しいツールです。
  • 完全な盲検テストによりバイアスを排除しています。
  • サポート対応：マルチモデル · 盲検テスト · シンセシス（統合）

• ドキュメント

  • テキストはあなたが書き、AI がサポート役になります。
  • 機能：マルチタブエディタ · Markdown/HTML/CSV · シンタックスハイライト · AI による編集支援・サジェスション

• メモリ / スキル

  • エージェントはあなたやタスクを理解するにつれて進化します。
  • 実装技術：ChromaDB · fastembed (ONNX) · ベクトル検索＋キーワード検索 · インポート/エクスポート機能

• メール

  • IMAP/SMTP の受信トレイに AI による優先度分類機能を組み込みました。
  • 機能：緊急性の通知・自動タグ付け・要約・返信ドラフトの自動生成・スパムフィルタリング
  • 対応プロトコル：IMAP · SMTP · アカウント別ルーティング · CalDAV

• メモとタスク

  • リマインダー付きの簡易メモ、ToDo リスト、スケジュール済みタスクが可能。
  • サポート：ノートピンチ通知 · チェックリスト · クロンのような定時タスク · ntfy/ブラウザ/メールチャンネル

• カレンダー

  • ローカルファーストな設計です。
  • 対応：Radicale / Nextcloud / Apple / Fastmail への CalDAV シンク
  • 機能：.ics ファイルのインポート/エクスポート · カレンダー別色分け · エージェント認知機能

• モバイル対応

  • デスクトップだけでなく、スマートフォンでも美しく動作します。
  • 仕様：レスポンシブデザイン · 装着可能な PWA · タッチジェスチャー対応

• その他機能

  • 画像エディタ · テーマエディタ · ファイルアップロード（ビジョン＋PDF） · Web 検索 · プリセット · セッション · 二段階認証 (2FA) など

🎬 デモツアー

ランディングページ（

docs/index.html

• チャットとエージェントの実演
• ディープリサーチのワークフロー
• モデル比較ツール
• ドキュメント作成支援
• メモとタスク管理機能

🏁 クイックスタート

デフォルト設定ですぐに動作します。リポジトリをクローンして実行し、アプリ内から追加の設定を行います。

初回ログイン後、「設定」パネルを開き、以下の指定を行ってください：

• LLM サーバー
• 検索プロバイダー
• メールアカウントなど

⚠️ 注意:

.env

ファイルへの触り方は限定的です。

AUTH_ENABLED

や

DATABASE_URL

といったデプロイメント全体の値、あるいは初期パスワードの事前設定（

ODYSSEUS_ADMIN_PASSWORD

）が必要な場合に限ります。指定しないと初回起動時にパスワードが自動生成され表示されます。

🐳 オプション 1：Docker インストール（推奨）

手順

git clone <your-odysseus-repo-url>
cd odysseus
cp .env.example .env       # オプションですが、明示的なデフォルトのため推奨
docker compose up -d --build

概要

• docker compose

  コマンドはオデッセウス、ChromaDB、SearXNG、ntfy を起動します。
• 初回実行ではイメージのフルビルドが行われます。
• コンテナが正常に動作した後、

  http://localhost:7000

  にアクセスしてください。

SSH キーとリモートサーバー設定

レシピ本（Cookbook）用のリモートサーバーは、Docker 内の

./data/ssh

1. 「Recipes → Settings → Servers」で公開キーを生成・コピーします。
2. リモートサーバーの

   ~/.ssh/authorized_keys

   に追加してください。

ホスト側からのインストールも可能です：

ssh-copy-id -i data/ssh/id_ed25519.pub user@server

ローカルデータとキャッシュ

• レシピ本のモデルカタログは

  ./data/huggingface

  へ保存されます。
• オデッセウスコンテナ内部では

  ~/.cache/huggingface

  としてマウントされています。

🛠️ 有用な確認コマンド

• コンテナ状態の確認：

  docker compose ps
  

• ログ表示（最新 120 行）：

  docker compose logs --tail=120 odysseus
  

• エラー監視（ChromaDB やメモリストアの状態確認）：

  docker compose logs odysseus | grep -E 'ChromaDB|MemoryVectorStore|DEGRADED'
  

• モデルロード数確認：

  docker compose exec odysseus python -c "from services.hwfit.models import get_models; print(len(get_models()))"
  

🧠 ベクターメモリの起動時期待値

正常に稼働している状態です：

• ChromaDB 接続済み:

  chromadb:8000

• MemoryVectorStore が初期化済み

モデルカタログチェックについて：

• レシピ本のモデルカタログチェックで非ゼロの数字が表示されます。
• もし 「0」 が表示された場合は、以下のコマンドでイメージを再構築してください。

  docker compose build --no-cache odysseus
  

🐧 オプション 2：手動インストール（Linux / macOS）

要件

• Python 3.11 以上が必要です。
• Linux/Termux では、バックグラウンドでのモデルダウンロードやサーバー起動のために tmux も必須です。

システムパッケージのインストール

# Debian/Ubuntu
sudo apt install tmux

# Arch
sudo pacman -S tmux

# Fedora
sudo dnf install tmux

オデッセウスのインストールと起動

git clone <your-odysseus-repo-url>
cd odysseus
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
python setup.py            # データディレクトリを作成し、初期管理者パスワードを表示
uvicorn app:app --host 0.0.0.0 --port 7000

🪟 オプション 3：手動インストール（Windows / PowerShell）

git clone <your-odysseus-repo-url>
cd odysseus
python -m venv venv
venv\Scripts\Activate.ps1
pip install -r requirements.txt
python setup.py
uvicorn app:app --host 0.0.0.0 --port 7000

インストール後は

http://localhost:7000

🔒 セキュリティに関する注意事項

オデッセウスは、シェルアクセス・ファイルアップロード・モデルダウンロードなど強力なローカルツールを備えた自己ホストワークスペースです。管理コンソールとして扱うべきです。

必須セキュリティ対策

• ネットワークからのアクセス: 常に

  AUTH_ENABLED=true

  に設定してください。
• 公開デプロイ: HTTPS と信頼できるリバースプロキシの使用が必須です。
• バージョン管理:

  data/

  や

  .env

  、ログ、データベースなどを Git にコミットしないでください（デフォルトで無視されています）。
• 管理者パスワード: 初回起動後には必ず

  data/auth.json

  を確認し、オープンなサインアップは意図的に行うように設定してください。管理者は自分自身にのみ権限を与え、テストアカウントは非管理者として制限してください。

ユーザー権限とアクセス制御

• デフォルトでは、非管理者ユーザーはシェル・Python・ファイルの読み書きが許可されません。
• MCP 管理や API トークン、Webhooks、モデル提供などは管理者専用です。
• 公開デプロイ前: すべてのユーザの権限を確認してください。

安全運用ガイドライン

• API キーの管理: 共有チャットやログに漏れないよう、定期的にローテーション（更新）してください。
• トークンの分離: 統合ごとに個別の API トークンを作成し、使用されていないものは削除してください。
• バインドアドレス: 手動開発時は

  127.0.0.1

  にバインドし、LAN/共有アクセス時のみ

  0.0.0.0

  を使用してください。
• 公開前の確認: フォークを公開する前に

  git status --short

  を実行し、プライベートファイルがステージングされていないことを確認してください。

🔐 HTTPS への裏付け方法

オデッセウスは標準 HTTP でポートを起動しています。ブラウザから警告が出たり、平文で送信されたりしないよう、TLS ターミネーションを行うリバースプロキシを導入することをお勧めします（Tailscale IP を含む共有環境でも推奨）。

Caddy を使った最短経路（Let's Encrypt 自動更新）

odysseus.example.com {
  reverse_proxy localhost:7000
}

• LAN 限定:

  Caddy + tailscale-cert

  または組み込みの MagicDNS HTTPS で動作します。
• nginx/Traefik: ロカルホストをリバースプロキシし、TLS ターミネーションをプロキシ側で行います。

これにより、ブラウザ警告が消え、ログイン情報が暗号化されます。

🤝 コントリビュート（貢献）

ご協力をお願いいたします。以下が特に歓迎されます：

• 新鮮なインストールテスト
• プロバイダー設定に関するバグ修正
• モバイル/エディタの使いやすさ向上
• ドキュメント作成
• 小規模で焦点を絞ったリファクタリング

詳細は

ROADMAP.md

⚙️ 設定（Configuration）

大部分の設定は

/setup

.env

主要な環境変数

LLM_HOST

localhost

llm-host.local:8000

LLM_HOSTS

--

OPENAI_API_KEY

--

SEARXNG_INSTANCE

http://localhost:8080

AUTH_ENABLED

true

LOCALHOST_BYPASS

false

false

DATABASE_URL

sqlite:///./data/app.db

CHROMADB_HOST

localhost

CHROMADB_PORT

8100

EMBEDDING_URL

--

組み込みサービス（Docker Compose デフォルト）

• ChromaDB – セマンティックメモリのベクターストア。Docker では内部接続用 (

  chromadb:8000

  ) 、外部露出は

  localhost:8100

  。
• SearXNG – Web 検索用のメタ検索。内部接続 (

  searxng:8080

  ) 、外部露出は

  127.0.0.1:8080

  のみ。
• ntfy – ローカル通知サービス。

  localhost:8091

  で露出されます。

オプションの外部サービス

• Ollama – ローカルの LLM サーバー (

  ollama.ai

  )

🏗️ アーキテクチャ

• app.py

  – FastAPI のエントリーポイント

• core/

  – 認証、データベース、ミドルウェア、定数類

• src/

  – llm_core, agent_loop, agent_tools, chat_processor, search など

• routes/

  – チャット、セッション、ドキュメント、メモリ、モデルなどのエンドポイント

• services/

  – ドキュメント処理、メモリ管理、検索、hwfit（レシピ本用）など

• static/

  – index.html + app.js + style.css + js/（モジュラーフロントエンド）

• docs/

  – ランディングページ（index.html）＋ プレビュークリップ

💾 データ管理

すべてのユーザデータは

data/

含まれるファイル：

• app.db

  – セッション、メッセージ、ドキュメント

• memory.json

  /

  presets.json

• uploads/

  ,

  personal_docs/

• chroma/

  ,

  settings.json

  など

📜 ライセンス

MIT License
詳細は

LICENSE

ACKNOWLEDGMENTS.md