How odysseus is put together
Odysseus is a self-hosted, single-process AI workspace (chat, agents, deep research, documents, email, notes, calendar, image generation) built as a Python FastAPI/Starlette ASGI application served by uvicorn. app.py is a slim orchestrator that wires CORS, gzip, security-header, request-timeout, foreground-activity, and slow-request middleware around a large set of routers under routes/, with business logic in src/ and shared infrastructure (auth, database, session management, middleware, constants) in core/. Persistence is via SQLAlchemy over a relational DB plus a ChromaDB HTTP vector store with fastembed ONNX embeddings for RAG/semantic memory; auth is multi-user bcrypt password hashing with session cookies and bearer API tokens, TOTP 2FA, and owner-scoped data access. It ships MCP servers (email, image-gen, memory, RAG), a companion LAN-pairing bridge, and is deployed via Docker Compose with optional GPU variants and native/desktop build scripts.
Languages
Frameworks
Datastores
Infrastructure
Major components
core (infrastructure)
Shared foundation: auth manager, database/models, session manager, middleware, constants, atomic IO, and exceptions used app-wide.
routes (HTTP API)
FastAPI routers exposing all feature endpoints (chat, auth, email, calendar, documents, research, cookbook, shell, model, memory, tokens, etc.).
src (service layer)
Business logic for LLM interaction, agent loop, deep research, embeddings, memory, CalDAV sync, chat processing, and integrations.
mcp_servers
Built-in MCP (v1 Server API) servers exposing email, image generation, memory, and RAG capabilities to agents.
companion bridge
Additive /api/companion/* layer for LAN client discovery and admin-gated device pairing that mints chat-scoped API tokens.
auth & security surface
Multi-user bcrypt auth, session tokens, TOTP 2FA, API tokens, owner-scoping, admin gating, and security-header/CSP middleware.
deployment & build
Docker Compose stacks, GPU overlays, entrypoint, systemd unit, and Windows/macOS native build/launch scripts.
specs & tests
Per-area specification docs (specs/) and a marker-taxonomy pytest suite (pyproject.toml, tests/) covering security, routes, and services.
A quiet week centered on new project documentation and routine dependency and release housekeeping.
5 weeksWeek of 2026-08-24
Week of 2026-08-24latest
A quiet week centered on new project documentation and routine dependency and release housekeeping.
Week of 2026-08-17
A cleanup week of small bug fixes across the agent, models, and time handling, plus a code reorganization of the task area.
Week of 2026-08-10
A very large week dominated by a sweeping security hardening of how the agent handles approvals and untrusted content, alongside performance gains and settings improvements.
Week of 2026-08-03
A steady week of usability fixes across email, chat, memory, and skills, plus continued reorganization of the code into cleaner sections.
Week of 2026-07-27
A mixed week of email sign-in fixes, model and formatting corrections, and a new configurable limit for the text-to-speech cache.
Over the past several weeks the Odysseus team shifted from a burst of intensive security and reliability hardening—especially around how the AI agent handles user approvals and untrusted content—toward broader polish, code reorganization, and performance work. Recent weeks focused on tidying the codebase into cleaner sub-packages, speeding up page loads, and fixing everyday issues in email, chat, and models. The latest week wound down into documentation and routine maintenance.
Week by week
2026-08-24A quiet week centered on new project documentation and routine dependency and release housekeeping.latest4 changes
Docs
New 'specs' reference guide for the codebase
Added a compact, living map of the system's subsystems to help people and coding assistants find their way around the code.
Chore
Bulk update of automated build tools
Refreshed 11 build-and-test automation components to their latest versions.
Chore
Development version aligned to 1.0.3
Synced the in-progress version number to keep release tracking consistent.
Chore
Updated a development testing dependency
Bumped an internal testing library to a newer release.
2026-08-17A cleanup week of small bug fixes across the agent, models, and time handling, plus a code reorganization of the task area.6 changes
Fix
Smoother handling of approved agent actions
Fixed the agent so it no longer leaves an empty step when replaying an action a user already approved, and lets remaining approved steps continue.
Fix
Cleaner file handling on save errors
Leftover temporary files are now removed when a safe file save fails partway through.
Fix
More readable time zones
The app now shows a named time zone (like 'America/New_York') instead of a raw numeric offset.
Fix
API models shown by default
Corrected the models list so API-based models appear and their selection checkboxes stay in sync.
Fix
Windows recipe runner fix
The step-by-step 'cookbook' runner now correctly activates a local Windows environment.
Refactor
Task code reorganized
Moved task-related code into its own dedicated section for easier maintenance.
2026-08-10A very large week dominated by a sweeping security hardening of how the agent handles approvals and untrusted content, alongside performance gains and settings improvements.6 changes
Fix
Major agent approval and untrusted-content hardening
A long series of fixes tightened how the agent grants, retires, and continues approvals and how it handles content from external sources, closing gaps that could bypass safeguards.
Refactor
Faster page loads
Bundled math and diagram libraries locally and loaded heavy features (like the image editor) only when first needed, plus shared a cached settings fetch.
Fix
Sign-in cookie security tied to connection type
The session cookie's secure flag is now set based on whether the request is over HTTPS, improving login safety.
Refactor
Registry-backed settings navigation
Reworked settings with a searchable, registry-driven navigation and finder.
Feature
Default/Local owner contract for accounts
Defined clearer ownership rules for default and local accounts in the sign-in system.
Fix
Various chat, search, and integration fixes
Preserved failed link previews in context, improved provider detection, fixed companion pairing, and corrected several display and data issues.
2026-08-03A steady week of usability fixes across email, chat, memory, and skills, plus continued reorganization of the code into cleaner sections.6 changes
Fix
Email summaries routed through a shared component
Email summaries now use one common language-model connector for consistency.
Fix
More reliable Add Memory form
The memory form got a proper submit button and dependable Enter-key handling.
Fix
Chat editing and typing fixes
Stopped the Up arrow from erasing an unsent multi-line message and fixed edit-box formatting that dropped code blocks.
Fix
Safer memory storage
An unreadable memory store is no longer accidentally overwritten with an empty one.
Fix
Tighter integration security
Locked an external API call to a pre-validated address to guard against a common network attack.
Refactor
Document, webhook, and vault code reorganized
Moved several feature areas into their own dedicated sections for cleaner structure.
2026-07-27A mixed week of email sign-in fixes, model and formatting corrections, and a new configurable limit for the text-to-speech cache.6 changes
Feature
Configurable text-to-speech cache limit
Added a setting to cap the size of the speech-audio cache with automatic cleanup when it fills up.
Fix
Email OAuth sign-in improvements
Fixed the post-sign-in flow to open settings and preserve secure email connection settings.
Fix
Correct handling of newer model IDs
Adjusted settings for certain Opus model identifiers so requests are formed correctly.
Fix
More reliable text formatting
Preserved special characters and code blocks when rendering formatted text.
Fix
Skills reliability fixes
Updated skill timestamp handling and used a lighter model for skill tests.
Chore
Tests for speech cache cleanup
Added tests confirming the cache handles file-removal errors gracefully.
Dependencies and code review
Dependency advisories
Security Watch
No known advisories across 1 scanned dependencies.
No known advisories in the scanned dependencies.
Code review
No concrete code-level issues confirmed.
Get this report every week for your repos.
GitZoid learns each repo, reports what changed, and flags what needs attention. One flat price for the whole team.
$19 a month, flat · First 10 outputs free · No card required