Repo Year in Review Limited info

odysseus-dev/odysseus

Self-hosted AI workspace for chat, agents, research, documents, email, notes, calendar and local model workflows, deployed with Docker Compose.

  • 92.5k GitHub stars
  • Python
  • ⚖️ AGPL-3.0
View on GitHub (opens in a new tab) Setup guide
odysseus-dev/odysseus preview image

What it is

Odysseus is a self-hosted AI workspace that combines chat and agents, deep research, a document editor, email, notes, tasks, calendar and local model workflows in one app. It supports local and API models, tools, MCP, files, shell, skills and memory. The quick start runs it with Docker Compose, using an official multi-arch image from ghcr.io. It is licensed AGPL-3.0-or-later.

Who it's for

  • Users who want a self-hosted AI workspace instead of a hosted service
  • People running local or API models who want chat, agents and tools in one interface
  • Self-hosters comfortable deploying with Docker Compose or Portainer
  • Contributors interested in fresh-install testing, provider setup bugs, mobile/editor polish and docs

Requirements

Requirements

  • Docker with Docker Compose (the quick start uses docker compose)
  • Git, to clone the repository
  • A .env file copied from .env.example
  • Port 7011 on localhost for the web UI

Setup

  1. Clone, configure and start

    Clone the repo, copy the example env file, and start the containers. The compose files pull the official image and only build locally if the pull fails.

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

  2. Open the app and get the admin password

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

  3. Pin an immutable image for production

    For production, pin the immutable :X.Y.Z-<sha> tag instead of :latest, which moves on every push to main.

    bash
    ODYSSEUS_IMAGE=ghcr.io/odysseus-dev/odysseus:1.0.2-7c8070f docker compose up -d

Examples

Quick start with Docker Compose

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

What it does: Clones the repository, creates the environment file and starts Odysseus in the background.

Pin a specific build

bash
bash
ODYSSEUS_IMAGE=ghcr.io/odysseus-dev/odysseus:1.0.2-7c8070f docker compose up -d

What it does: Overrides the image with an immutable tag so production deployments always run one specific build.

Pros & cons

Pros

  • Pro:Broad feature set in one workspace: chat, agents, deep research, documents, email, notes, tasks and calendar
  • Pro:Supports both local and API models, plus MCP, tools, skills and memory
  • Pro:Simple Docker Compose deployment with an official multi-arch image and immutable tags for pinning
  • Pro:Includes security options such as AUTH_ENABLED and 2FA

Cons

  • Con:Has powerful local tools (such as shell access), so it needs careful security configuration and must not expose raw model/service ports publicly
  • Con:The default branch dev gets changes first, while main is the more curated branch
  • Con:AGPL-3.0-or-later license may constrain some uses

Images

odysseus-dev/odysseus preview image
odysseus-dev/odysseus preview image · odysseus-dev/odysseus on GitHub · AGPL-3.0
odysseus-dev/odysseus preview image