How techjarves/odysseus-portable works
1. This repo is a portable launcher/orchestrator, not the AI app itself.
Its job is to prepare a self-contained local environment, then start the Odysseus web UI and a local model server on localhost.
2. The entry points are OS-specific shell wrappers.
start.bat and start.sh kick off the Node-based launcher. The scripts/ folder also contains bootstrap/reset helpers, including a PowerShell bootstrapper for Windows.
3. src/start.js is the main control plane.
It is the top-level orchestrator that sequences startup: environment checks, runtime provisioning, model selection, backend launch, and browser opening.
4. src/system.js is the hardware and platform detection boundary.
It scans the host OS and machine capabilities so the launcher can choose the correct portable binaries and size/shape the inference runtime for the device.
5. src/downloader.js handles portable dependency acquisition.
The launcher downloads and extracts bundled runtimes on demand rather than relying on system-installed Node, Python, or model-server binaries.
6. src/model.js manages local GGUF model discovery and retrieval.
This is the model boundary: it scans the models/ area, supports local selection, and downloads model artifacts when needed.
7. src/runtime.js manages child processes and lifecycle.
It appears to be the process supervisor for the launched services, including startup, shutdown, logging, and restart behavior when a backend fails.
8. src/backends/ contains inference adapters.
There are separate backend implementations for llama and ollama, with common.js shared across them. This suggests the launcher can target more than one local model-serving stack.
9. src/backends/common.js is the initialization/seed layer.
The README indicates it sets up database credentials and performs self-healing setup work, so this is likely where Odysseus-specific bootstrapping and SQLite-related setup happen.
10. src/backends/llama/ is the main llama.cpp integration path.
The README centers on a local llama-server backend serving GGUF models, with the launcher selecting context size and parallelism based on hardware.
11. src/backends/ollama/ provides an alternate local model backend.
Even though the README focuses on llama.cpp, the tree shows explicit Ollama support, so the architecture includes a second inference adapter rather than a single hard-coded engine.
12. The external Odysseus web application is a separate repository/runtime boundary.
The launcher clones or updates the ./odysseus repo and then runs it locally. That web app is the user-facing interface, while this repo provides the environment and model services beneath it.
13. The main runtime flow is local and offline-first.
Startup checks hardware, provisions portable runtimes, updates or seeds the app, starts the model backend, starts the web UI, and opens http://127.0.0.1:7070. The model API is exposed only on localhost, with an additional proxy/backend port in the 8080/10086 range per the README.
14. All persistent state stays inside the project directory.
The architecture intentionally keeps binaries under bin/, models under models/, the cloned app under odysseus/, and logs under logs/, so the entire workspace is portable and leaves minimal host-system footprint.
Main entry points: start.js start.js · common.js common.js · downloader.js downloader.js · model.js model.js
Components 19
Launchers
OS-specific entry points and maintenance helpers.
- start.bat · Windows wrapper that starts the launcher.
start.bat - start.sh · Unix shell wrapper that starts the launcher.
start.sh - bootstrap-node.ps1 · PowerShell bootstrapper for Windows runtime setup.
scripts/bootstrap-node.ps1 - reset helpers · Reset and recovery scripts for the portable workspace.
Core Orchestration
Node-based startup control plane and provisioning logic.
- start.js · Main startup sequence and service coordination.
src/start.js - system.js · Detects host OS and hardware capabilities for runtime sizing and selection.
src/system.js - downloader.js · Downloads and extracts portable runtimes and other dependencies.
src/downloader.js - model.js · Finds, selects, and retrieves local GGUF model artifacts.
src/model.js - runtime.js · Starts, stops, logs, and restarts child processes.
src/runtime.js - git bootstrap · Initializes or updates the external Odysseus application repository.
src/bootstrap/git.js
Backends
Local model-serving adapters and shared backend setup.
- common.js · Shared backend initialization and self-healing setup logic.
src/backends/common.js - llama backend · Main llama.cpp integration for serving GGUF models locally.
src/backends/llama/index.js - ollama backend · Alternate local model-serving adapter based on Ollama.
src/backends/ollama/index.js
Workspace State
Portable runtime, model, and external app boundaries managed by the launcher.
- odysseus repo · Separate user-facing Odysseus application cloned and run locally.
- bin/ · Downloaded local binaries and runtime payloads kept inside the project.
- models/ · Stored GGUF model files and downloads managed by the launcher.
- logs/ · Process and launch logs produced by the local environment.
- localhost UI · Browser-opened Odysseus interface on the local machine.
- local backend · Private localhost inference service exposed by the selected backend.
Connections 21
- start.bat → start.js: launches · Windows entry wrapper starts the Node launcher.
- start.sh → start.js: launches · Shell entry wrapper starts the Node launcher.
- bootstrap-node.ps1 → start.js: bootstraps · Windows bootstrapper prepares Node and environment for startup.
- reset helpers → odysseus repo: resets · Maintenance scripts can clear or restore the workspace.
- start.js → system.js: probes · Launcher checks hardware and platform capabilities first.
- start.js → downloader.js: provisions · Launcher fetches portable dependencies when needed.
- start.js → model.js: selects · Launcher resolves which local model to use.
- start.js → runtime.js: supervises · Launcher coordinates service process lifecycle.
- start.js → git bootstrap: seeds · Launcher prepares or updates the external app repository.
- start.js → common.js: initializes · Launcher applies shared backend setup before starting services.
- downloader.js → bin/: writes · Portable runtime binaries are stored inside the workspace.
- model.js → models/: reads/writes · Model discovery and downloads operate within the local models area.
- git bootstrap → odysseus repo: clones/updates · External Odysseus app is maintained as a separate local repo.
- common.js → llama backend: configures · Shared setup feeds the main llama backend.
- common.js → ollama backend: configures · Shared setup feeds the Ollama backend.
- llama backend → local backend: serves · Llama backend exposes the local inference API.
- ollama backend → local backend: serves · Ollama backend can expose the local inference API.
- runtime.js → logs/: emits · Process supervision writes runtime logs.
- start.js → localhost UI: opens · Launcher opens the local Odysseus web interface in the browser.
- localhost UI → odysseus repo: renders · The browser UI is provided by the external Odysseus application.
- odysseus repo → local backend: calls · The web app talks to the local model backend on localhost.