Iva Personal Assistant
A self-hosted Telegram assistant that turns daily messages into durable memory and actionable work.
- Source repo
- smixs/iva-agent
- Stars
- ★ 285
- Last updated
- 3d ago
- License
- MIT
- Primary language
- TypeScript
- FA score
- 85/100 · Good
At a glance
- How it runs
- Works with
- Universal · cross-platformChatGPT · Codex
- Cost
- Free software; you pay for model usage
- Setup effort
- Medium · a few setup steps
- You'll need
- Typical use
- A business owner records client agreements and preferences as durable cards, then asks months later what was promised and how to follow up.
- Not a fit if
- Individuals unwilling to maintain a Linux host, systemd services and upgrades
- Anyone automating a personal Telegram account: the userbot violates Telegram's ToS and risks a ban
- Source review
- 85/100 · Good
What does this agent do, and when should you use it?
Iva is a self-hosted Telegram assistant that receives text, voice notes, photos, forwarded material, and decisions through long polling, so it does not require a public HTTPS endpoint, domain, or webhook. It writes conversations into an Obsidian-compatible Markdown vault and builds layered memory from daily, weekly, monthly, and yearly summaries, CORE.md, and typed cards. The deployment runs as two systemd user services, two watchdog timers, and five in-process eve schedules, with Node.js 24's built-in SQLite powering the search index. It can use web search, Google Workspace, reminders, filesystem operations, custom skills, and MCP servers. The vault and credentials stay on the user's server, while model inference and transcription remain cloud services chosen and paid for by the operator. It best fits individuals or small teams that want Telegram as their operational interface and are willing to maintain a Linux installation.
The Telegram bridge long-polls for messages and appends each day's user messages and Iva responses verbatim to daily/YYYY-MM-DD.md. Deepgram nova-3 can transcribe voice, audio, and video notes, while the selected provider's vision model describes photos; several classes of forwarded or retrieved content pass through a prompt-injection check. At 04:00, the nightly rollup folds the journal into daily, weekly, monthly, and yearly summaries and updates typed contacts, projects, decisions, ideas, and notes; a CORE.md file limited to 1,200 characters is included in every prompt. Retrieval combines BM25 with link-graph reranking by default, with an optional vector mode. Iva can add, list, and remove one-off or repeating reminders; search through Tavily, Exa, Parallel, or Brave; and operate Gmail, Calendar, Drive, Sheets, Docs, and Tasks through the gws CLI. Skills can add procedures, MCP servers can add integrations, and the opt-in beta userbot can read, search, or send through a personal Telegram account. Outbound content passes through an Outbox secret-redaction gate.
- A business owner records client agreements and preferences as durable cards, then asks months later what was promised and how to follow up.
- An executive on the road sends a five-minute voice note and receives a task list, draft email, and meeting card.
- A Google Workspace user asks from Telegram to turn a price list into a quote, adjust the discount, and produce a shareable Google Doc.
- A knowledge worker captures photos, forwarded articles, decisions, and daily thoughts in an inspectable Obsidian-compatible vault, then retrieves them by meaning.
- A heavy Telegram user opts into the beta userbot to summarize busy groups, search account history, and cautiously send replies after accepting the account-ban risk.
How do you install or deploy this agent?
Use an Ubuntu or Debian machine and install as a normal user, not root. Obtain a Telegram bot token from @BotFather, then run:
curl -fsSL https://raw.githubusercontent.com/smixs/iva-agent/main/install.sh | bashComplete the wizard with the bot token and one supported model provider: OpenCode Go, Ollama Cloud, OpenRouter, or OpenAI through a ChatGPT subscription. Add a Deepgram key if voice transcription is required. Send the bot a message; the wizard extracts the Telegram ID from it, completes setup, and confirms in chat that Iva is live. On a brand-new VPS where only root access exists, first run:
bash <(curl -fsSL https://raw.githubusercontent.com/smixs/iva-agent/main/bootstrap.sh)This creates a sudo user with lingering enabled, updates the system, and enables a firewall, fail2ban, and SSH hardening. Log in as that user and run the main installer. To install from source instead, run:
git clone https://github.com/smixs/iva-agent.git ~/iva
cd ~/iva && bash install.shHow do you use this agent?
After installation, send the bot a text or voice message and inspect daily/ in the vault to see the dated verbatim record. Next, provide a durable fact such as “Marina at Acme wants the revised quote by Friday — she never picks up the phone.” and ask “how should I follow up with Marina?” to test card creation and memory retrieval. Send a photo or forward a long post to request a description or summary. Use /menu for model, rich-reply, voice, and maintenance settings, and /usage for token accounting. Google Workspace access is configured through the installed gws CLI and its guided in-chat key setup. Add procedures through skill files and place MCP credentials in .env; enable the personal-account userbot only deliberately, with read-only mode available through an environment switch.
What are this agent's strengths and limitations?
- Memory is stored in user-owned plain Markdown, including verbatim daily logs, hierarchical summaries, CORE.md, and typed cards that can be inspected or opened in Obsidian.
- Long polling removes the need for a domain, public HTTPS endpoint, or Telegram webhook, and the documented installer offers a one-command deployment path.
- Four model-provider choices, four web-search providers, Google Workspace, skills, and MCP support reduce dependence on one model vendor.
- Reminder delivery uses an atomic state transition and an independent agent check, scheduled runs leave diagnostic facts, and versioned updates support probing and rollback.
- External-input screening, Outbox secret redaction, and a fail-closed user allowlist provide concrete security controls rather than relying only on prompt instructions.
- Adopters must operate an Ubuntu or Debian host, Node.js 24, systemd services, credentials, environment configuration, and upgrades; this is not a maintenance-free hosted assistant.
- The privacy boundary is not fully local: model inference and Deepgram transcription use cloud services selected and funded by the operator.
- Input screening has documented gaps: document bodies, userbot-read chats, and agent-browser output are unscreened, while media-caption warnings are not yet carried to the model.
- Personal-account automation is a rough beta and violates Telegram's terms; sending can lead to rate limits or an account ban despite the enforced pacing and circuit breaker.
- The stated roughly $14–15 monthly total applies to a particular OpenCode Go and VPS setup; usage-based models and optional services can change the cost.
How does this agent compare with similar options?
Key facts side by side with the most closely related agents.
| Agent | Source review | Form / cost | Stars | Updated | Language | Full support on |
|---|---|---|---|---|---|---|
| Iva Personal Assistant This agent | 85 · Good | Chat botFree + model costs | ★ 285 | 3d ago | TypeScript | ChatGPT · Codex |
| Sapphire Blue AI | 53 · Major gaps | Web appFree + model costs | ★ 328 | 1d ago | Python | OpenAI API · Claude API |
| MIRA OS | 51 · Major gaps | Self-hosted serviceFreemium | ★ 482 | 4d ago | Python | Claude API |
| Octop Self-Hosted Assistant | 67 · Some gaps | CLIFree + model costs | ★ 12k | 1d ago | Python | Codex · Claude Code · OpenAI API |
How does FollowAgents rate this agent?
Why each dimension lost points
The evidence clearly documents normal-user installation, a fail-closed Telegram allowlist, a userbot read-only switch, owner-only terminal plugin installation, inbound injection screening, outbound secret redaction, and data flows to cloud models, transcription services, and an optional private GitHub mirror; data-flow transparency therefore earns full credit. Updates use build, probe, switch, and rollback, while destructive CRM-dedup tests demonstrate backup-before-replacement, fault recovery, and symlink-escape resistance, providing strong rollback evidence. Deductions apply because the agent shell inherits the full process environment and runs with the installer's user privileges, while document bodies, userbot chats, and browser output remain unscreened. Some userbot writes are governed only by prompt instructions, and no universal per-action confirmation mechanism is shown. Dependencies are versioned and the repository claims audit remediation and supplies security-test scripts, but the supplied evidence contains no lockfile, provenance verification, or comprehensive ongoing vulnerability process. Attribution identifies smixs and project lineage, with private reporting channels, but publisher identity remains unknown.
The README, security policy, package metadata, and tests are internally consistent about the release, runtime, security boundaries, and recovery behavior. Seeded property tests, fault injection, and extensive regression cases further support self-consistency. Failure handling is unusually concrete: tool-schema fallback, reminder fallback delivery, diagnostic bundles, explicit configuration errors, and interrupted-update recovery justify full marks for failure messages. Dependency availability is supported only statically through declared Node 24, eve, cloud services, and installation requirements; the evidence does not establish a comprehensive unified fallback for outages across Telegram, model providers, Deepgram, search, and Google services.
The material identifies business owners, specialists, executives, and everyday users and supplies concrete voice, CRM, document, reminder, and search scenarios. Multiple model and search providers, optional vectors, skills, MCP, plugins, read-only operation, and custom rules offer substantial adaptation. The security policy thoroughly states sanitizer blind spots, plugin trust boundaries, cloud-API exposure, and userbot risks, earning full capability-boundary credit. Trigger precision is reduced because natural-language interpretation, skill prompts, and configuration modes govern important behavior, and userbot joins, invites, contact imports, and reactions are not wrapped by the server guardrail. Environment fit is primarily limited to Ubuntu/Debian, systemd, and Node 24 rather than broad cross-platform support.
The README has clear navigation and dedicated architecture, feature, installation, cost, documentation, release-history, and license sections, alongside English/Russian documentation, first-minute examples, FAQ, troubleshooting, and numerous use cases. Package naming, CLI naming, versions, and release notes are consistent, and the complete MIT text is supplied. Limitations—including beta userbot ban risk, sanitizer gaps, latest-release-only support, and cloud data exposure—are candidly documented, supporting full marks across most convention criteria. Maintenance responsibility receives two points because vulnerability email and private reporting, response expectations, issue/PR routes, and a support policy are present, but there is no verified organizational identity, demonstrated multi-maintainer structure, or formal long-term maintenance commitment.
Outputs are designed for Telegram-native rich messages, checklists, tables, document links, reminders, and directly inspectable Obsidian-compatible Markdown, making the static output design highly usable. Layered long-term memory, personal CRM, actionable reminders, Google Workspace integration, and a user-controlled vault provide clear marginal value beyond an ordinary chatbot. Cost disclosure covers models, VPS hosting, voice, and provider choice, but the quoted monthly amounts, savings, and end-to-end outcomes remain repository claims without independent execution or comparative evidence, so cost-benefit is not awarded full marks.
Major claims are traceable to named documentation sections, release records, package versions, the security policy, and concrete tests for frontmatter handling, recovery, and fault injection. The tests use fixed seeds and explicit recovery invariants. The sources also distinguish stated behavior, known gaps, beta risks, and marketing scenarios without presenting this static review as an executed validation, supporting strong fact/inference separation. Cross-source corroboration is reduced because all evidence is repository-authored and many central product claims appear only in the README or changelog; the supplied code excerpts do not cover the Telegram bridge, redaction gate, installer, updater, or complete end-to-end behavior.
- The agent shell inherits the process environment, so an injected turn may read model, Telegram, Google, and other secrets. Run it under a dedicated low-privilege account, minimize inherited variables, and restrict host file permissions.
- PDF/DOCX bodies, userbot-read chats, and agent-browser output are not covered by one consistent injection screen; do not treat those sources as trusted instructions.
- Personal-account userbot automation violates Telegram's terms and may cause throttling or bans. Prefer read-only mode and avoid using a high-value primary account.
- Plugin code and plugin-invoked bash can access every installation secret. Install only reviewed plugins and treat them as equally trusted with the core agent.
- The one-command example pipes code from the moving main branch into a shell. Download and review it first, and pin deployments to a specific release or commit.
- This assessment used only the supplied static files; installation, tests, agent workflows, and dependency audits were not executed.
Recent releases
Latest entries from the project's GitHub Releases. Notes are quoted from upstream as written, not rewritten or tested by FollowAgents.
-
Release notes excerpt
- 🔧 Сводки и напоминания снова читают Telegram: плановый ход и сработавшее напоминание читают чаты через юзербот; отправку, ответ, пересылку, правку, удаление, реакции и отметку о прочтении Ива сама не делает, текст отправляет код. Scheduled turns and fired reminders may read Telegram through the userbot read tools; every Telegram write stays forbidden and the code delivers the final text. …View on GitHub ↗ -
v0.5.8 Iva 0.5.8
Release notes excerpt
- 🔧 Model context window in Telegram: /new and status use the same context window as the runtime. Claude shows 1M when no override is configured, and model selection saves the selected Claude model's window. Helpers respect their own model's window. - 🔧 Окно модели в Telegram: /new и статус используют то же окно контекста, что и рантайм. Claude показывает 1M при отсутствии явной настройки; выбор модели сохраняет её окно. Помощники учитывают окно своей модели.View on GitHub ↗