Odysseus — селф-хостед ИИ-рабочее место с агентами, документами, почтой и локальными моделями

Odysseus — селф-хостед ИИ-рабочее место. Проще говоря, это веб-приложение, которое вы ставите на свой сервер и открываете в браузере. На момент, когда я смотрел проект, у него было около 89,3 тысячи звёзд и 1,1 тысячи форков на GitHub. Лицензия — AGPL-3.0-or-later, основной язык — Python, но в репозитории есть JavaScript, CSS и даже Swift: на macOS из него собирают обычное приложение с иконкой в меню.

Логика проекта простая. Если вы уже пользовались облачным чатом с ИИ, то знаете главную претензию: переписка и файлы уходят к чужой компании, а модель ничего не помнит между сессиями. Odysseus отвечает на это иначе. Это одно веб-приложение, которое живёт на вашем железе. Внутри него — агенты с доступом к файлам и командной строке, поиск по вебу, редактор документов, почтовый ящик, заметки и календарь. Приватные данные никуда не уходят, если вы не отправляете их наружу сами.

Название выбрано не случайно: Одиссей — тот, кто долго плыл и вернулся домой. Авторы прямо пишут в дорожной карте, что проект ещё в пути и очень нуждается в помощи. Это честный признак ранней стадии, о нём стоит помнить дальше.

Что умеет

Возможности перечислены в README без лишних слов. Разложу их по смыслу, потому что список получился неоднородный.

Отдельно стоит сказать про MCP. Это общий стандарт, по которому к агенту подключают внешние инструменты. Через него к агентам Odysseus можно присоединить любые сторонние MCP-серверы, а не только те, о которых знают авторы проекта.

Быстрый старт через Docker

Рекомендуемый путь — Docker Compose. Он поднимает не только само приложение, но и всё, что нужно для работы.

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

Когда контейнеры поднимутся, откройте http://localhost:7000. Пароль администратора печатается в логах при первом запуске:

docker compose logs odysseus

Логин по умолчанию — admin. Его можно задать заранее через ODYSSEUS_ADMIN_USER и ODYSSEUS_ADMIN_PASSWORD. Входите первый раз с временным паролем, а новый задайте в настройках приложения.

Отдельная деталь, о которой стоит знать заранее: compose-файл сначала пытается скачать готовый образ с GitHub Container Registry, и только если это не удалось — собирает его локально. Благодаря этому те же самые файлы работают на машине, где нет инструментов для сборки. Например, на сервере с Portainer или Coolify.

Какие бывают образы

Сборки публикуются в реестре контейнеров проекта при каждом пуше в main и dev. Теги устроены так:

Для рабочего сервера берите третий вариант из таблицы — :1.0.2-7c8070f и подобные. Первые два тега подвижные, и после пуша ваш сервер молча поменяет версию.

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

Кстати, в самом репозитории две ветки. Ветка dev — основная, и в неё попадают последние изменения, но она может быть нестабильной. Ветка main — более стабильная, и именно из неё собираются образы с тегами :latest и :X.Y.Z.

Установка без Docker

Если контейнеры не подходят, есть нативный вариант. Нужен Python 3.11 или новее. Для Cookbook дополнительно требуется tmux: он держит фоновые загрузки моделей, которые должны пережить закрытие терминала.

git clone https://github.com/odysseus-dev/odysseus.git
cd odysseus
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
python setup.py
python -m uvicorn app:app --host 127.0.0.1 --port 7000

Само приложение весит мало. Тяжёлая часть — только локальный запуск моделей, и там всё зависит от модели, среды исполнения, видеокарты и её памяти. Если железа не хватает, подключитесь к внешней модели через API.

На macOS

Для Apple Silicon есть отдельный скрипт:

git clone https://github.com/odysseus-dev/odysseus.git
cd odysseus
./start-macos.sh

Приложение поднимается на http://127.0.0.1:7860. Есть важное ограничение: Docker на macOS не получает доступ к GPU через Metal. Поэтому Cookbook в контейнере считает только на процессоре. Если нужна видеокарта, запускайте Odysseus нативно — тогда GPU используется по-настоящему.

Чтобы открыть доступ с телефона через доверенную сеть или Tailscale, привяжите все интерфейсы и откройте адрес в браузере телефона:

ODYSSEUS_HOST=0.0.0.0 ./start-macos.sh
# затем открыть http://<tailscale-ip>:7860

Чтобы собрать обычное приложение со значком в меню, есть ./build-macos-app.sh. Под Windows в репозитории лежат build-windows-portable.ps1, launch-windows.ps1 и update_windows.bat.

Cookbook — управление локальными моделями

Cookbook — самая интересная часть проекта и одновременно та, где авторы честно признают проблемы. Это встроенный менеджер локальных моделей. Он смотрит на ваш процессор, видеокарту и объём памяти. Потом предлагает подходящие модели, скачивает их и запускает. Запуск делают программы-движки: vLLM, SGLang и llama-cpp-python. Каждая из них умеет подать модели по-своему, и выбор влияет на скорость ответа.

Загруженные вещи сохраняются между пересозданиями контейнера: в Docker это каталоги ./data/huggingface и ./data/local. Там же лежат Python-пакеты, установленные Cookbook, — иначе пересоздание контейнера тихо удаляло бы установленные движки.

GPU в Docker подключается дополнительными compose-файлами: docker/gpu.nvidia.yml и docker/gpu.amd.yml. Включаются через переменную COMPOSE_FILE:

COMPOSE_FILE=docker-compose.yml:docker/gpu.nvidia.yml

Причём Cookbook видит только те видеокарты, которые Docker действительно пробросил в контейнер. Если проброс не настроен, вы увидите встроенную графику или процессор вместо той карты, которую рассчитывали. Для диагностики есть скрипт scripts/check-docker-gpu.sh: он проверяет проброс и по умолчанию ничего не меняет на машине.

Отдельный сценарий — удалённые серверы с моделями. В настройках Cookbook → Settings → Servers приложение генерирует SSH-ключ, а его публичную часть нужно добавить в ~/.ssh/authorized_keys на удалённой машине. По сути это самый спокойный способ считать GPU, не выделяя его на основном сервере.

Какие сервисы поднимаются рядом

Compose поднимает четыре вещи:

• Odysseus — само приложение, порт 7000;
• ChromaDB — векторная база для поиска по смыслу (по умолчанию порт 8100);
• SearXNG — свой поисковик по вебу, чтобы не отправлять запросы наружу;
• ntfy — доставка уведомлений.

По умолчанию все порты слушают только 127.0.0.1. Доступ из локальной сети появляется только если вы это явно разрешили.

ChromaDB и ntfy нужны не всем. ChromaDB отвечает за поиск по смыслу. ntfy удобен, чтобы получать уведомления на телефон, не поднимая свой сервер уведомлений.

Настройка через .env

Значения по умолчанию работают сразу. Файл .env нужен в основном для параметров развёртывания, а модели, поиск и почту вы настраиваете уже в интерфейсе.

Часто встречающиеся переменные:

Провайдеры моделей, которые проверяются и настраиваются в приложении, включают Anthropic, Gemini, Groq, xAI, OpenRouter, OpenAI и DeepSeek. То есть работать можно и с облачными моделями — но тогда история чата уходит к провайдеру.

Безопасность

Это приложение с доступом к вашим файлам и командной строке, поэтому пара правил обязательна.

Держите AUTH_ENABLED=true на любом сервере, доступном по сети. Держите LOCALHOST_BYPASS=false везде, кроме локальной разработки. Не публикуйте наружу «сырые» порты моделей и служебных сервисов. Если ставите на macOS и вешаете на 0.0.0.0, отдавайте предпочтение Tailscale или VPN, а не прямому выходу в интернет.

Подробности развёртывания и модель угроз описаны в гайде по настройке, а отдельный документ THREAT_MODEL.md перечисляет, что авторы считают границей доверия. Лицензия — AGPL-3.0-or-later, текст лежит в LICENSE, список сторонних компонентов — в ACKNOWLEDGMENTS.md. Для своего кода на этой основе ожидайте того же требования: публикуйте изменения под открытой лицензией.

Телефон как клиент

В репозитории есть companion — небольшой слой, который позволяет телефону в той же сети найти сервер и привязаться к нему. Он намеренно тонкий: логика работы с моделями не дублируется, телефон лишь видит возможности сервера и свои собственные модели. Через этот слой телефон может дешёво проверить связь с сервером, узнать о его возможностях и получить список моделей. Привязка выдаёт одноразовый токен. Токен выдаётся только методом POST, поэтому получить его одной лишь ссылкой в браузере нельзя.

Что признают сами разработчики

Дорожная карта честная и местами резкая. Вот несколько пунктов, которые стоит знать до установки.

Cookbook — самое хрупкое место. Там идёт работа над тем, чтобы он одинаково работал на разных машинах, видеокартах, драйверах, оболочках и Python-окружениях. Поддержка SGLang по платформам тоже ещё в процессе. Ошибки загрузок и установок пока должны показывать в интерфейсе понятный лог — авторы перечисляют это как задачу.

Агентный режим перегружает контекст у небольших локальных моделей. Схемы инструментов, навыки, память и документы съедают окно в 4–16 тысяч токенов до того, как начнётся сама задача. Нужны более тонкие подсказки и меньшие наборы инструментов по умолчанию.

Отдельно идёт аудит на подмену инструкций через содержимое. Навыки, заметки, документы, загруженные страницы и память считаются недоверенными данными, и авторы просят проверять, не выполняет ли модель команды, найденные внутри этих данных.

Ещё в планах спекулятивное декодирование (speculative decoding). Смысл простой: маленькая модель-черновик с тем же токенизатором заранее придумывает продолжение, а большая проверяет её догадку. Ранние тесты с Qwen3-0.6B рядом с Qwen3-8B заметно сокращали время ответа. И есть аудит производительности почты: на IMAP/SMTP с большой задержкой письма открываются медленно.

Если хочется поучаствовать, в CONTRIBUTING.md ждут тестировщиков чистой установки, тех, кто чинит настройку провайдеров, и тех, кому есть что сказать про фронтенд. Интерактивный тур по интерфейсу лежит на демо-странице проекта.

Кому это подойдёт

Odysseus — не замена терминальному кодинг-агенту, а место, где агенты живут вместе с остальной работой. Он закрывает сценарий «своя машина, своя история чатов, своя почта и свои модели», и закрывает его целиком, а не по частям.

Подойдёт, если вы уже работаете с локальными моделями через Ollama или vLLM и хотите собрать вокруг них одно приложение. Подойдёт, если вам не нравится отправлять рабочие переписки в чужой облачный сервис. Не подойдёт, если вам нужно, чтобы всё работало с первого запуска без настройки: порт, GPU, драйверы и Cookbook — здесь всё это придётся трогать руками.