2026-06-15 23:24:41 +09:00
<p align="center">
<img src="docs/odysseus-wordmark.png" alt="Odysseus" width="280">
</p>
2026-06-03 02:42:01 +08:00
2026-06-15 23:24:41 +09:00
<p align="center">
A self-hosted AI workspace for chat, agents, research, documents, email, notes, calendar, and local model workflows.
</p>
2026-06-07 06:16:14 -04:00
2026-06-15 23:24:41 +09:00
<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>
2026-06-01 15:07:41 +09:00
2026-06-15 23:24:41 +09:00
<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>
2026-05-31 23:58:26 +09:00
2026-06-15 23:24:41 +09:00
<p align="center">
<img src="docs/odysseus.jpg" alt="Odysseus interface">
</p>
2026-05-31 23:58:26 +09:00
2026-06-15 23:24:41 +09:00
---
2026-06-01 15:07:41 +09:00
2026-05-31 23:58:26 +09:00
## Quick Start
2026-06-15 23:24:41 +09:00
> `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.
2026-05-31 23:58:26 +09:00
```bash
2026-06-01 10:43:35 +09:00
git clone https://github.com/pewdiepie-archdaemon/odysseus.git
2026-05-31 23:58:26 +09:00
cd odysseus
2026-06-15 23:24:41 +09:00
cp .env.example .env
2026-05-31 23:58:26 +09:00
docker compose up -d --build
```
2026-06-03 10:13:47 +05:30
2026-06-15 23:24:41 +09:00
Open `http://localhost:7000` when the containers are healthy. The first admin password is printed in `docker compose logs odysseus` .
2026-06-03 10:13:47 +05:30
2026-06-15 23:24:41 +09:00
Native installs, GPU notes, Windows/macOS instructions, HTTPS, and configuration live in the [setup guide ](docs/setup.md ).
2026-06-03 10:13:47 +05:30
2026-06-15 23:24:41 +09:00
## Features
2026-05-31 23:58:26 +09:00
2026-06-15 23:24:41 +09:00
- **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.
2026-06-02 05:01:12 +01:00
2026-06-15 23:24:41 +09:00
## Demo
2026-05-31 23:58:26 +09:00
2026-06-15 23:24:41 +09:00
A full hover-to-play tour lives on the landing page: [`docs/index.html` ](docs/index.html ).
2026-05-31 23:58:26 +09:00
## Contributing
refactor(uploads): centralize upload byte-limits in upload_limits.py (#3364) (#3518)
Move every per-route upload byte-limit into src/upload_limits.py as a
validated, env-overridable constant via read_byte_limit_env:
- Add GALLERY_UPLOAD_MAX_BYTES, GALLERY_TRANSFORM_UPLOAD_MAX_BYTES,
MEMORY_IMPORT_MAX_BYTES, PERSONAL_UPLOAD_MAX_BYTES,
EMAIL_COMPOSE_UPLOAD_MAX_BYTES, STT_MAX_AUDIO_BYTES, ICS_MAX_BYTES.
- Routes import their constant instead of defining it locally: replaces 4
raw int(os.getenv(...)) and removes 3 hardcoded literals.
- The 3 previously-hardcoded limits (email compose, STT audio, calendar
ICS) are now env-overridable with the same ODYSSEUS_*_MAX_BYTES naming.
- Defaults unchanged, so behavior is unchanged unless an env var is set;
an invalid value now fails fast with a clear message instead of a bare
int() ValueError.
- Document all env vars in .env.example and the README.
Fixes #3364
2026-06-09 01:24:30 +02:00
2026-06-15 23:24:41 +09:00
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 ).
2026-05-31 23:58:26 +09:00
2026-06-15 23:24:41 +09:00
## Security
Fix NPX MCP server crash (skip if not installed, alternative shape to #242 / #252) (#253)
* Fix NPX MCP server crash by checking install state instead of timing out
When @playwright/mcp (or any future npx-based built-in server) isn't
already cached, npx tries to download and install it on first invoke.
That can take minutes or hang on a fresh install missing Playwright
system deps. The previous code bounded that wait with
asyncio.wait_for(mcp_manager.connect_server(...), timeout=30), but the
cancellation that wait_for fires on timeout propagates into
mcp.client.stdio.stdio_client's internal anyio task group, which
raises:
RuntimeError: Attempted to exit cancel scope in a different task
than it was entered in
The error fires in a sibling background task (Task exception was never
retrieved) so the surrounding try/except BaseException doesn't catch
it, and the orphaned cancel scope cascades cancellations into other
tasks in the same event loop. Running requests start failing and the
process needs a restart.
Fix: detect whether the package is already cached before invoking
connect_server, instead of trying to bound the connect with a timeout.
A new _is_npx_package_cached helper runs:
npx --no-install <pkg> --version
The --no-install flag makes npx fail fast on a cache miss instead of
downloading, so the probe returns in <500ms either way. If the package
isn't cached, we log a warning with the exact command the user can run
to install it, and skip the server. If it is cached, we call
connect_server normally with no wait_for wrapper, so there's no
cancellation that could enter stdio_client's task group.
This removes the entire bug class instead of papering over it. No
asyncio.wait_for around stdio_client, no shielded-task leak, no
shutdown-time RuntimeError. Verified against current versions
(mcp library on Python 3.14, anyio 4.13.0) with the existing
@playwright/mcp@latest cached, and with a deliberately uncached
package spec to exercise the skip path.
* Make first-run setup explicit when NPX MCP package isn't cached
Per @pewdiepie-archdaemon review on #253:
- src/builtin_mcp.py: expand the skip-server warning into a multi-line
block with Reason/Impact/Fix/Notes lines, so the message stands out
in startup logs and clearly tells the user what to run.
- README.md: add 'Built-in MCP servers (optional setup)' subsection
under Configuration, with the install command and a brief note that
it's optional and skipped if not cached.
2026-05-31 22:23:19 -07:00
2026-06-15 23:24:41 +09:00
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 ).
2026-06-15 19:26:47 +08:00
2026-06-01 07:24:52 +02:00
## 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>
2026-05-31 23:58:26 +09:00
## License
2026-06-15 23:24:41 +09:00
AGPL-3.0-or-later -- see [LICENSE ](LICENSE ) and [ACKNOWLEDGMENTS.md ](ACKNOWLEDGMENTS.md ).
