Odysseus - MixRoute API

Odysseus is a self-hosted AI workspace designed to provide a privatized Web experience similar to ChatGPT and Claude. It not only supports local models but also seamlessly integrates with cloud APIs (such as Mixroute), featuring powerful Agent routing, Deep Research, collaborative document editing, persistent memory (ChromaDB), and an evolving skill system.

Official GitHub: pewdiepie-archdaemon/odysseus

Core Features

Smart Agent Routing

Built-in autonomous Agents based on tool calling, web search, file read/write, and Shell execution, supporting MCP service extensions.

Deep Research

Multi-step, autonomous academic and factual search, synthesis, and extraction, ultimately outputting comprehensive, high-quality visual reports.

Self-Hosted AI Collaboration

Equipped with a rich-text Markdown editor where AI can collaboratively edit documents based on context, perfectly optimized for mobile devices.

Prerequisites

Before starting deployment, please ensure your system meets the following requirements:

Prepare Mixroute Credentials

Obtain your Mixroute API endpoint URL, typically: https://api.mixroute.ai/v1
Generate your API Key in the Mixroute console.
Determine the model name you want to use, e.g., claude-sonnet-4-6 (make sure this model is enabled in the Mixroute console).

Environment Dependency Check

Docker Deployment: Requires Docker and Docker Compose.
Native Linux Deployment: Requires Python 3.11 or higher, and ensure git is installed on your system.

Deploying Odysseus

You can choose between the recommended Docker containerized deployment or native Linux deployment based on your system configuration.

Docker Compose (Recommended)
Native Linux Deployment

Launch Odysseus and its companion services (ChromaDB, SearXNG, etc.) with a single command via Docker Compose. All data is persisted in the local data/ directory.

# Clone the repository and enter the workspace directory
git clone https://github.com/pewdiepie-archdaemon/odysseus.git
cd odysseus

# Create and configure the environment file (optional, to modify ports or bind addresses)
cp .env.example .env

# Start the services
docker compose up -d --build

If you want optional PDF rendering and Office document extraction support (requires AGPL PyMuPDF), perform a manual build with the build argument before running up:

docker compose build --build-arg INSTALL_OPTIONAL=true
docker compose up -d

If you prefer to deploy directly on your host machine (physical or virtual machine), please refer to the following guide:

# Clone and enter the directory
git clone https://github.com/pewdiepie-archdaemon/odysseus.git
cd odysseus

# Create and activate a Python virtual environment (Python 3.11+)
python3 -m venv venv
source venv/bin/activate

# Install dependencies
pip install -r requirements.txt

# Run the setup script
python setup.py

# Start the application (bound to 127.0.0.1, port 7000)
python -m uvicorn app:app --host 127.0.0.1 --port 7000

Native deployment requires ensuring that essential system dependencies (such as sqlite3) are installed. If you wish to use Odysseus’s Cookbook feature to download or manage background services, installing tmux is highly recommended.

By default, Odysseus automatically creates an admin account admin during the first startup and prints the generated random initial password to the startup logs.

Retrieve Initial Admin Password

Run the following command in your terminal to view the output:

Docker Deployment:

docker compose logs odysseus | grep -C3 'password'

Native Linux Deployment: Check the temporary initial password output in uvicorn or your startup terminal.

Access Web Console

Local access: http://127.0.0.1:7000
Remote cloud server access: http://<your-server-ip>:7000

By default, the container only listens to 127.0.0.1. If you need to configure a cloud virtual machine, please refer to the Nntwork errors or container listening issues below.

Configuring Mixroute

Once logged in successfully, follow these steps to configure Mixroute as a custom endpoint to power your Odysseus intelligent assistant.

Open Settings Panel

Click Settings in the bottom-left corner to access the global system settings.

Configure Provider

Add a new custom endpoint on the Providers/Endpoints page in Settings:

Base URL: https://api.mixroute.ai/v1
API Key: Enter your Mixroute API Key (e.g., sk-xxxxxxxx)

Enable & Manage Models

After adding the endpoint, Odysseus will automatically probe and load the available models returned by that endpoint. You can enable frequently used models in the list, or assign them to global default roles (such as default chat, Deep Research, Task scheduling, vision, etc.).

Testing shows that the GPT series performs exceptionally well in Odysseus; using it in conjunction with GPT models is highly recommended.

Enjoy your Odysseus

Return to the Chat home page to start conversations and launch powerful intelligent Agents utilizing Mixroute’s underlying models.

FAQ & Advanced Setup

How to enable NVIDIA GPU passthrough in Docker?

If you need to call or manage local GPUs through the Cookbook inside self-hosted containers, we recommend:

Running the built-in diagnostic and configuration script:

scripts/check-docker-gpu.sh --install-nvidia-toolkit --enable-nvidia-overlay

This script automatically appends COMPOSE_FILE=docker-compose.yml:docker/gpu.nvidia.yml to .env to enable NVIDIA Container Toolkit mapping.

Network errors or container listening issues

By default, the container only listens on 127.0.0.1.

If you need direct access via IP over LAN or the public network, please modify APP_BIND=0.0.0.0 in .env and restart the container.
For production environments, it is highly recommended to keep the listening address on 127.0.0.1 and use Nginx, Caddy, or Cloudflare Tunnel as a reverse proxy with an SSL certificate.

ChromaDB or memory retrieval errors

If you encounter issues where ChromaDB fails to load or experiences client incompatibilities:

# We recommend manually uninstalling potentially conflicting lightweight clients, then force-reinstalling the full package:
./venv/bin/pip uninstall chromadb-client -y
./venv/bin/pip install --force-reinstall chromadb

Once configured, all of Odysseus’s subsequent features (Deep Research, file retrieval, calendar/todos, and email triage) will be powered by the Mixroute endpoint bound and configured in your Settings, delivering a robust and highly cost-effective cloud-based LLM experience.

​Core Features

Smart Agent Routing

Deep Research

Self-Hosted AI Collaboration

​Prerequisites

​Deploying Odysseus

​First Login & Password Retrieval

​Configuring Mixroute

​FAQ & Advanced Setup

Core Features

Prerequisites

Deploying Odysseus

First Login & Password Retrieval

Configuring Mixroute

FAQ & Advanced Setup