Odysseus AIをLinuxにインストールする方法：ネイティブ版とDocker版の完全ガイド

インストール前にネイティブ版かDocker版かを決める

公式の複数サービス構成を再現しやすく、ホストOSとの境界を保ちたい場合はDockerが基本です。PythonやUvicornのプロセスを直接確認したい場合、リポジトリ開発を行う場合、コンテナーを介さずホストのツールを使いたい場合はネイティブ版が適しています。

ローカルモデルを使うだけならネイティブ版に限定されません。どちらの方式でもOllama、vLLM、SGLang、OpenAI互換エンドポイントへ接続できます。またDockerを選んでもGPUが自動で有効になるわけではなく、ホストドライバー、コンテナーランタイム、Composeオーバーレイの確認が必要です。

Linux導入前の確認項目

クローン前にブランチ、Python、ポート、空き容量、モデルの実行場所を確認します。公式リポジトリではdevが最新変更を受け取る既定ブランチで、mainはより選別されたブランチと説明されています。2026年7月30日の確認時点でGitHub Releases、バージョンタグ、公式バイナリはありません。そのため本ページでは架空の最新バージョンやインストーラーを案内しません。

ネイティブ版はPython 3.11以上が必要です。Docker版はDocker EngineとComposeプラグインを確認します。APP_PORTを変更しない場合は7000番ポートを空けます。ネイティブLinuxでCookbookのモデルダウンロードやバックグラウンド実行を使う場合、公式文書ではtmuxも要件として示されています。

1. devかmainを選ぶ

   最新変更を優先するならdev、より選別された状態を優先するならmainを選びます。

2. モデルの実行場所を決める

   同じホスト、別サーバー、ホスト型APIのいずれかを先に決めます。

3. ポートを確認する

   7000番が空いているか確認し、必要ならAPP_PORTを変更します。

4. 初回起動を非公開にする

   生成されたパスワードを変更するまでは127.0.0.1だけで起動します。

python3 --version
docker --version
docker compose version
ss -ltn | grep ':7000' || true

Odysseus AIをLinuxへネイティブインストールする

ネイティブ手順では隔離された仮想環境を作り、依存関係を導入し、セットアップを実行してUvicornでASGIアプリを起動します。管理下のディレクトリで一般ユーザーとして実行してください。sudo pipはシステムPythonとプロジェクト依存関係を混在させ、更新や削除を難しくするため避けます。

最初の起動コマンドはループバックだけにバインドします。これは正しい初期設定です。対話起動、ログイン、モデル接続が成功してからsystemdなどへ移行し、同じ作業ディレクトリ、仮想環境、環境変数を使用してください。

git clone https://github.com/odysseus-dev/odysseus.git
cd odysseus
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
python setup.py

python -m uvicorn app:app --host 127.0.0.1 --port 7000

Docker ComposeでOdysseus AIをインストールする

公式クイックスタートではDockerが推奨されています。.env.exampleのコピーは任意ですが、展開設定を明示できるため便利です。コンテナーをビルドして起動し、正常性を確認してからOdysseusのログで一時管理者パスワードを読みます。

Composeは既定でWeb UIを127.0.0.1へバインドします。7000番が使用中なら.envでAPP_PORT=7001など空きポートを設定し、コンテナーを再作成します。APP_BIND=0.0.0.0はポート競合の解決策ではありません。

git clone https://github.com/odysseus-dev/odysseus.git
cd odysseus
cp .env.example .env
docker compose up -d --build

docker compose ps
docker compose logs odysseus --tail=120

モデルを追加する前に初回ログインを確認する

Linuxホストでhttp://localhost:7000を開きます。初回セットアップでは管理者アカウントが作成され、一時パスワードが端末またはコンテナーログへ表示されます。ログイン後に設定画面で変更し、新しいブラウザーセッションでもログインできることを確認してからリモートアクセスへ進みます。

次に既知のモデルエンドポイントを1つだけ追加し、短いメッセージを送ります。画面は開くのに応答だけ失敗する場合、Linux導入自体は正常な可能性が高いため、URL、認証情報、モデル名、ファイアウォール、モデル実行環境を確認します。

1. ローカルページを開く

   localhost:7000でログイン画面が表示されるか確認します。

2. 生成パスワードを読む

   端末またはログを確認し、既定パスワードを推測しません。

3. 認証情報を変更する

   LAN、VPN、プロキシを使う前に変更します。

4. モデルを1つ試す

   既知のエンドポイントと短いプロンプトで確認します。

GPUは主にモデル実行環境の問題として扱う

Odysseusワークスペース自体は比較的軽量で、GPU需要の大部分はローカル推論から生じます。ネイティブ版はホストのOllamaへ直接接続でき、Docker版もDockerソケットをマウントせずホストや別サーバーのエンドポイントを利用できます。

NVIDIAやAMDをコンテナーで使う場合、最初にホストドライバーとパススルーを確認します。公式の診断スクリプトとオーバーレイが利用できます。コンテナー内でnvidia-smiが成功しても、llama.cpp、vLLM、SGLangに必要なCUDAやROCmライブラリまで正しいとは限りません。

scripts/check-docker-gpu.sh

http://host.docker.internal:11434/v1

LinuxのOdysseusをTailscaleへ安全に接続する

Similarwebのphrase matchではconnect odysseus to tailscale linuxが低難易度の補助クエリとして確認されました。リモートアクセスはローカル導入後の作業なので、本Linuxガイド内で扱うのが適切で、薄い別ページを作る根拠にはなりません。

アプリを0.0.0.0または適切なインターフェースへ意図的にバインドし、認証を維持し、Tailscaleポリシーやホストのファイアウォールで端末を制限します。ブラウザー機能が安全なオリジンを必要とする場合はHTTPSを使用し、アプリやモデルの生ポートをインターネットへ直接転送しないでください。

python -m uvicorn app:app --host 0.0.0.0 --port 7000

APP_BIND=0.0.0.0
AUTH_ENABLED=true

存在しないリリース番号を使わず安全に更新する

2026年7月30日時点で公式Releaseやバージョンタグはありません。devは頻繁に変わり、mainはより選別されています。そのため本ガイドでは最新バージョン番号、ファイルサイズ、バイナリインストーラー、恒久的な直接ダウンロードURLを主張しません。

更新前に現在のブランチを記録し、データと.envをバックアップし、変更内容を確認して同じブランチを更新します。無関係な保守作業中にmainからdevへ切り替えないでください。再ビルド後はログイン、モデル、ネットワークを再確認します。

git status --short
git branch --show-current
git pull --ff-only
# Docker
docker compose up -d --build

Linuxインストールのトラブルシューティング

プロセス、ポート、ログイン、モデルエンドポイント、追加サービスの順に確認します。複数の層を同時に変更すると原因が分からなくなります。