Odysseus Portable is a unified, 100% self-contained, offline-first AI agent workspace that requires zero system-level installation. It bundles the Odysseus web UI — a feature-rich, Claude/ChatGPT-like local interface created by pewdiepie-archdaemon, with SQLite-backed memory, calendar integration, custom agents, and deep research capabilities — alongside a dynamic, hardware-optimized llama.cpp inference engine. The entire stack lives in a single folder you can copy to a USB drive, external SSD, or any directory and run immediately on Windows, macOS, or Linux without administrator rights.Documentation Index
Fetch the complete documentation index at: https://mintlify.com/techjarves/Odysseus-Portable/llms.txt
Use this file to discover all available pages before exploring further.
What’s Included
Odysseus Web UI
A premium local chat interface with SQLite memory, calendar, custom agents, deep research, and model management via the Cookbook panel — all accessible at
http://127.0.0.1:7070.llama.cpp Inference
A hardware-optimized
llama-server binary downloaded and cached on first run. Automatically selects CUDA, Vulkan, Metal, or CPU-only execution based on your hardware.Dual Backends
Switch between the built-in llama.cpp GGUF router for maximum portability or Ollama for webapp-managed downloads and model switching — selectable at launch or via environment variable.
Cross-Platform
Native support for Windows (x64, ARM64), macOS Intel and Apple Silicon, and Linux (x64, ARM64). Each OS gets its own isolated runtime directory so one USB drive works on all three.
The Portability Guarantee
Odysseus Portable keeps your user data, SQLite databases, configuration files, cached model weights, session logs, and secrets out of system directories and registries. When you unplug the USB drive or delete the folder, no configuration or data traces are left on the host machine. The launcher’s portable Node.js 22 runtime and llama-server binary are downloaded into the project’sbin/ subdirectory on first run.
On macOS and Linux, the Python 3.12 virtual environment is created by
uv at ~/.cache/odysseus-portable/envs/ in your home directory — outside the project folder. This is a platform constraint of Python virtual environments. All other data (models, databases, configuration, logs) remains inside the project folder. On Windows, the embedded Python environment is stored entirely within the project’s odysseus/bin/ directory.How It Works
When you runstart.bat (Windows) or ./start.sh (macOS/Linux), the orchestrator at src/start.js takes over:
- Hardware Scan — Detects your OS, CPU architecture, total RAM, and GPU. Automatically selects the best inference acceleration: CUDA for NVIDIA GPUs, Metal for Apple Silicon, Vulkan for AMD/Intel/other discrete GPUs, or CPU as the universal fallback.
- Runtime Bootstrap — Downloads portable Node.js 22, a platform-specific Python 3.12 environment (via
uvon macOS/Linux, embedded zip on Windows), and a hardware-matchedllama-serverbinary — all intobin/. This happens once; subsequent launches reuse the cached runtimes. - Odysseus Sync — Clones the Odysseus web application from GitHub into the
odysseus/directory (or fast-forwards it if already present). A suite of self-healing patches is then applied to ensure smooth operation in the portable environment: Windows path support, Cookbook model-directory routing, Ollama dropdown injection, and more. - Backend Start — Launches the selected inference backend (llama.cpp router or Ollama) and the Odysseus web server on
127.0.0.1. - Browser Launch — Opens
http://127.0.0.1:7070in your default browser automatically.
Odysseus UI Features
The Odysseus web interface provides a full-featured local AI workspace:Chat & Memory
Chat & Memory
Persistent, SQLite-backed conversation memory across sessions. Every chat is stored locally inside the project folder — no cloud sync, no telemetry.
Calendar & Agents
Calendar & Agents
Built-in calendar integration and a custom agents panel. Create specialized agents with tailored system prompts, tools, and memory scopes.
Deep Research
Deep Research
A multi-step research mode that chains model calls to plan, search, synthesize, and summarize information — all running locally.
Cookbook & Model Management
Cookbook & Model Management
The Cookbook panel lets you download GGUF models directly from Hugging Face, manage local model files, and configure inference servers — all from the browser UI.
Default Ports
| Service | Address | Default Port |
|---|---|---|
| Odysseus Web UI | http://127.0.0.1 | 7070 |
| API Proxy | http://127.0.0.1 | 8080 |
| llama-server | http://127.0.0.1 | 10086 |
If any default port is already in use, the orchestrator automatically finds the next free port and uses that instead. All three services always bind to
127.0.0.1 (localhost only) by default.Default Credentials
The Odysseus web interface is protected by username/password authentication. The defaults seeded on first run are:| Field | Value |
|---|---|
| Username | admin |
| Password | techjarves |
Navigation
Quickstart
Get Odysseus Portable running on Windows, macOS, or Linux in four steps.
Requirements
Storage, RAM, OS, and network requirements before you start.
Backends
Compare llama.cpp and Ollama backends, and learn how to switch between them.
Configuration
Environment variables and
launcher_config.json settings reference.