Learn how to set up Odysseus AI locally on any PC with this step-by-step guide. From installation to running your first AI model, ensure a secure, private, and fully operational AI workspace.
Master Generative AI and Artificial Intelligence fundamentals with hands-on lessons for beginners. Learn to build, run, and apply AI confidently in real projects.
If you've ever wanted a local AI workspace without cloud limitations - where your conversations, files, and personal data stay entirely on your own machine - then Odysseus AI is exactly what you've been waiting for.
Odysseus is a self-hosted, open-source AI workspace that lets you run powerful AI tools directly on your PC, without paying for a subscription or handing your data to a third-party cloud. Think of it as your personal version of ChatGPT or Claude, but running on your own hardware, under your own control.
Built and launched by developer pewdiepie-archdaemon on GitHub, Odysseus packages an impressive range of capabilities into a single unified workspace: chat with any local or API-connected model, autonomous AI agents, deep research tools, email and calendar management, file uploads, web browsing, and a built-in model Cookbook that scans your hardware and recommends AI models you can actually run. It supports popular local inference backends like Ollama, llama.cpp, and vLLM, as well as remote APIs like OpenAI and OpenRouter - meaning it works whether you're running open-source models locally or routing to cloud APIs.
The project is completely free and open source - no sales team, no demo request, no hidden costs.
Before you begin your Odysseus AI installation, make sure your PC meets the following requirements. Running a self-hosted AI workspace doesn't require a supercomputer, but having adequate hardware will significantly improve your experience - especially if you plan to run large local language models.
|
Component |
Minimum (Core App / API Use) |
Recommended (Smooth Local AI) |
Optimal (Heavy Local Models) |
|
CPU |
4-core modern CPU |
6–8 core CPU |
8+ core high-performance CPU |
|
RAM |
16 GB |
32 GB |
64 GB+ |
|
Storage |
20 GB SSD free |
50–100 GB SSD/NVMe |
100–250 GB NVMe |
|
Python |
Python 3.11+ |
Python 3.11 or 3.12 |
Python 3.12 preferred |
|
OS |
Windows, macOS, or Linux |
Linux/macOS preferred; Windows with Ollama |
Linux preferred for vLLM/SGLang |
|
GPU |
Optional / integrated OK |
8–12 GB VRAM |
16–24 GB+ VRAM |
🔗 External resource: Not sure which Python version you have? Read the official Python documentation for version checking instructions on each OS.
A smooth Odysseus AI setup starts with proper preparation. Follow this checklist before cloning the repository or running any installation commands.
1. Verify Python Version
Open your terminal (Command Prompt / PowerShell on Windows, Terminal on macOS/Linux) and run:
python --version
# or
python3 --version
You need Python 3.10 or newer. If your version is outdated, download the latest from python.org.
2. Install Git
Odysseus is hosted on GitHub, so you'll need Git to clone the repository. Check if it's installed:
git --version
If not installed:
3. (Optional) Install Docker for Containerised Setup
If you prefer a Docker-based Odysseus install — which is cleaner and avoids dependency conflicts — install Docker Desktop first:
After installation, verify Docker is running:
docker --version
docker compose version
💡 What is Docker? Docker packages software into isolated "containers" so it runs the same way on any machine. If you're new to containers or want a deeper understanding of modern AI tooling, our Generative AI & Artificial Intelligence for Beginners course covers these foundational concepts in plain language.
4. Check Network Permissions
Odysseus needs internet access during setup to:
Make sure your firewall or corporate network allows outbound HTTPS connections. If you're behind a proxy, configure it in your terminal:
# Example: set HTTP proxy (replace with your proxy address)
export HTTP_PROXY=http://your-proxy:port
export HTTPS_PROXY=http://your-proxy:port
5. Create a Dedicated Project Folder
Keep things organised from the start:
# Create and navigate to your projects folder
mkdir ~/ai-projects
cd ~/ai-projects
Now that your environment is ready, it's time to obtain the Odysseus source code. The official repository is hosted publicly on GitHub at:
🔗 pewdiepie_archdaemon_odysseus
This is the standard method for all platforms. Open your terminal, navigate to your project folder, and run:
git clone https://github.com/pewdiepie-archdaemon/odysseus.git
cd odysseus
This downloads the latest version of Odysseus, including all source files, configuration templates, and setup scripts.
⚠️ Important: Always clone from the official repository (pewdiepie-archdaemon/odysseus). Community forks exist, but the official repo is the authoritative, most up-to-date source.
If you'd prefer not to use Git:
cd ~/ai-projects/odysseus-main
Once you've cloned or extracted the repo, confirm the files are present:
ls
# You should see: app.py requirements.txt setup.py data/ ...
On Windows (PowerShell):
dir
# You should see: app.py requirements.txt setup.py data/ ...
The key files to look for are:
|
File / Folder |
Purpose |
|
app.py |
Main application entry point |
|
requirements.txt |
Python dependencies list |
|
setup.py |
Initial setup script (generates admin password, creates data dirs) |
|
data/ |
Directory for local storage (conversations, config, uploads) |
|
.env.example |
Environment variable template |
Odysseus is at version 1.0 at launch. To check for newer releases or tagged versions:
# After cloning, check available tags/releases
git tag -l
# To pull latest updates at any time
git pull origin main
For production or stable deployments, check the Releases tab on GitHub and checkout a specific release tag:
git checkout tags/v1.0 # example: pin to a specific release
🔗 External resource: New to Git and GitHub? The GitHub official quickstart guide is an excellent free reference for beginners.
With the repository cloned and your environment ready, it's time for the actual Odysseus AI installation. The process is built around Python's virtual environment system - a clean, isolated container for all of Odysseus's dependencies so they don't conflict with other software on your machine.
Open PowerShell (search for it in the Start menu) and navigate to your Odysseus folder:
cd ~/ai-projects/odysseus
Step 1 - Create a virtual environment:
python -m venv venv
Step 2 - Activate the virtual environment:
venv\Scripts\Activate.ps1
⚠️ Common Windows Error: If you see a "running scripts is disabled" message, run this first:
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
Then retry the activation command.
Step 3 - Install dependencies:
pip install -r requirements.txt
Step 4 - Run the setup script (creates data directories and generates your admin password):
python setup.py
📝 Note the admin password printed in the terminal - you'll need it to log in. You can also pre-set it by adding ODYSSEUS_ADMIN_PASSWORD=yourpassword to a .env file before running setup.
Step 5 - Launch Odysseus:
python -m uvicorn app:app --host 127.0.0.1 --port 7000
Open Terminal and navigate to your Odysseus folder:
cd ~/ai-projects/odysseus
Step 1 - Create a virtual environment:
python3 -m venv venv
Step 2 - Activate the virtual environment:
source venv/bin/activate
Step 3 - Install dependencies:
pip install -r requirements.txt
Step 4 - Run setup:
python setup.py
Step 5 - Launch Odysseus:
python -m uvicorn app:app --host 127.0.0.1 --port 7000
💡 macOS note: Docker on macOS cannot use the Metal GPU for acceleration. If you want native Apple Silicon GPU performance, use the manual Python install method above — not Docker.
🔗 External resource: If you don't have Python 3.11+ on macOS, the easiest way to install it is via Homebrew: brew install [email protected]
Open your terminal and navigate to the Odysseus folder:
cd ~/ai-projects/odysseus
Step 1 - Install system dependencies (if not already present):
sudo apt update && sudo apt install -y python3-venv python3-pip tmux
📝 tmux is required on Linux for the Cookbook feature to run background model downloads. Install it now to avoid issues later.
Step 2 - Create and activate a virtual environment:
python3 -m venv venv
source venv/bin/activate
Step 3 - Install Python dependencies:
pip install -r requirements.txt
Step 4 - Run setup:
python setup.py
Step 5 - Launch Odysseus:
python -m uvicorn app:app --host 127.0.0.1 --port 7000
For Red Hat / Fedora / CentOS, replace apt with dnf:
sudo dnf install python3-venv python3-pip tmux
|
Step |
Windows |
macOS |
Linux |
|
Create venv |
python -m venv venv |
python3 -m venv venv |
python3 -m venv venv |
|
Activate venv |
venv\Scripts\Activate.ps1 |
source venv/bin/activate |
source venv/bin/activate |
|
Install deps |
pip install -r requirements.txt |
same |
same |
|
Run setup |
python setup.py |
same |
same |
|
Launch |
python -m uvicorn app:app --host 127.0.0.1 --port 7000 |
same |
Same |
Once you run the launch command, Odysseus starts a local web server. Here's how to access and configure your new local AI workspace.
Open your browser and go to:
http://localhost:7000
You'll see the Odysseus login screen. Use the admin password generated by setup.py to log in. The password was printed in your terminal during setup - look for a line beginning with a generated password notice. Change it immediately after first login via Settings → Account.
After logging in, navigate to Settings (gear icon) to configure your workspace:
1. Connect an AI Model
Odysseus supports multiple AI backends. Under Settings → Models, add your preferred provider:
2. Use the Cookbook to Download Local Models
The built-in Cookbook feature scans your hardware and recommends AI models your system can actually run. Navigate to Cookbook, let it scan, then click any model to download and serve it automatically - no command-line model management needed.
3. Start Chatting
Once a model is connected or downloaded, click Chat in the left sidebar and start your first conversation. You can also activate Agents to give the AI autonomous task-running capabilities.
🔗 External resource: For a deeper understanding of how different AI models compare and what "parameters" mean, see Hugging Face's model documentation.
Unlock the world of AI effortlessly! 🚀 The Generative AI & Artificial Intelligence for Beginners course from the German Compliance Institute teaches you the essentials of AI, from language models to practical applications-perfect for tech enthusiasts ready to start building with confidence.
For users who want a cleaner, more portable Odysseus Docker install, Docker Compose is the recommended approach. It bundles Odysseus and all its dependencies into isolated containers, eliminating the risk of version conflicts and making updates straightforward.
Step 1 — Navigate to the Odysseus folder and copy the environment template:
cd ~/ai-projects/odysseus
cp .env.example .env
Open .env in any text editor to review or customize settings (port, admin password, LLM host) before starting.
Step 2 — Build and start the containers:
docker compose up -d --build
This command does everything: pulls required base images, builds the Odysseus container, and starts it in detached mode (running in the background). The first build may take a few minutes.
Step 3 — Open Odysseus in your browser:
http://localhost:7000
Docker Compose binds the web UI to 127.0.0.1 by default — accessible only from your own machine. This is the secure default.
|
Command |
Purpose |
|
docker compose up -d --build |
Build and start in background |
|
docker compose down |
Stop and remove containers |
|
docker compose logs --tail=120 odysseus |
View recent logs for debugging |
|
docker compose restart odysseus |
Restart the Odysseus container |
|
docker compose build --no-cache odysseus |
Rebuild from scratch (fixes stale cache issues) |
🔗 External resource: For production HTTPS deployment, the Caddy web server documentation provides an excellent reverse proxy quickstart guide.
After launching Odysseus - whether via Python or Docker - run through these quick checks to confirm everything is working correctly.
✅ Test 1: Web UI loads
Open http://localhost:7000 in your browser. You should see the Odysseus login page. If it doesn't load, confirm the server is still running in your terminal.
✅ Test 2: Login succeeds
Log in with the admin credentials generated during setup. A successful login takes you to the main Odysseus dashboard with the sidebar navigation visible.
✅ Test 3: Model connection works
Navigate to Settings → Models and confirm at least one model provider is connected (green status indicator). If you installed Ollama locally, you should see it listed automatically.
✅ Test 4: Cookbook model catalog loads
Go to Cookbook. It should display a list of recommended models for your hardware (non-zero count). If the catalog shows 0 models and you're using Docker, rebuild the image:
docker compose build --no-cache odysseus
docker compose up -d
✅ Test 5: Send a test chat message
Click Chat, select a connected model, and send a simple test message:
Hello! Can you confirm you're running and tell me which model you are?
A successful response confirms the full pipeline — UI → backend → model — is working correctly.
✅ Test 6: Agent basic check (optional)
Navigate to Agents, create a new agent, and give it a simple task like "Search the web for today's date." If the agent completes the task and returns a result, your tools and agent loop are functioning.
🎉 If all six checks pass, your Odysseus AI setup is complete and fully operational!
Even with careful preparation, installations can hit snags. Below are the most common problems encountered during Odysseus AI installation and their solutions.
🔴 Problem: PowerShell says "running scripts is disabled" (Windows) → Solution: Run Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser in PowerShell, then retry activating the virtual environment.
🔴 Problem: pip install -r requirements.txt fails with dependency errors → Solution: Ensure you're running Python 3.11 or higher (python --version). If not, download the latest Python from python.org and create a fresh virtual environment. Also try upgrading pip first: pip install --upgrade pip
🔴 Problem: python setup.py fails with "Admin creation did not happen: dependencies are missing" → Solution: The bcrypt package is missing. Run:
pip install bcrypt
Then re-run python setup.py.
🔴 Problem: python setup.py fails with "Check write permissions for the 'data' directory" → Solution: Odysseus can't write to its data folder. Fix permissions:
🔴 Problem: Browser shows "This site can't be reached" at localhost:7000 → Solution: The server is not running. Go back to your terminal and confirm the uvicorn command is still active. If you closed the terminal, restart the server. For Docker users, run docker compose ps to check container status.
🔴 Problem: Cookbook shows 0 models (Docker) → Solution: Rebuild the Odysseus image without cache:
docker compose build --no-cache odysseus
docker compose up -d
🔴 Problem: Port 7000 is already in use → Solution: Either stop the conflicting process, or change Odysseus's port. Add APP_PORT=7001 to your .env file and relaunch. For manual runs, change the port in the uvicorn command:
python -m uvicorn app:app --host 127.0.0.1 --port 7001
🔴 Problem: Ollama models not detected in Settings → Solution: Confirm Ollama is running (ollama serve in a separate terminal) and at least one model is pulled (ollama pull llama3). Then in Odysseus Settings → Models, set the Ollama host to http://localhost:11434. External resource: Ollama model library.
🔴 Problem: Linux — Cookbook model downloads freeze or never complete → Solution: tmux is required for background model serving on Linux. Install it:
sudo apt install tmux # Ubuntu/Debian
sudo dnf install tmux # Fedora/RHEL
Then restart Odysseus.
🔴 Problem: macOS — Docker container starts but GPU acceleration doesn't work → Solution: This is expected behaviour. Docker on macOS cannot access the Metal GPU. Switch to the manual Python installation method to get native Apple Silicon GPU acceleration via Metal/MLX.
🔗 Still stuck? Check the Odysseus GitHub Issues page - the community is active and many edge-case solutions are already documented there.
Congratulations - you've successfully installed and launched Odysseus AI on your PC! Let's recap what you've accomplished:
You now have a fully operational, private, local AI workspace - one that gives you the power of tools like ChatGPT and Claude, running entirely on your own hardware, with zero subscription fees and complete data sovereignty.
Now that Odysseus is running, here are the best ways to go deeper:
Installing Odysseus is just the beginning. To truly unlock the power of local AI - understanding how to write effective prompts, what different model architectures do, how generative AI actually works under the hood, and how to apply AI responsibly in real-world projects - you need a solid foundation.
The Generative AI & Artificial Intelligence for Beginners course from the German Compliance Institute is built exactly for this. Whether you're a developer, a tech enthusiast, or a professional looking to get ahead of the AI curve, this course takes you from zero to confident - with practical, beginner-friendly lessons that make AI genuinely understandable.
|
Resource |
Link |
|
Odysseus GitHub Repository |
|
|
Odysseus Official Page |
|
|
Ollama Model Library |
|
|
OpenRouter (API models) |
|
|
Docker Desktop |
|
|
Python Downloads |
|
|
Beginners AI Course |
Found this guide helpful? Share it with fellow AI enthusiasts, and check back for updates as Odysseus continues to evolve.
