{"id":50578106,"url":"https://github.com/pewdiepie-archdaemon/odysseus","last_synced_at":"2026-06-08T09:00:46.391Z","repository":{"id":361728329,"uuid":"1255180606","full_name":"pewdiepie-archdaemon/odysseus","owner":"pewdiepie-archdaemon","description":"Self-hosted AI workspace. ","archived":false,"fork":false,"pushed_at":"2026-06-01T02:53:00.000Z","size":20173,"stargazers_count":8748,"open_issues_count":114,"forks_count":1224,"subscribers_count":99,"default_branch":"main","last_synced_at":"2026-06-01T03:20:04.089Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/pewdiepie-archdaemon.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":"ROADMAP.md","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-31T14:05:51.000Z","updated_at":"2026-06-01T03:19:56.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/pewdiepie-archdaemon/odysseus","commit_stats":null,"previous_names":["pewdiepie-archdaemon/odysseus"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/pewdiepie-archdaemon/odysseus","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pewdiepie-archdaemon%2Fodysseus","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pewdiepie-archdaemon%2Fodysseus/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pewdiepie-archdaemon%2Fodysseus/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pewdiepie-archdaemon%2Fodysseus/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/pewdiepie-archdaemon","download_url":"https://codeload.github.com/pewdiepie-archdaemon/odysseus/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pewdiepie-archdaemon%2Fodysseus/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34055249,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-08T02:00:07.615Z","response_time":111,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-06-05T00:00:33.526Z","updated_at":"2026-06-08T09:00:46.384Z","avatar_url":"https://github.com/pewdiepie-archdaemon.png","language":"JavaScript","funding_links":[],"categories":["Python","others"],"sub_categories":[],"readme":"# Odysseus\n\n```\n───────────────────────────────────────────────\n ⊹ ࣪ ˖ ૮( ˶ᵔ ᵕ ᵔ˶ )っ  Odysseus vers. 1.0\n───────────────────────────────────────────────\n```\n\n![Odysseus](docs/odysseus.jpg)\n\nA self-hosted AI workspace -- meant to be the self-hosted version of the UI experience you get from ChatGPT and Claude. But with more jank and fun. Running on your own hardware, with your own data -- local-first, privacy-first, and no trojan.\n\n## Features\n  - **Chat** -- chat with any local model or API; adding them is super simple.\u003cbr\u003e　\u003csub\u003evLLM · llama.cpp · Ollama · OpenRouter · OpenAI · GitHub Copilot\u003c/sub\u003e\n  - **Agent** -- hand it tools and let it run the whole task itself.\u003cbr\u003e　\u003csub\u003ebuilt on [opencode](https://github.com/anomalyco/opencode) · MCP · web · files · shell · skills · memory\u003c/sub\u003e\n  - **Cookbook** -- Scans your hardware, recommends models, click to download and serve.. easy!\u003cbr\u003e　\u003csub\u003ebuilt on [llmfit](https://github.com/AlexsJones/llmfit) · VRAM-aware · GGUF / FP8 / AWQ · fit scoring · vLLM / llama.cpp serving\u003c/sub\u003e\n  - **Deep Research** -- multi-step runs that gather, read, and synthesize sources into a nice visual report.\u003cbr\u003e　\u003csub\u003eadapted from [Tongyi DeepResearch](https://github.com/Alibaba-NLP/DeepResearch)\u003c/sub\u003e\n  - **Compare** -- a fun tool to compare models side by side. Test completely blind, no bias!\u003cbr\u003e　\u003csub\u003emulti-model · blind test · synthesis\u003c/sub\u003e\n  - **Documents** -- YOU write the text, AI is there to assist, not the opposite.\u003cbr\u003e　\u003csub\u003emulti-tab editor · markdown · HTML · CSV · syntax highlighting · AI edits · suggestions\u003c/sub\u003e\n  - **Memory / Skills** -- Persistent memory and skills, your agent evolves over time as it better understands you and your tasks!\u003cbr\u003e　\u003csub\u003eChromaDB · fastembed (ONNX) · vector + keyword retrieval · import/export\u003c/sub\u003e\n  - **Email** -- IMAP/SMTP inbox with AI triage built in: urgency reminders, auto-tag, auto-summary, auto-reply drafts, auto-spam.\u003cbr\u003e　\u003csub\u003eIMAP · SMTP · per-account routing · CalDAV-aware\u003c/sub\u003e\n  - **Notes \u0026 Tasks** -- Quick notes with reminders, a todo list, and scheduled tasks the agent can act on.\u003cbr\u003e　\u003csub\u003enote pings · checklist · cron-style tasks · ntfy / browser / email channels\u003c/sub\u003e\n  - **Calendar** -- Local-first calendar with CalDAV sync to Radicale / Nextcloud / Apple / Fastmail.\u003cbr\u003e　\u003csub\u003eCalDAV pull · .ics import/export · per-calendar colors · agent-aware\u003c/sub\u003e\n  - **Works on mobile** -- looks and runs great on your phone, not just desktop.\u003cbr\u003e　\u003csub\u003eresponsive · installable (PWA) · touch gestures\u003c/sub\u003e\n  - **Extras** -- more to explore, happy if you give it a go!\u003cbr\u003e　\u003csub\u003eimage editor · theme editor · file uploads (vision + PDF) · web search · presets · sessions · 2FA\u003c/sub\u003e\n\n## Demo\nA full, hover-to-play tour lives on the landing page (`docs/index.html`).\n\n\u003cdetails\u003e\n\u003csummary\u003eScreenshots / clips\u003c/summary\u003e\n\n### Chat \u0026 Agents\n![Chat \u0026 Agents](docs/chat.gif)\n### Deep Research\n![Deep Research](docs/research.gif)\n### Compare\n![Compare](docs/compare.gif)\n### Documents\n![Documents](docs/document.gif)\n### Notes \u0026 Tasks\n![Notes \u0026 Tasks](docs/notes.gif)\n\n\u003c/details\u003e\n\n## Quick Start\n\nDefaults work out of the box: clone, run, then configure models/search/email\ninside **Settings**. Only edit `.env` for deployment-level overrides like\n`APP_BIND`, `APP_PORT`, `AUTH_ENABLED`, `DATABASE_URL`, or a pre-seeded admin password.\n\nOn first setup, Odysseus creates an admin account (`admin` unless\n`ODYSSEUS_ADMIN_USER` is set) and prints a temporary password in the terminal.\nFor Docker installs, the same line is in `docker compose logs odysseus`.\nUse that for the first login, then change it in **Settings**.\n\nContributing? See [CONTRIBUTING.md](CONTRIBUTING.md) for setup, testing, and\npull request guidelines.\n\n### Docker (recommended)\n```bash\ngit clone https://github.com/pewdiepie-archdaemon/odysseus.git\ncd odysseus\ncp .env.example .env       # optional, but recommended for explicit defaults\ndocker compose up -d --build\n```\nTo include optional extras in the image (PDF viewer, Office extraction; includes AGPL PyMuPDF), build with `docker compose build --build-arg INSTALL_OPTIONAL=true` before `up`.\n\nOpen `http://localhost:7000` when the containers are healthy. Docker Compose\nbinds the web UI to `127.0.0.1` by default. If the port is taken, set\n`APP_PORT=7001` in `.env` and recreate the container. Set `APP_BIND=0.0.0.0`\nonly when you intentionally want LAN/reverse-proxy access.\n\n### Native Linux / macOS\n```bash\ngit clone https://github.com/pewdiepie-archdaemon/odysseus.git\ncd odysseus\npython3 -m venv venv\nsource venv/bin/activate\npip install -r requirements.txt\npython setup.py\npython -m uvicorn app:app --host 127.0.0.1 --port 7000\n```\nRequirements: Python 3.11+. Cookbook also needs `tmux` for background model\ndownloads and serves. The app itself is lightweight; local model serving is the\nheavy part and depends on the model, runtime, GPU, and VRAM, so small hosts can\nconnect to API or remote model servers instead. Use `--host 0.0.0.0` only when you intentionally want LAN/reverse-proxy access.\n\n### Apple Silicon\nDocker on macOS cannot use the Metal GPU. For GPU-accelerated Cookbook on an\nM-series Mac, run Odysseus natively:\n\n```bash\ngit clone https://github.com/pewdiepie-archdaemon/odysseus.git\ncd odysseus\n./start-macos.sh\n```\n\nIt launches at `http://127.0.0.1:7860`. To expose it to your phone over a trusted LAN/VPN such as Tailscale, bind all interfaces:\n\n```bash\nODYSSEUS_HOST=0.0.0.0 ./start-macos.sh\n# then open http://\u003ctailscale-ip\u003e:7860\n```\n\nThe script also reads `.env` at startup, so `APP_BIND=0.0.0.0` and `APP_PORT`\nset there are picked up automatically without a command-line override each run.\n\nKeep `AUTH_ENABLED=true` (the default) before binding outside loopback. Do not\nexpose this port directly to the public internet. To build a clickable app wrapper:\n\n```bash\n./build-macos-app.sh\n```\n\n\u003cdetails\u003e\n\u003csummary\u003eCookbook, GPU, Ollama, and troubleshooting notes\u003c/summary\u003e\n\n**Docker bundled services.** Compose starts Odysseus, ChromaDB, SearXNG, and\nntfy. Odysseus and the bundled service ports bind to `127.0.0.1` by default, so\nthey are reachable from the host but not exposed to your LAN/public internet\nunless you opt in.\n\n**Cookbook storage in Docker.** Downloads live in `./data/huggingface`\n(`~/.cache/huggingface` in the container). Cookbook-installed Python CLIs and\nserve engines live in `./data/local` (`~/.local` in the container), so they\nsurvive container recreation.\n\n**Remote servers.** In **Cookbook -\u003e Settings -\u003e Servers**, generate the\nOdysseus SSH key and add the public key to the remote server's\n`~/.ssh/authorized_keys`. From the host you can also run:\n\n```bash\nssh-copy-id -i data/ssh/id_ed25519.pub user@server\n```\n\n**Docker GPU overlays.** CPU-only users can skip this section. Cookbook can\nonly detect GPUs that Docker exposes to the container — if the host runtime or\ndevice passthrough is not configured, Cookbook sees the iGPU, another card, or\nCPU instead of your intended GPU.\n\nFor NVIDIA, `scripts/check-docker-gpu.sh` diagnoses GPU passthrough and can\noptionally install the host runtime or update `.env`.\n\n```bash\n# Read-only diagnostic (default — installs nothing, never edits .env):\nscripts/check-docker-gpu.sh\n\n# Print OS-specific install commands without running them:\nscripts/check-docker-gpu.sh --print-install-commands\n\n# Install NVIDIA Container Toolkit on Ubuntu/Debian (requires sudo):\nscripts/check-docker-gpu.sh --install-nvidia-toolkit\n\n# Write COMPOSE_FILE to .env (only when GPU passthrough is confirmed working):\nscripts/check-docker-gpu.sh --enable-nvidia-overlay\n\n# Full assisted setup — install toolkit, then enable overlay if passthrough works:\nscripts/check-docker-gpu.sh --install-nvidia-toolkit --enable-nvidia-overlay\n```\n\nSafety notes:\n- The app never installs host GPU runtime automatically.\n- The app never edits `.env` automatically.\n- `.env` is only modified when `--enable-nvidia-overlay` is explicitly passed,\n  and only after GPU passthrough succeeds. `--yes` skips prompts but does not\n  bypass the passthrough gate.\n- `.env.bak.*` backups created by `--enable-nvidia-overlay` are ignored by\n  Git and the Docker build context.\n\nTo enable manually without the script, add this to `.env`:\n\n```bash\nCOMPOSE_FILE=docker-compose.yml:docker/gpu.nvidia.yml\n```\n\n**AMD / ROCm.** AMD setup is read-only diagnostic plus manual `.env` edit. Run:\n\n```bash\nscripts/check-docker-amd-gpu.sh\n```\n\nThen add the reported values to `.env`, replacing `RENDER_GID` with your host's\nnumeric render group id:\n\n```bash\nCOMPOSE_FILE=docker-compose.yml:docker/gpu.amd.yml\nRENDER_GID=989\n```\n\nFor NVIDIA/AMD GPU support, also read the comments in the selected overlay file: docker/gpu.nvidia.yml or docker/gpu.amd.yml.\n\n**Stack-management UIs (Portainer, Coolify, Dockhand, etc.).** These tools\noften accept only a single Compose file and do not reliably honor `COMPOSE_FILE`\nor multiple `-f` overlays. CLI users should keep using the `COMPOSE_FILE`\noverlay workflow above. For stack UIs, point the stack at one of the standalone\nfiles instead, which bundle the base stack plus the GPU settings:\n\n- `docker-compose.gpu-nvidia.yml` — still requires the NVIDIA Container Toolkit\n  on the host.\n- `docker-compose.gpu-amd.yml` — still requires host ROCm/kfd/DRI setup, the\n  `video`/`render` group membership, and `RENDER_GID` when needed.\n\nThe base `docker-compose.yml` plus the `docker/gpu.*.yml` overlays remain the\nsource of truth; the standalone files mirror them for single-file deployments.\n\nVerify after enabling either overlay:\n\n```bash\ndocker compose exec odysseus nvidia-smi -L   # NVIDIA\ndocker compose exec odysseus sh -lc 'test -e /dev/kfd \u0026\u0026 test -d /dev/dri \u0026\u0026 ls -l /dev/kfd /dev/dri/renderD*'  # AMD\n```\n\n\u003e **GPU passthrough ≠ llama.cpp CUDA.** `nvidia-smi` passing inside the\n\u003e container confirms Docker GPU access, but llama.cpp also needs `cudart` and\n\u003e the CUDA Toolkit at runtime. If Cookbook logs show `Unable to find cudart\n\u003e library`, `Could NOT find CUDAToolkit`, `CUDA Toolkit not found`, or\n\u003e tensors/layers assigned to CPU, that is a Cookbook/llama.cpp build issue —\n\u003e not a Docker passthrough failure. Re-install the serve engine via\n\u003e **Cookbook → Dependencies** to get a CUDA-enabled build.\n\u003e\n\u003e The same split applies to AMD/ROCm: seeing `/dev/kfd` and `/dev/dri` inside\n\u003e the container confirms device passthrough, not ROCm userspace or a\n\u003e ROCm-enabled vLLM/llama.cpp build. `rocm-smi` and `rocminfo` are not expected\n\u003e inside the slim Odysseus image.\n\n**Ollama with Docker.** If Ollama runs on the host, add this endpoint in\nSettings:\n\n```text\nhttp://host.docker.internal:11434/v1\n```\n\nOllama must listen outside its own loopback interface:\n\n```bash\nOLLAMA_HOST=0.0.0.0:11434 ollama serve\n```\n\nThis connects Odysseus in Docker to an Ollama server that is already running on\nyour host machine; it does not start Ollama inside the container.\n`host.docker.internal` is Docker's hostname for the host machine from inside the\ncontainer. Cookbook **Serve** is a separate workflow for serving downloaded\nmodels through Odysseus/llama.cpp, so Windows users with an existing Ollama\ninstall usually only need to add the endpoint in Settings.\n\n**Useful checks.**\n\n```bash\ndocker compose ps\ndocker compose logs --tail=120 odysseus\ndocker compose logs odysseus | grep -E 'ChromaDB|MemoryVectorStore|DEGRADED'\n```\n\n**macOS details.** `start-macos.sh` installs Homebrew deps, creates the venv,\nruns setup, and starts uvicorn on port `7860` because AirPlay often holds\n`7000`. It uses llama.cpp/Ollama for Metal. vLLM/SGLang are CUDA/ROCm-only and\ndo not run on macOS. MLX-only models are not served by Odysseus.\n\n\u003c/details\u003e\n\n### Native Windows\n\n**One-command launcher** (creates the venv, installs deps, runs setup, starts the\nserver; safe to re-run):\n\n```powershell\ngit clone https://github.com/pewdiepie-archdaemon/odysseus.git\ncd odysseus\npowershell -ExecutionPolicy Bypass -File .\\launch-windows.ps1\n```\n\nOr do it by hand:\n\n```powershell\ngit clone https://github.com/pewdiepie-archdaemon/odysseus.git\ncd odysseus\npy -3.11 -m venv venv\nvenv\\Scripts\\Activate.ps1\npip install -r requirements.txt\npython setup.py\npython -m uvicorn app:app --host 127.0.0.1 --port 7000\n```\n\nIf `python` points at an older interpreter, use `py -3.12` (or another installed\n3.11+ version) for the venv step.\n\n**Requirements:** Python 3.11+. The core app (chat, agent, memory, documents,\nemail, calendar, deep research) runs fully native. For full **Cookbook** background\nmodel downloads and the agent shell tool, also install\n[Git for Windows](https://git-scm.com/download/win) (provides `bash.exe`).\nLocal GPU *serving* of vLLM/SGLang needs Linux/WSL2; for a local model on Windows,\n[Ollama](https://ollama.com/download) is the easiest path — point Odysseus at\n`http://localhost:11434/v1` in Settings.\n\nOpen `http://localhost:7000`, log in with the generated admin password,\nand configure everything else inside **Settings**.\n\n## Troubleshooting \u0026 Advanced Setup\n\n### `chromadb-client` conflicts with embedded ChromaDB\nIf `chromadb-client` (the lightweight HTTP-only package) is installed alongside the full `chromadb` package, Odysseus starts but ChromaDB silently falls back to HTTP-only mode and fails.\n\n**Fix:** uninstall `chromadb-client` and force-reinstall the full package:\n```bash\n./venv/bin/pip uninstall chromadb-client -y\n./venv/bin/pip install --force-reinstall chromadb\n```\n\n### HTTPS + LAN/Tailscale exposure\nTo expose Odysseus on a local network or Tailscale with HTTPS:\n1. Change the bind address to `0.0.0.0` in `.env` (`APP_BIND=0.0.0.0` or `ODYSSEUS_HOST=0.0.0.0`).\n2. Generate a locally-trusted cert for your LAN/Tailscale IPs using [mkcert](https://github.com/FiloSottile/mkcert):\n   ```bash\n   mkcert -install\n   mkcert -cert-file cert.pem -key-file key.pem 192.168.1.100 tailscale-ip\n   ```\n3. Run `uvicorn` with the generated certs:\n   ```bash\n   python -m uvicorn app:app --host 0.0.0.0 --port 7000 --ssl-certfile=cert.pem --ssl-keyfile=key.pem\n   ```\n4. Install the `mkcert` CA on any other device you want to access Odysseus from (e.g., for iOS, email the `rootCA.pem` to yourself, install the profile, and trust it in Certificate Trust Settings).\n\n### Optional Dependencies\n`requirements-optional.txt` contains packages that unlock extra features. It is not installed by default.\n\n| Package | Feature unlocked |\n|---------|-----------------|\n| `faster-whisper` | Local speech-to-text (microphone -\u003e text) via the \"local\" STT provider. |\n| `duckduckgo-search` | DuckDuckGo as a search provider option. |\n| `PyMuPDF` | PDF page rendering in the side viewer panel and form-filling. (Note: AGPL-3.0) |\n| `markitdown` | Office/EPUB document text extraction (converts .docx/.xlsx/.pptx/.xls/.epub to Markdown). |\n\n## Security Notes\nOdysseus 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.\n\n- Keep `AUTH_ENABLED=true` for any network-accessible deployment.\n- Keep `LOCALHOST_BYPASS=false` outside local development.\n- Use `SECURE_COOKIES=true` when Odysseus is served through HTTPS by a trusted reverse proxy or private access gateway.\n- Do not expose it directly to the public internet without HTTPS and a trusted reverse proxy or private access layer.\n- Keep `.env`, `data/`, `logs/`, databases, uploads, generated media, backups, auth/session files, API keys, and model/provider tokens out of Git and private shares. They are ignored by default.\n- Review `data/auth.json` after first boot: disable open signup unless you intentionally want it, make only your own account admin, and keep demo/test accounts non-admin.\n- Non-admin users do not get shell/Python/file read/write by default, and admin-only routes/tools such as MCP management, API tokens, webhooks, model/cookbook serving, backup/vault, and app settings are admin-gated. Other features are controlled by per-user privileges, so review each user's privileges before exposing a deployment.\n- Rotate any API keys or tokens that were ever pasted into a shared chat, demo, screenshot, or log.\n- If you enable API tokens or webhooks, create separate tokens per integration and delete unused ones.\n- Prefer binding manual development runs to `127.0.0.1`; bind to `0.0.0.0` only when you intentionally want LAN/reverse-proxy access.\n- Keep ChromaDB, SearXNG, ntfy, Ollama, vLLM, llama.cpp, databases, and raw model/provider APIs internal-only. Expose only the authenticated Odysseus web/API entrypoint through your trusted proxy or private access layer.\n- Before publishing a fork, run `git status --short` and confirm no private files from `.env`, `data/`, `logs/`, uploads, backups, or local databases are staged.\n\n### Private or proxied deployments\nOdysseus serves plain HTTP on its app port. Docker Compose binds Odysseus and the bundled services to `127.0.0.1` by default, so a typical production/private setup is:\n\n1. Keep Odysseus on localhost, for example `127.0.0.1:7000`.\n2. Terminate HTTPS at a trusted reverse proxy or private access gateway.\n3. Put the authenticated Odysseus web/API entrypoint behind that layer.\n4. Keep raw service and model ports internal-only.\n\nCloudflare Access, Tailscale, Caddy, nginx, and Traefik can all fit this pattern; none are required by Odysseus. If your access layer reaches Odysseus on the same host, proxy to `http://127.0.0.1:7000` and keep `AUTH_ENABLED=true`, `LOCALHOST_BYPASS=false`, and `SECURE_COOKIES=true`.\n\nCommon internal-only ports from the default docs/compose setup:\n\n| Port | Service |\n|---|---|\n| `7000` | Odysseus raw app port |\n| `8080` | SearXNG |\n| `8091` | ntfy |\n| `8100` | ChromaDB host port for manual/compose access |\n| `11434` | Ollama |\n| `8000-8020` | Common local model/provider APIs |\n\n## Contributing\nHelp is welcome. The best entry points are fresh-install testing, provider setup\nbugs, mobile/editor polish, docs, and small focused refactors. See\n[ROADMAP.md](ROADMAP.md) for the current help-wanted list.\n\n## Configuration\nMost setup is done inside the app with `/setup` or **Settings**. Use `.env`\nfor deployment-level defaults and secrets you want present before first boot.\nKey settings:\n\n| Variable | Default | Description |\n|---|---|---|\n| `LLM_HOST` | `localhost` | Your LLM server (e.g. `llm-host.local:8000`) |\n| `LLM_HOSTS` | -- | Comma-separated list for model discovery |\n| `OPENAI_API_KEY` | -- | Optional OpenAI key. Prefer adding providers in the app unless pre-seeding. |\n| `SEARXNG_INSTANCE` | `http://localhost:8080` | SearXNG URL. Docker overrides this to `http://searxng:8080`. |\n| `SEARXNG_SECRET` | generated on first Docker boot | Optional SearXNG cookie/CSRF secret. Leave blank unless you need to pin it. |\n| `APP_BIND` | `127.0.0.1` | Docker Compose host bind address for the web UI. Use `0.0.0.0` only for intentional LAN/reverse-proxy access. |\n| `APP_PORT` | `7000` | Docker Compose host port for the web UI. |\n| `AUTH_ENABLED` | `true` | Enable/disable login |\n| `LOCALHOST_BYPASS` | `false` | Development-only auth bypass for loopback requests. Keep false for shared/network deployments. |\n| `SECURE_COOKIES` | `false` | Set true when serving Odysseus through HTTPS at a trusted proxy or private access gateway. |\n| `DATABASE_URL` | `sqlite:///./data/app.db` | Database connection string |\n| `CHROMADB_HOST` | `localhost` | ChromaDB host for vector memory. Docker overrides this to `chromadb`. |\n| `CHROMADB_PORT` | `8100` | ChromaDB port for manual host runs. Docker overrides this to `8000`. |\n| `EMBEDDING_URL` | -- | OpenAI-compatible embeddings endpoint |\n\n### Built-in MCP servers (optional setup)\n\nOdysseus 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.\n\nTo enable the browser MCP (page navigation, screenshots, vision), run once:\n\n```bash\nnpx -y @playwright/mcp@latest --version\n```\n\nThat installs `@playwright/mcp` plus Playwright (~300MB total). Restart Odysseus and the server will register at startup.\n\n## Architecture\n```\napp.py                   # FastAPI entry point\ncore/      auth, database, middleware, constants\nsrc/       llm_core, agent_loop, agent_tools, chat_processor, search/\nroutes/    chat, session, document, memory, model … endpoints\nservices/  docs, memory, search, hwfit (Cookbook) …\nstatic/    index.html + app.js + style.css + js/ (modular front-end)\ndocs/      landing page (index.html) + preview clips\n```\n\n## Data\nAll user data lives in `data/` (gitignored): `app.db` (sessions, messages, documents),\n`memory.json`, `presets.json`, `uploads/`, `personal_docs/`, `chroma/`, `settings.json`.\n\n## Star History\n\n\u003ca href=\"https://www.star-history.com/?repos=pewdiepie-archdaemon%2Fodysseus\u0026type=date\u0026legend=top-left\"\u003e\n \u003cpicture\u003e\n   \u003csource media=\"(prefers-color-scheme: dark)\" srcset=\"https://api.star-history.com/chart?repos=pewdiepie-archdaemon/odysseus\u0026type=date\u0026theme=dark\u0026legend=top-left\" /\u003e\n   \u003csource media=\"(prefers-color-scheme: light)\" srcset=\"https://api.star-history.com/chart?repos=pewdiepie-archdaemon/odysseus\u0026type=date\u0026legend=top-left\" /\u003e\n   \u003cimg alt=\"Star History Chart\" src=\"https://api.star-history.com/chart?repos=pewdiepie-archdaemon/odysseus\u0026type=date\u0026legend=top-left\" /\u003e\n \u003c/picture\u003e\n\u003c/a\u003e\n\n## License\nMIT -- see [LICENSE](LICENSE) and [ACKNOWLEDGMENTS.md](ACKNOWLEDGMENTS.md).\n\n```\n                                  |\n                                 |||\n                                |||||\n                  |    |    |   |||||||\n                 )_)  )_)  )_)   ~|~\n                )___))___))___)\\  |\n               )____)____)_____)\\\\|\n             _____|____|____|_____\\\\\\__\n             \\                       /\n       ~^~^~~^~^~~^~^~~^~^~~^~^~~^~^~~^~^~~^~^~\n               ~^~  all aboard!  ~^~\n       ~^~^~~^~^~~^~^~~^~^~~^~^~~^~^~~^~^~~^~^~\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpewdiepie-archdaemon%2Fodysseus","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpewdiepie-archdaemon%2Fodysseus","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpewdiepie-archdaemon%2Fodysseus/lists"}