odysseus/README.md

<p align="center">
  <img src="docs/odysseus-wordmark.png" alt="Odysseus" width="238">
</p>

<p align="center">
  A self-hosted AI workspace for chat, agents, research, documents, email, notes, calendar, and local model workflows.
</p>

<p align="center">
  <a href="#quick-start">Quick Start</a> ·
  <a href="docs/setup.md">Setup Guide</a> ·
  <a href="CONTRIBUTING.md">Contributing</a> ·
  <a href="ROADMAP.md">Roadmap</a>
</p>

<p align="center">
  <a href="https://repology.org/project/odysseus-ai/versions"><img src="https://repology.org/badge/vertical-allrepos/odysseus-ai.svg" alt="Packaging status"></a>
</p>

<p align="center">
  <img src="docs/odysseus-browser.jpg" alt="Odysseus interface">
</p>

---

## Quick Start

> `dev` is the default branch and gets the newest changes first. Use [`main`](https://github.com/pewdiepie-archdaemon/odysseus/tree/main) if you want the more curated branch.

```bash
git clone https://github.com/pewdiepie-archdaemon/odysseus.git
cd odysseus
cp .env.example .env
docker compose up -d --build
```

Open `http://localhost:7000` when the containers are healthy. The first admin password is printed in `docker compose logs odysseus`.

### Dockge / Gitea Registry Image
Use this when you want Dockge to pull the prebuilt image from the Gitea
container registry instead of building Odysseus locally. The full compose file
is also available as `docker-compose.dockge.yml`.

```yaml
services:
  odysseus:
    image: git.wilkensxl.de/mrsphay/odysseus:latest
    ports:
      - "${APP_BIND:-127.0.0.1}:${APP_PORT:-7000}:7000"
    volumes:
      - ./data:/app/data:z
      - ./logs:/app/logs:z
      - ./data/ssh:/app/.ssh:z
      - ./data/huggingface:/app/.cache/huggingface:z
      - ./data/local:/app/.local:z
    extra_hosts:
      - "host.docker.internal:host-gateway"
    env_file:
      - .env
    environment:
      - SEARXNG_INSTANCE=http://searxng:8080
      - CHROMADB_HOST=chromadb
      - CHROMADB_PORT=8000
    depends_on:
      searxng:
        condition: service_started
      chromadb:
        condition: service_started
    restart: unless-stopped

  chromadb:
    image: docker.io/chromadb/chroma:latest
    ports:
      - "${CHROMADB_BIND:-127.0.0.1}:8100:8000"
    volumes:
      - chromadb-data:/chroma/chroma
    environment:
      - ANONYMIZED_TELEMETRY=FALSE
    restart: unless-stopped

  searxng:
    image: docker.io/searxng/searxng:2026.5.31-7159b8aed
    entrypoint:
      - /bin/sh
      - -c
      - |
        set -eu
        if [ ! -s /etc/searxng/settings.yml ] || grep -q 'odysseus-local-searxng-json-2026-05-30\|__SEARXNG_SECRET__' /etc/searxng/settings.yml; then
          secret="$${SEARXNG_SECRET:-}"
          if [ -z "$$secret" ]; then
            secret="$$(python -c 'import secrets; print(secrets.token_urlsafe(48))')"
          fi
          sed "s|__SEARXNG_SECRET__|$$secret|g" /tmp/searxng-settings.yml.template > /etc/searxng/settings.yml
        fi
        if ! grep -q '^default_doi_resolver:' /etc/searxng/settings.yml; then
          printf '\ndefault_doi_resolver: "oadoi.org"\n' >> /etc/searxng/settings.yml
        fi
        exec /usr/local/searxng/entrypoint.sh
    ports:
      - "127.0.0.1:8080:8080"
    volumes:
      - searxng-data:/etc/searxng
      - ./config/searxng/settings.yml:/tmp/searxng-settings.yml.template:ro,z
    environment:
      - SEARXNG_BASE_URL=http://localhost:8080/
      - SEARXNG_SECRET=${SEARXNG_SECRET:-}
    cap_drop:
      - ALL
    cap_add:
      - CHOWN
      - SETGID
      - SETUID
      - DAC_OVERRIDE
    healthcheck:
      test: ["CMD-SHELL", "python -c \"import urllib.request; urllib.request.urlopen('http://localhost:8080/', timeout=5).read(1)\""]
      interval: 5s
      timeout: 6s
      retries: 20
      start_period: 10s
    restart: unless-stopped

  ntfy:
    image: docker.io/binwiederhier/ntfy
    command: serve
    ports:
      - "${NTFY_BIND:-127.0.0.1}:8091:80"
    volumes:
      - ntfy-cache:/var/cache/ntfy
    environment:
      - NTFY_BASE_URL=${NTFY_BASE_URL:-http://localhost:8091}
    restart: unless-stopped

volumes:
  searxng-data:
  chromadb-data:
  ntfy-cache:
```

Minimal `.env` template:

```dotenv
APP_BIND=127.0.0.1
APP_PORT=7000
CHROMADB_BIND=127.0.0.1
NTFY_BIND=127.0.0.1

AUTH_ENABLED=true
LOCALHOST_BYPASS=false
ODYSSEUS_ADMIN_USER=admin
ODYSSEUS_ADMIN_PASSWORD=
ALLOWED_ORIGINS=http://localhost,http://127.0.0.1
SECURE_COOKIES=false

LLM_HOST=localhost
LLM_HOSTS=
OPENAI_API_KEY=
OLLAMA_BASE_URL=
RESEARCH_LLM_ENDPOINT=
HF_TOKEN=
HUGGING_FACE_HUB_TOKEN=
EMBEDDING_URL=
EMBEDDING_MODEL=
FASTEMBED_MODEL=sentence-transformers/all-MiniLM-L6-v2
FASTEMBED_CACHE_PATH=

DATA_BRAVE_API_KEY=
GOOGLE_API_KEY=
GOOGLE_PSE_CX=
TAVILY_API_KEY=
SERPER_API_KEY=

DATABASE_URL=sqlite:///./data/app.db
CLEANUP_INTERVAL_HOURS=24
ODYSSEUS_INPROCESS_POLLERS=1
ODYSSEUS_INPROCESS_TASKS=1
ODYSSEUS_SCRIPT_HOST=localhost
SEARXNG_SECRET=
PUID=1000
PGID=1000
```

Native installs, GPU notes, Windows/macOS instructions, HTTPS, and configuration live in the [setup guide](docs/setup.md).

## Features

- **Chat + Agents** — local/API models, tools, MCP, files, shell, skills, and memory.
- **Cookbook** — hardware-aware model recommendations, downloads, and serving.
- **Deep Research** — multi-step web research with source reading and report generation.
- **Compare** — blind side-by-side model testing and synthesis.
- **Documents** — writing-first editor with AI edits, suggestions, Markdown, HTML, CSV, and syntax highlighting.
- **Email** — IMAP/SMTP inbox with triage, tags, summaries, reminders, and reply drafts.
- **Notes, Tasks + Calendar** — reminders, todos, scheduled agent tasks, and CalDAV sync.
- **Extras** — gallery/image editor, themes, uploads, web search, presets, sessions, and 2FA.

## Demo

A full hover-to-play tour lives on the landing page: [`docs/index.html`](docs/index.html).

## Contributing

Help is welcome. The best entry points are fresh-install testing, provider setup bugs, mobile/editor polish, docs, and small focused refactors. See [CONTRIBUTING.md](CONTRIBUTING.md) and [ROADMAP.md](ROADMAP.md).

## Security

Odysseus is a self-hosted workspace with powerful local tools. Keep auth enabled, keep private data out of Git, and do not expose raw model/service ports publicly. Deployment details are in the [setup guide](docs/setup.md#security-notes).

## Star History

<a href="https://www.star-history.com/?repos=pewdiepie-archdaemon%2Fodysseus&type=date&legend=top-left">
 <picture>
   <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/chart?repos=pewdiepie-archdaemon/odysseus&type=date&theme=dark&legend=top-left" />
   <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/chart?repos=pewdiepie-archdaemon/odysseus&type=date&legend=top-left" />
   <img alt="Star History Chart" src="https://api.star-history.com/chart?repos=pewdiepie-archdaemon/odysseus&type=date&legend=top-left" />
 </picture>
</a>

## License

AGPL-3.0-or-later -- see [LICENSE](LICENSE) and [ACKNOWLEDGMENTS.md](ACKNOWLEDGMENTS.md).