Личный и семейный 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_v4 и отправляет голосовым без скрытых повторов, а при сбое озвучки отвечает текстом. |
| Workspaces | Изолированные personal, family и group файловые области, attachment persistence, безопасная отправка файлов. |
| 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 делегирует большие задачи подагенту 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 одной командой.
- Напоминания: разовые, ежедневные, еженедельные; личные и семейные. Напоминание может прийти с кнопками («✅ Оплатил / ⏰ Через час»): нажатие уходит агенту, и он отмечает или переносит дело.
- Агентные сценарии по расписанию — не просто текст в срок, а полноценный запуск с инструментами («каждое утро собери погоду, календарь и почту», «в пятницу — сводка по портфелю»).
- Пробуждения в разговоре: агент сам ставит себе проверку по текущей задаче («скажу, когда привезут») и продолжает её со всей историей чата. Монитор — такое пробуждение со скриптом проверки: скрипт без модели раз в несколько минут смотрит, не случилось ли событие, и будит агента только тогда.
- Часовой пояс и тихие часы: ночью не разбудит.
- Для внешних групп — отчёты по расписанию, которые владелец настраивает в личном чате.
- На вопрос с короткими вариантами («Оформляем?») агент ставит кнопки прямо в своём сообщении, под его текстом: зелёную для «да», красную для отмены, синюю для альтернативы, с эмодзи. Нажатие уходит агенту как ваш ответ. Кнопки показывают клиенты Telegram с августа 2026 года.
- Нажатие отмечается сразу, даже если агент ещё занят: на месте кнопок появляется «Выбрано: …», а ответ агента приходит своим чередом. Если вы пишете что-то своё, кнопки сменяются на «Ничего не выбрано». В семейной группе нажать может только тот, кому агент отвечал.
- Нажатие — это ответ, а не подтверждение: серьёзные действия по-прежнему подтверждаются отдельной карточкой. Во внешних группах кнопок нет.
- Голосовые и видеосообщения расшифровываются через Groq Whisper до основного хода агента: в личке и семейной группе — все, во внешней группе — только обращённые к агенту.
- Место, геопозицию, контакт, опрос, кубик, список дел, стикер, GIF, видео и пересылку агент получает описанием от сервера; стикер, GIF и видео он может рассмотреть по кадру-превью.
- Агент сам отправляет в чат карточку места или точку на карте и запускает опрос Telegram.
- По просьбе «ответь голосом» агент присылает голосовое сообщение, озвученное через 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; по явной просьбе root-agent отвечает голосовым через ElevenLabs. |
| Семейная группа | Только family |
/workspace/family |
Trusted sandbox и family tools environment; по явной просьбе root-agent отвечает голосовым через ElevenLabs. |
| Внешняя группа | Только group |
/workspace/group |
Без Bash, произвольного сетевого доступа и persistent credentials; web_fetch и send_voice_message доступны только через отдельные owner grants; безопасные file tools и импорт присланного в Telegram файла любого формата в папку группы. |
| Native child | Та же проверенная identity и scopes, что у parent turn | Тот же разрешённый workspace и sandbox | Тот же trust-zone surface, кроме root-owned remember и send_voice_message; отдельные history и state. |
1. Поставить на сервер. Нужен GNU/Linux x86_64 (glibc) с systemd, Docker Engine + Compose v2, jq, curl и flock (пакет util-linux), свободный порт 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. После нажатия «Обновить» не позже чем
через минуту сервер ставит её сам: снимает резервную копию, заменяет контейнеры, проверяет, что бот
жив, и пишет итог в чат. Скрипт обновления едет внутри каждого релиза и обновляет себя вместе с ним,
так что ручных шагов на сервере нет. Пока идёт обновление, osinara restart и osinara config
не запускаются и просят повторить позже. Журнал обновлений: journalctl -u osinara-deploy.service.
Сама программа osinara остаётся версии установки.
npm ci
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 · собственное ядро агента на AI SDK 7.0.60 · 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. |
