Skip to main content

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.

Odysseus Portable is designed to be running in minutes regardless of your operating system. There is no installer, no system-level dependency to satisfy, and no administrator prompt — just download or clone the repository, run the startup script, and the orchestrator handles the rest. The steps below cover all three supported platforms.

​
Launch Instructions

1

Download or clone the repository

Download the project as a ZIP from GitHub and extract it, or clone it with Git into any directory or USB drive:
git clone https://github.com/techjarves/Odysseus-Portable.git
cd Odysseus-Portable
2

Run the startup script

Double-click start.bat in Windows Explorer, or open a Command Prompt in the project folder and run:
start.bat
PowerShell is used internally for the Node.js bootstrap — no separate PowerShell window needs to be opened.
3

Wait for the first-run setup to complete

On first launch, the orchestrator downloads portable Node.js, a Python 3.12 embedded environment, and a CUDA/Vulkan/CPU-optimized llama-server.exe binary — all into the bin\ folder. Setup completes automatically without user interaction.
4

Open the UI and log in

The orchestrator opens http://127.0.0.1:7070 in your default browser automatically once the Odysseus web server is ready.Log in with the default credentials: admin / techjarves.

​
What Happens on First Launch

The orchestrator runs a multi-stage bootstrap sequence the very first time you start Odysseus Portable. Understanding each stage helps you diagnose slow starts or network errors.
1

Hardware scan

The orchestrator reads your OS, CPU architecture, total RAM, and GPU. It probes nvidia-smi for CUDA GPUs, checks for vulkan-1.dll / libvulkan.so.1 for Vulkan, and detects Apple Silicon automatically for Metal. The result determines which llama-server binary variant to download.
2

Runtime bootstrap

Portable Node.js 22.16.0 is downloaded from nodejs.org and extracted into bin/node-<os>-<arch>/ (macOS/Linux) or bin\node\ (Windows). A portable Python 3.12 environment is set up — via uv virtual environment on macOS/Linux, or via the official embedded zip on Windows. The hardware-matched llama-server binary is also downloaded and cached in bin/. This step runs once; all assets are reused on subsequent launches.
3

Odysseus sync

The orchestrator clones the Odysseus web application source from GitHub into the odysseus/ directory. If the directory already exists, it fast-forwards with git pull --ff-only when an internet connection is available. After cloning, a series of self-healing patches are applied to the Odysseus source to enable Windows path support, portable model-directory routing, and Ollama integration in the Cookbook UI.
4

Backend start

Python dependencies for Odysseus are installed (or verified) in the portable Python environment. The database is seeded with the default admin credentials, and the Cookbook state is configured to point at the project’s models/ folder. The selected inference backend — either llama-server or Ollama — is then started and the orchestrator waits for it to bind its port before proceeding.
5

Browser open

Once the Odysseus web server is confirmed live on port 7070, the orchestrator opens http://127.0.0.1:7070 in your default browser using start (Windows), open (macOS), or xdg-open (Linux).
On subsequent launches, the runtime bootstrap step is skipped entirely because Node.js, Python, and llama-server are already cached in bin/. Startup is significantly faster after the first run.

​
Choosing an Inference Backend

The orchestrator selects the llama.cpp backend by default when no saved preference, environment variable, or CLI flag is present. You can override this at any time using a CLI flag or environment variable. When the backend cannot be determined from a saved data/launcher_config.json config, an arg, or an environment variable, you will be prompted interactively: 
Choose inference backend:
  [1] Ollama   - webapp-managed downloads and model switching
  [2] llama.cpp - portable GGUF llama-server fallback

Enter selection [1-2] (default 1 - Ollama):
OptionBest For
[1] OllamaUsers who already have Ollama installed, or who prefer managing models through the Odysseus Cookbook web UI with one-click downloading and switching.
[2] llama.cppMaximum portability. The bundled llama-server binary runs entirely from the project folder with no external dependencies. GGUF models are stored in models/.

​
Pre-selecting a Backend

You can skip the interactive prompt by passing a flag or setting an environment variable before launch: 
./start.sh --backend=llama
./start.sh --backend=ollama
Your selection is persisted to data/launcher_config.json and used as the default on all future launches — no re-prompting unless you delete that file.
Change the default admin password after first login. The default credentials (admin / techjarves) are publicly documented. Open the user profile settings in the Odysseus web UI and set a strong password before using the workspace on any shared or networked machine.

Build docs developers (and LLMs) love

Get started for freeTalk to us