Личный и семейный Telegram-агент: помнит контекст, ведёт дела, работает с файлами и сервисами — и держит строгие границы между личным, семейным и групповым.
Osinara — self-hosted агент, который живёт в Telegram и работает как личный ассистент одной семьи. Он говорит по-русски, понимает голосовые, помнит договорённости между сессиями, сам напоминает о делах и умеет доводить задачи до результата через инструменты: документы, Google Workspace, браузер, брокерский счёт, файлы, sandbox.
Ключевое отличие от обычного бота: права не живут в промте. Кто ты, из какой ты семьи, что тебе доступно в этом чате — определяется проверенным Telegram-апдейтом и базой, а не текстом от модели. Личная память никогда не попадает в групповой чат, внешняя группа никогда не получает доступ к личным данным и сервисам.
Рассчитан на: одну семью на своём сервере. Один владелец, приглашённые участники, закрытые семейные группы и отдельно — внешние группы (рабочие, дружеские), где агент работает в урезанном режиме.
| Блок | Что умеет |
|---|---|
| Telegram | Durable webhook ingress, быстрый ACK Telegram, FIFO-drain по chat/topic, обычные и rich replies, HITL callbacks с ограниченным окном подтверждения. |
| Семья и группы | Bootstrap владельца, приглашения, подтверждение участников, owner-only операции, семейные и внешние группы. |
| Память | Root-agent source-backed writes, semantic integrity для изменений, versioned mutations, soft delete, atomic memory threads, локальный hybrid retrieval, экспорт и отдельные scopes. |
| Расписания | Напоминания и автономные agent schedules: личные и семейные сценарии, а также owner-approved отчёты во внешние группы с отдельной fresh session, минимальным capability allowlist и bounded snapshot истории. |
| Голос | Groq Whisper transcription перед основным agent turn с повторной проверкой authorization; по явной просьбе root-agent озвучивает ответ через ElevenLabs eleven_v3 и отправляет голосовым без скрытых повторов, а при сбое озвучки отвечает текстом. |
| Workspaces | Изолированные personal, family и group файловые области, attachment persistence, безопасная отправка файлов. |
| Изображения | Root-agent создаёт одно WebP через gpt-image-2, сохраняет его в authorized workspace и доставляет в Telegram без скрытых повторов; внешней группе capability выдаёт владелец из личного чата. |
| Google Workspace | Native gws skills для Gmail, Calendar, Drive, Docs, Sheets и People через workspace-bound OAuth credentials. |
| Sandbox | Долгоживущие Docker sandbox sessions с scoped mounts, isolated tools volume, egress proxy и fail-closed policy. |
| Оркестрация | В trusted private/family режимах root-agent делегирует большие задачи нативному Eve agent со свежим контекстом и теми же разрешёнными tools, skills, connections, sandbox и workspace; во внешних группах child delegation запрещена. |
| Production | Immutable GitHub releases, GHCR digest images, Telegram approval перед deploy, systemd timer на сервере. |
- Помнит факты и договорённости; каждая запись привязана к источнику — можно спросить «откуда ты это взяла».
- Треды — незакрытые сюжеты (поиск квартиры, ремонт, лечение): агент сам поднимает их, когда тема возвращается.
- Гибридный поиск по памяти (pgvector + локальные эмбеддинги
multilingual-e5-small), без отправки памяти во внешние сервисы. - Конфликты («раньше говорил одно, теперь другое») выносятся на ваше решение, а не переписываются молча.
- Отдельные области:
personal,family,group. Экспорт всей личной памяти в JSON + Markdown одной командой.
- Напоминания: разовые, ежедневные, еженедельные; личные и семейные.
- Агентные сценарии по расписанию — не просто текст в срок, а полноценный запуск с инструментами («каждое утро собери погоду, календарь и почту», «в пятницу — сводка по портфелю»).
- Часовой пояс и тихие часы: ночью не разбудит.
- Для внешних групп — отчёты по расписанию, которые владелец настраивает в личном чате.
- Голосовые сообщения расшифровываются через Groq Whisper до основного хода агента.
- По просьбе «ответь голосом» агент присылает голосовое сообщение, озвученное через ElevenLabs.
- Присланные файлы и фото сохраняются в рабочую область чата и доступны инструментам.
- Агент может прислать файл из рабочей области обратно в Telegram и посмотреть картинку.
- Изолированные области:
personal,family,group— файлы одной области не видны в другой.
pdf,docx,xlsx— чтение, правка, сборка: договор, таблица, отчёт, презентационный документ.- Работа идёт в sandbox-контейнере, результат приходит файлом в чат.
- Нативный
gws-доступ к Gmail, Calendar, Drive, Docs, Sheets, People. - OAuth-подключение владельца; токены шифруются и не попадают в текст модели.
- Пример: «что у меня в календаре на среду», «найди письмо от подрядчика и вытащи сумму».
- Портфель, позиции, свободные деньги, котировки, операции, дивиденды, комиссии, доходность.
- Сделки — только по явной команде. Это доступ к данным и расчётам, не инвестиционные рекомендации.
agent-browser— автоматизация браузера: открыть, заполнить, нажать, забрать данные.find-docs— актуальная документация библиотек и API вместо памяти модели.- Во внешних группах веб-доступ идёт только через контролируемую обёртку и отдельное разрешение.
- Bootstrap владельца по одноразовому коду при установке.
- Приглашение участника: владелец создаёт одноразовую ссылку → человек переходит → владелец подтверждает.
- Административные операции возможны только в личном чате владельца — и перепроверяются в базе перед выполнением.
- Семейная группа (
family_private): только подтверждённые участники семьи, доступна семейная память. - Внешняя группа (
external): своя изолированная область, без личных и семейных данных, без Bash и произвольной сети. - Режимы реакции: только по обращению, на все сообщения, либо только на сообщения владельца.
- Для внешней группы владелец точечно выдаёт allowlist инструментов и skills; смена типа группы пересоздаёт зону доверия и удаляет данные прежней области.
- Пожелания к стилю общения сохраняются на чат: короче, без смайлов, другой язык, свой формат.
- Действия с последствиями подтверждаются кнопкой в Telegram (HITL), включая деплой обновлений.
- Ручная ротация контекста, когда тема сменилась и старый диалог мешает.
- Ответ может прийти не одним сообщением: сначала по делу, а через пару секунд отдельная мысль вдогонку, как пишут люди. Реплаем помечено только первое сообщение.
- Пока идёт долгая работа, агент присылает короткую отбивку о том, что делает прямо сейчас, вместо молчания до готового результата.
- Вместо ответа на короткое «спасибо» или упоминание без вопроса агент ставит реакцию. Набор реакций берётся из настроек самого чата: сузили список или отключили реакции, агент это учтёт.
| Где | Память | Файлы | Инструменты |
|---|---|---|---|
| Личный чат | personal и family |
/workspace/personal, /workspace/family |
Полный trusted sandbox и personal tools environment; при активной Codex-подписке root-agent может создавать изображения; по явной просьбе root-agent отвечает голосовым через ElevenLabs. |
| Семейная группа | Только family |
/workspace/family |
Trusted sandbox и family tools environment; при активной Codex-подписке root-agent может создавать изображения; по явной просьбе root-agent отвечает голосовым через ElevenLabs. |
| Внешняя группа | Только group |
/workspace/group |
Без Bash, произвольного сетевого доступа и persistent credentials; web_fetch, generate_image и send_voice_message доступны только через отдельные owner grants, причём generate_image предлагается владельцу лишь при активном provider codex-subscription; безопасные file tools и настраиваемый импорт UTF-8 TXT/MD/JSON/CSV/TSV/HTML/XML/YAML/YML из Telegram. |
| Native child | Та же проверенная identity и scopes, что у parent turn | Тот же разрешённый workspace и sandbox | Тот же trust-zone surface, кроме root-owned remember, generate_image и send_voice_message; отдельные history и state. |
1. Поставить на сервер. Нужен GNU/Linux x86_64 (glibc), Docker Engine + Compose v2, свободный порт 8082; если Osinara ставит свой Traefik, ещё и свободные 80 и 443.
Скачайте install.sh из последнего релиза и передайте ему URL CLI-ассета и его SHA-256 из того же релиза:
sudo ./install.sh \
https://github.com/nyxandro/osinara/releases/download/vX.Y.Z/osinara-linux-x64 \
<SHA-256 из osinara-linux-x64.sha256>Установщик спросит домен (или предложит sslip.io) и способ публикации HTTPS: поставить свой Traefik
или использовать уже работающий на сервере прокси. Затем проверит Telegram-бота и модель, поднимет
digest-pinned образы, HTTPS и webhook, и выдаст ссылку владельца.
2. Стать владельцем. Перейдите по ссылке из установщика и напишите боту. Если ссылка не появилась —
sudo osinara owner-bootstrap выдаст новый код на 15 минут (прежний отзывается).
3. Позвать своих. В личном чате: «пригласи Анну» → отправьте ссылку → после её перехода подтвердите кандидата.
4. Подключить группы. Добавьте бота в группу и в личном чате владельца скажите, чем эта группа является: семейной или внешней. Для внешней сразу задайте режим реакции и что ей разрешено.
5. Дальше — обычным языком. «Напомни в четверг про садик», «расшифруй голосовое и вынеси задачи», «собери из этих чеков таблицу», «что по портфелю», «каждое утро в 8 присылай сводку», «запомни, что мы выбрали клинику».
Обслуживание:
osinara status # состояние сервисов
osinara doctor # диагностика установки
osinara logs # логи
osinara restart # перезапуск
osinara config # конфигурация модели и провайдераОбновления агент сам предлагает в Telegram; деплой начинается только после подтверждения владельца.
npm ci # postinstall применяет локальные Eve-патчи
cp .env.example .env # заполнить обязательные секреты
docker compose up --build # edge: http://localhost:8080Полный список переменных — в .env.example: только секреты, доступы и привязки
к инфраструктуре. Поведение агента (таймауты, лимиты, расписания, настройки модели) живёт в
конфигурации в репозитории, а не в окружении. Отсутствующий обязательный секрет — ошибка на старте,
а не подставленное значение по умолчанию. Блок Google Workspace нужен только при включённой интеграции.
Проверки:
npm run typecheck && npm test && npm run build
# production-equivalent прогон
docker compose -f compose.test.yaml up --build --abort-on-container-exit --exit-code-from testsМиграции запускаются только внутри backend/test-контейнера: npm run migrate.
TypeScript на Node 24 · Eve 0.40.0 · PostgreSQL 17 + pgvector ·
Docker Compose · Groq Whisper · локальные эмбеддинги E5 · Telegram как единственный канал.
Архитектурные заметки и рантбуки — в docs/, правила разработки — в AGENTS.md,
деплой — в docs/production-deployment.md.
- Авторизация принадлежит приложению: identity, семья, роль и область доступа никогда не берутся из текста модели.
- Память, документы, сайты и результаты инструментов — это данные, а не инструкции для агента.
- Отсутствие обязательного конфига — быстрая ошибка со стабильным кодом, а не догадка со значением по умолчанию.
- Внешние группы не получают личную и семейную память, учётные данные, Bash и произвольную сеть.
- Production-образы собирает только CI из канонического
main; деплой требует подтверждения владельца и точной проверки манифеста релиза.
Highlighted skill groups:
| Skill group | Examples |
|---|---|
| Google Workspace | gws-gmail, gws-calendar, gws-drive, gws-docs, gws-sheets, gws-people. |
| Documents | pdf, docx, xlsx. |
| Browser and research | agent-browser, find-docs. |
| Personalization | behavior-preferences. |
| Tone, opt-in | pohuy — режим ответов с матом, грузится только по явной просьбе. |
| Image generation | Dynamic imagegen доступен root-agent только вместе с активным subscription-backed generate_image; без provider codex-subscription ни tool, ни skill не существуют и не выдаются. |
