From ead7c01822d4cc4381260d2c80a64e0736e7d47c Mon Sep 17 00:00:00 2001 From: pewdiepie-archdaemon Date: Mon, 1 Jun 2026 15:07:41 +0900 Subject: [PATCH] Trim README quick start --- README.md | 264 ++++++++++++++++-------------------------------------- 1 file changed, 79 insertions(+), 185 deletions(-) diff --git a/README.md b/README.md index 9c5b5f4..3e0162c 100644 --- a/README.md +++ b/README.md @@ -22,7 +22,10 @@ A self-hosted AI workspace -- meant to be the self-hosted version of the UI expe - **Extras** -- more to explore, happy if you give it a go!
　image editor · theme editor · file uploads (vision + PDF) · web search · presets · sessions · 2FA ## Demo -A full, hover-to-play tour lives on the landing page (`docs/index.html`). A few looks: +A full, hover-to-play tour lives on the landing page (`docs/index.html`). + +
+Screenshots / clips ### Chat & Agents ![Chat & Agents](docs/chat.gif) @@ -35,194 +38,119 @@ A full, hover-to-play tour lives on the landing page (`docs/index.html`). A few ### Notes & Tasks ![Notes & Tasks](docs/notes.gif) +
+ ## Quick Start -Defaults work out of the box — clone, run, configure inside the app. -Open the **Settings** panel after first login to point Odysseus at your LLM -server, search provider, email account, etc. Only touch `.env` if you need -to override deployment-level things like `AUTH_ENABLED`, `DATABASE_URL`, -or pre-seed `ODYSSEUS_ADMIN_PASSWORD` (otherwise an initial password is -generated and printed on first boot). +Defaults work out of the box: clone, run, then configure models/search/email +inside **Settings**. Only edit `.env` for deployment-level overrides like +`APP_PORT`, `AUTH_ENABLED`, `DATABASE_URL`, or a pre-seeded admin password. Contributing? See [CONTRIBUTING.md](CONTRIBUTING.md) for setup, testing, and pull request guidelines. -### Option 1: Docker (recommended) +### Docker (recommended) ```bash git clone https://github.com/pewdiepie-archdaemon/odysseus.git cd odysseus cp .env.example .env # optional, but recommended for explicit defaults docker compose up -d --build ``` -Compose starts Odysseus, ChromaDB, SearXNG, and ntfy. First run does a full -image build. Open `http://localhost:7000` after the containers are healthy. -If port `7000` is already taken, set `APP_PORT=7001` (or another free port) -in `.env`, recreate the container, and open `http://localhost:7001`. +Open `http://localhost:7000` when the containers are healthy. If the port is +taken, set `APP_PORT=7001` in `.env` and recreate the container. -> **On Apple Silicon, Docker can't use the Metal GPU** (it runs a Linux VM), so -> Cookbook will serve models on the CPU only. For GPU-accelerated Cookbook, -> run the app natively — see [Apple Silicon](#apple-silicon-m-series). - -Cookbook remote servers use an Odysseus-owned SSH key from `./data/ssh` -inside Docker. In **Cookbook -> Settings -> Servers**, generate/copy the -public key and add it to the remote server's `~/.ssh/authorized_keys`. -After generating the key, you can also install it from the host with: -```bash -ssh-copy-id -i data/ssh/id_ed25519.pub user@server -``` -Cookbook local downloads are stored in `./data/huggingface`, mounted as -`~/.cache/huggingface` inside the Odysseus container. Cookbook-installed -serve engines and Python CLIs are stored in `./data/local`, mounted as -`~/.local`, so vLLM/llama.cpp installs survive container recreation. - -After downloading a model, open **Cookbook -> Serve**, pick the cached model, -and launch it. When the server answers `/v1/models`, Odysseus adds it to the -chat model picker automatically. For NVIDIA / AMD GPUs in Docker, install -the host runtime (NVIDIA Container Toolkit or ROCm drivers) and enable the -matching overlay via `COMPOSE_FILE` in `.env`: - -```bash -# NVIDIA -COMPOSE_FILE=docker-compose.yml:docker/gpu.nvidia.yml -# AMD ROCm -COMPOSE_FILE=docker-compose.yml:docker/gpu.amd.yml -``` - -Verify with `docker compose exec odysseus nvidia-smi -L` (or `rocm-smi`). - -The default Docker image is intentionally slim. For Python-based serve engines, -use **Cookbook -> Dependencies** to install vLLM, SGLang, llama-cpp-python, or -diffusers into the persisted `./data/local` mount. Native CUDA builds inside the -container also require CUDA toolkit binaries such as `nvcc`; if those are not -installed in the container, use prebuilt Python wheels or serve from a remote -GPU host that already has the toolkit. - -Useful checks: -```bash -docker compose ps -docker compose logs --tail=120 odysseus -docker compose logs odysseus | grep -E 'ChromaDB|MemoryVectorStore|DEGRADED' -docker compose exec odysseus python -c "from services.hwfit.models import get_models; print(len(get_models()))" -``` - -Expected vector-memory startup lines in Docker: -```text -ChromaDB connected: chromadb:8000 -MemoryVectorStore initialized -``` - -The Cookbook model catalog check should print a non-zero count. If it prints -`0`, rebuild the Odysseus image with `docker compose build --no-cache odysseus`. - -### Option 2: Manual install — Linux / macOS -**Requirements:** Python 3.11+. Cookbook also requires `tmux` for background -model downloads and serves. - -> **On macOS (Apple Silicon)?** Skip the manual steps below — run -> `./start-macos.sh` for a one-command setup. See -> [Apple Silicon](#apple-silicon-m-series). - -Install system packages first: -```bash -# Debian/Ubuntu -sudo apt install tmux - -# Arch -sudo pacman -S tmux - -# Fedora -sudo dnf install tmux - -# macOS (Homebrew). macOS ships no recent Python by default — install 3.11+ -# (skip the python line if you already have Python 3.11 or newer): -brew install python@3.11 tmux -``` - -Then install Odysseus: +### Native Linux / macOS ```bash git clone https://github.com/pewdiepie-archdaemon/odysseus.git cd odysseus -python3 -m venv venv # on macOS use: python3.11 -m venv venv +python3 -m venv venv source venv/bin/activate pip install -r requirements.txt -python setup.py # creates data dirs and prints an initial admin password +python setup.py python -m uvicorn app:app --host 0.0.0.0 --port 7000 ``` +Requirements: Python 3.11+. Cookbook also needs `tmux` for background model +downloads and serves. -#### Apple Silicon (M-series) +### Apple Silicon +Docker on macOS cannot use the Metal GPU. For GPU-accelerated Cookbook on an +M-series Mac, run Odysseus natively: -> **On a Mac, run Odysseus natively (not in Docker) so Cookbook can use the -> Metal GPU.** Cookbook serves models on whatever machine Odysseus runs on, and -> Docker on macOS is a Linux VM with **no access to the GPU** — in a container -> your Mac looks like a CPU-only Linux box. - -**Quick start — one command.** From a fresh clone: ```bash git clone https://github.com/pewdiepie-archdaemon/odysseus.git cd odysseus ./start-macos.sh ``` -That installs what's needed via Homebrew (Python 3.11+, `tmux`, and a prebuilt -Metal `llama-server`), sets everything up, and launches Odysseus at -**http://127.0.0.1:7860**. Log in with the admin password it prints, open -**Cookbook**, and it detects your GPU (`backend: metal`) and recommends GGUF -models that fit your Mac. (MLX models aren't supported on macOS and are hidden — -see below.) Re-run `./start-macos.sh` any time to start it again (use another -port with `ODYSSEUS_PORT=7900 ./start-macos.sh`). -**Prefer a clickable app?** After your first `./start-macos.sh`, build a -launcher `Odysseus.app` (+ a drag-to-Applications `.dmg`) that starts the server -and opens the UI in its own window: +It launches at `http://127.0.0.1:7860`. To build a clickable app wrapper: + ```bash -./build-macos-app.sh # → dist/Odysseus.app and dist/Odysseus.dmg +./build-macos-app.sh ```
-What start-macos.sh does, serving engines, and manual steps +Cookbook, GPU, Ollama, and troubleshooting notes -`start-macos.sh` is just the manual steps wrapped up: Homebrew deps → a Python -`venv` → `pip install -r requirements.txt` → `python setup.py` → `uvicorn` on a -non-AirPlay port. Run them by hand if you prefer (the Linux steps above, but use -`python3.11 -m venv` and `--port 7860`). +**Docker bundled services.** Compose starts Odysseus, ChromaDB, SearXNG, and +ntfy. ChromaDB/SearXNG/ntfy bind host ports to `127.0.0.1` by default, so they +are reachable from the host but not exposed to your LAN/public internet unless +you opt in. -**Serving engines on Metal** — Cookbook only recommends models it can serve here: -- **llama.cpp** — `brew install llama.cpp` (done by `start-macos.sh`) provides a - prebuilt Metal `llama-server`, no compile. Without it, Cookbook builds it from - source on first serve, which needs `cmake` + Xcode Command Line Tools - (`brew install cmake && xcode-select --install`). -- **Ollama** — `brew install ollama` is another simple Metal-accelerated option. -- vLLM/SGLang are CUDA/ROCm-only and do **not** run on macOS. +**Cookbook storage in Docker.** Downloads live in `./data/huggingface` +(`~/.cache/huggingface` in the container). Cookbook-installed Python CLIs and +serve engines live in `./data/local` (`~/.local` in the container), so they +survive container recreation. -**MLX models are not supported on Apple Silicon.** Odysseus serves models via -llama.cpp/Ollama (GGUF) and vLLM/SGLang (CUDA) — it has no MLX (`mlx_lm`) -runtime. So MLX-only models can't be served on a Mac and are deliberately -**hidden** from Cookbook's recommendations there; pick a GGUF build instead. +**Remote servers.** In **Cookbook -> Settings -> Servers**, generate the +Odysseus SSH key and add the public key to the remote server's +`~/.ssh/authorized_keys`. From the host you can also run: -**Port 7000 & AirPlay** — macOS AirPlay Receiver holds ports 7000/5000, so -`start-macos.sh` defaults to **7860**. To use 7000, turn AirPlay Receiver off in -System Settings → General → AirDrop & Handoff. - -**Build prerequisites baked in** — the `.app` wraps this repo's `venv` (it -doesn't bundle Python), so the path is fixed at build time — rebuild if you move -the repo. -
- -### Option 3: Manual install — Windows (PowerShell) -Windows support is not actively tested. Use it with caution; Docker on Linux -or a Linux/macOS manual install is the safer path for now. - -```powershell -git clone https://github.com/pewdiepie-archdaemon/odysseus.git -cd odysseus -python -m venv venv -venv\Scripts\Activate.ps1 -pip install -r requirements.txt -python setup.py -python -m uvicorn app:app --host 0.0.0.0 --port 7000 +```bash +ssh-copy-id -i data/ssh/id_ed25519.pub user@server ``` -Open `http://localhost:7000`, log in with the generated admin password, -and configure everything else inside **Settings**. +**NVIDIA / AMD Docker GPU overlays.** Install the host runtime first, then add +one of these to `.env`: + +```bash +COMPOSE_FILE=docker-compose.yml:docker/gpu.nvidia.yml +COMPOSE_FILE=docker-compose.yml:docker/gpu.amd.yml +``` + +Verify with: + +```bash +docker compose exec odysseus nvidia-smi -L +docker compose exec odysseus rocm-smi +``` + +**Ollama with Docker.** If Ollama runs on the host, add this endpoint in +Settings: + +```text +http://host.docker.internal:11434/v1 +``` + +Ollama must listen outside its own loopback interface: + +```bash +OLLAMA_HOST=0.0.0.0:11434 ollama serve +``` + +**Useful checks.** + +```bash +docker compose ps +docker compose logs --tail=120 odysseus +docker compose logs odysseus | grep -E 'ChromaDB|MemoryVectorStore|DEGRADED' +``` + +**macOS details.** `start-macos.sh` installs Homebrew deps, creates the venv, +runs setup, and starts uvicorn on port `7860` because AirPlay often holds +`7000`. It uses llama.cpp/Ollama for Metal. vLLM/SGLang are CUDA/ROCm-only and +do not run on macOS. MLX-only models are not served by Odysseus. + + ## Security Notes Odysseus is a self-hosted workspace with powerful local tools: shell access, file uploads, model downloads, web research, email/calendar integrations, and API tokens. Treat it like an admin console. @@ -274,21 +202,6 @@ Key settings: | `CHROMADB_PORT` | `8100` | ChromaDB port for manual host runs. Docker overrides this to `8000`. | | `EMBEDDING_URL` | -- | OpenAI-compatible embeddings endpoint | -### Bundled services -Docker Compose includes these by default. The bundled service ports bind to `127.0.0.1` unless you opt in to a different bind address in `.env`, so they are reachable from the host machine but not from your LAN or the public internet by default: - - - **ChromaDB** → vector store for semantic memory. In Docker, Odysseus connects to `chromadb:8000`; from the host it is exposed as `${CHROMADB_BIND:-127.0.0.1}:8100`. - - **SearXNG** → meta search for web search. In Docker, Odysseus connects to `searxng:8080`; from the host it is exposed as `127.0.0.1:8080`. - - **ntfy** → local notification service, exposed as `${NTFY_BIND:-127.0.0.1}:8091`. - -**Phone push notifications via ntfy:** A phone cannot subscribe to `127.0.0.1` on your server. To expose ntfy safely without opening it on every interface: - - - **Tailscale (recommended)** — set `NTFY_BIND=` and `NTFY_BASE_URL=http://:8091` in `.env`, recreate ntfy, then point the ntfy Android/iOS app at `http://:8091/`. - - **Enable ntfy auth and bind to LAN** — add `NTFY_AUTH_FILE` + `NTFY_AUTH_DEFAULT_ACCESS=deny-all` to the `ntfy` service, create a user with `docker compose exec ntfy ntfy user add ...`, then set `NTFY_BIND` to your LAN IP. See the [ntfy docs](https://docs.ntfy.sh/config/#access-control). - -### Optional external services - - **Ollama** → local LLM server -- [ollama.ai](https://ollama.ai) - ### Built-in MCP servers (optional setup) Odysseus auto-registers a few built-in MCP servers at startup. The npx-based ones (currently the browser server, `@playwright/mcp`) only start when their npm package is already in the local npx cache. If a package isn't cached, that server is skipped with a startup log message explaining what to do, so a fresh install does not block on a multi-minute npm download or hang if Playwright system deps are missing. @@ -301,25 +214,6 @@ npx -y @playwright/mcp@latest --version That installs `@playwright/mcp` plus Playwright (~300MB total). Restart Odysseus and the server will register at startup. -### Ollama with Docker -If Odysseus is running in Docker and Ollama is running on the host, add the endpoint in Settings as: - -`http://host.docker.internal:11434/v1` - -The default Compose file already maps `host.docker.internal` on Linux. Ollama also needs to listen outside its own loopback interface: - -```bash -OLLAMA_HOST=0.0.0.0:11434 ollama serve -``` - -For a systemd Ollama install, set that in the Ollama service override. If Odysseus can see Ollama but requests hang or fail, check that your host firewall allows Docker bridge traffic to port `11434`. - -First-token latency is usually Ollama/model/hardware, not Odysseus. To compare, test Ollama directly: - -```bash -curl http://127.0.0.1:11434/v1/models -``` - ## Architecture ``` app.py # FastAPI entry point