EN Β· RU
Your personal AI assistant in Telegram.
Site Β· Use cases Β· Features Β· Install Β· Memory Β· What's new Β· Docs
Iva is a self-hosted Telegram AI assistant with layered memory that turns your messages into an Obsidian-compatible vault. You talk, it files: voice notes, photos, forwarded posts and decisions become plain-markdown cards it actually remembers. Everything runs on your own server, with your keys and your data.
Paste this into Claude Code, Codex or Claude Desktop:
Install Iva for me, instructions: https://iva-agent.com/install.txt
Or run the installer yourself:
curl -fsSL https://raw.githubusercontent.com/smixs/iva-agent/main/install.sh | bash- "What did we agree with client X about the last shipment?" β found in seconds, months later.
- A five-minute voice note from the car β a task list, a draft email, a meeting card.
- "Make a quote from this price list, cut the discount by 2.5%, send it to the client" β a finished Google Doc, link in the chat.
The rest β for business owners, specialists, executives and everyday life: Use cases.
The bridge long-polls Telegram, so no public HTTPS, domain or webhook is needed. Iva runs as two systemd user services, two systemd watchdog timers and seven in-process eve schedules β operations live in docs/deploy.md.
Wondering what you'd actually use an agent for? β 25+ real scenarios β business, work, everyday life.
Voice, vision, memory, personal CRM, Google Workspace, skills β expand the full list
- Voice β voice, audio and video notes transcribed with Deepgram nova-3; auto-detects ru/uz/en.
- Vision β photos described by your provider's own vision model; no extra key, no extra bill.
- Rich replies β tables, checklists, collapsible blocks and formulas render natively in Telegram via Bot API 10.1 rich messages; plain formatting keeps its proven path, with a graceful fallback.
- Quiet update checks β once a day Iva checks for a newer stable release without spending model tokens. If one exists, Telegram offers Update or Later once; otherwise it says nothing.
- Layered memory β remembers across months, long after the chat window has scrolled away.
- Personal CRM β who your people are, what you agreed, when to follow up.
- Search by meaning β BM25 plus link-graph rerank, any language; optional vector mode with one key.
- Decision cards β what you chose, when and why; old versions stay in a dated History.
- Tasks & reminders β priorities, due dates and a daily brief.
- Web search β four pluggable providers: Tavily, Exa, Parallel or Brave.
- Google Workspace β Gmail, Calendar, Drive, Sheets, Docs and Tasks from chat via the
gwsCLI; installed for you, with a guided key setup right in the conversation. - Skills & MCP β drop one file to add a procedure or connect an MCP server; keys stay in
.env. - Personal Telegram β userbot β read and send from your own account, not just the bot; connect by chat (QR, no terminal). Opt-in, at your own risk. A server-side anti-ban guardrail (FloodWait compliance + randomized pacing + circuit-breaker) is enforced, not just advised. Details.
- Safe to forward β forwarded text, captions and voice transcripts pass an injection screen before the model reads them. A flagged message or transcript reaches the model tagged as data rather than as an instruction; for media captions the screen runs but the tag does not travel with it yet.
- Token accounting β every model step is logged;
/usagereports it for free.
| Layer | What lives there | Path |
|---|---|---|
| π Leaves | the word-for-word transcript of each day, Iva's replies included | daily/YYYY-MM-DD.md |
| πΏ Branches | summaries folded upward: day β week β month β year | summaries/daily/, weekly/, monthly/, yearly/ |
| πͺ΅ Trunk | CORE.md (β€3600 chars, in every prompt) + typed cards: contacts, projects, decisions, ideas, notes |
CORE.md, cards/ |
- Every message lands verbatim in a daily markdown log β nothing is paraphrased on arrival.
- A nightly rollup at 04:00 distills day β week β month β year into schema-validated cards; facts that change get rewritten, not piled up.
- One core file,
CORE.md(β€3,600 chars), rides in every prompt β Iva knows you before it searches anything.
Full architecture and search internals: docs/memory.md.
The bot is half of Telegram. The other half is your personal account: connect the userbot (opt-in) and Iva works from it like a secretary β reads the group chats you never keep up with, folds them into summaries, catches the messages that actually need you, and replies as you.
- All of Telegram β groups, channels, unreads, search and the full history of your personal account.
- Onboarding in chat β tell the bot to connect your Telegram, scan a QR. No terminal.
- Anti-ban guardrail on the server β FloodWait compliance, a randomized delay after every send, and a circuit-breaker that pauses sending after three FloodWaits in 24 hours. It is enforced in the proxy rather than asked for in a prompt, and it wraps the three outbound calls that actually get accounts flagged: messages, files, forwards. Joins, invites, contact imports and reactions are not wrapped β those limits live in the skill file, which is a prompt.
- Read-only mode β one
.envswitch and Iva can read and search but physically cannot send.
Warning
Automating a personal account is against Telegram's ToS and can get the account limited or banned. The userbot is opt-in and used at your own risk β reading is far safer than sending. Details: docs/userbot.md.
Web pages, search results, voice transcripts, captions and the vision model's description of a picture reach the model only through a prompt-injection sanitizer. On a forwarded text message the same gate annotates the turn with a warning instead of filtering the text, and document bodies, userbot-read chats and agent-browser output are not screened at all. Everything that leaves through the Outbox passes a secret-redaction gate, and the user allowlist fails closed β an empty list answers nobody. Your memory is a private git repo you own; the honest boundary is that the model and transcription are cloud APIs you choose and pay for. Gate internals and the full boundary: docs/security.md.
Ask Claude Code, Codex or Claude Desktop to install Iva on your server or Mac:
Install Iva for me, instructions: https://iva-agent.com/install.txt
Or run the installer yourself.
One command on any Ubuntu/Debian box β a fresh VPS or your own machine:
curl -fsSL https://raw.githubusercontent.com/smixs/iva-agent/main/install.sh | bash- Get a bot token from @BotFather.
- Run the installer and answer its questions.
- Message your bot. The wizard picks your Telegram ID out of that message, finishes setup, and Iva confirms right in the chat that it's live.
Brand-new VPS, still logged in as root? Run bash <(curl -fsSL https://raw.githubusercontent.com/smixs/iva-agent/main/bootstrap.sh) first: it creates your sudo user (with lingering enabled), updates the box, and turns on a firewall, fail2ban and SSH hardening. It asks three things β a login, its password, and the timezone β and no SSH key. Then log in as that user with that password and run the installer above. Details: docs/install.md.
Install as a normal user, not as root β Iva's shell tool runs as whoever installed it. Headless installs take --skip-setup or --non-interactive. Prefer to read before you run? Fetch it with curl -fsSL https://raw.githubusercontent.com/smixs/iva-agent/main/install.sh -o install.sh, read it, then bash install.sh. Wizard walkthrough and an SSH primer for first-time VPS owners: docs/install.md.
iva updateinstalls releases only (vX.Y.Ztags) β the default.mainholds releases only; every accepted change lands in thebetabranch first.iva betaturns on beta updates: the tip of thebetabranch;iva stableturns them off and goes back tomain(nothing is rolled back β the next release catches up). Then runiva update.- A new installation on beta:
curl -fsSL https://raw.githubusercontent.com/smixs/iva-agent/beta/install.sh | IVA_BETA=1 bash. - The same switch is in Telegram:
/menuβ π Maintenance β π§ͺ Updates.iva versionshows which one is on.
Three messages, and you can watch the memory work:
- Send a voice note about your day β anything, out loud. Then look in
daily/inside your vault on the server: your words are sitting there in plain markdown, dated, yours. No other assistant hands you the file. - Tell it something a colleague would remember:
Marina at Acme wants the revised quote by Friday β she never picks up the phone. - Ask for it back the way a person would:
how should I follow up with Marina?β the answer comes from the card Iva just wrote, not from the last few messages.
Then send a photo of a business card, or forward a long post and ask for the gist. /menu has the rest; the full list is in 25+ scenarios.
Install from a clone β build it yourself
git clone https://github.com/smixs/iva-agent.git ~/iva
cd ~/iva && bash install.shThe installer reuses the existing checkout instead of re-cloning, keeps .env and the vault untouched, and installs the same dependencies. A fork or a branch works through variables read at startup: REPO_URL=β¦, BRANCH=β¦, INSTALL_DIR=β¦ (defaults: this repo, main, ~/iva). Details: docs/install.md.
Six model providers. Pick one and fill its block in .env:
| Provider | How you pay |
|---|---|
| OpenCode Go | API key, ~$10/mo ($5 first month) |
| Ollama Cloud | API key, ~$20/mo |
| OpenRouter | API key, pay-as-you-go, 300+ models |
| OpenAI (ChatGPT) | your Plus/Pro subscription, no API key |
| Claude (Pro/Max) | your Pro/Max subscription, no API key |
| Custom | your own OpenAI-compatible endpoint |
Default model is deepseek-v4-pro, 131k context. On Go it runs about $14β15/mo all-in ($10 model + $4β5 VPS; the model's first month is $5), no markup; voice rides Deepgram's free starter credit. Model lists, limits and the search matrix: docs/providers.md.
Use cases Β· Install Β· Configuration Β· Memory Β· Providers Β· Security Β· Deploy Β· Commands & CLI Β· Menu Β· Reminders Β· Extending Β· Plugins Β· FAQ Β· Troubleshooting
ΠΠΎΠΊΡΠΌΠ΅Π½ΡΠ°ΡΠΈΡ Π½Π° ΡΡΡΡΠΊΠΎΠΌ β docs/ru/
Iva carries eve 0.51.1 sources from vercel/eve in eve/, with our changes under Apache-2.0 and the original NOTICE. Maintainers build the package once; installations fetch the pinned archive. See building and publishing eve.
v0.5.13 Β· 15.11.2026 β expand the latest releases
- 𧩠Text answers while Telegram refuses widgets: Telegram's refusal is remembered for a day and Iva gives the same content as text; before, only the widget's caption arrived.
- β° Plain reminders arrive on time without waiting for the model: ready text is sent by code to the second; tasks still run as their own turn.
- β° A reminder no longer vanishes after an Iva restart: a firing cut short is marked and reported once, naming the reminder that may not have arrived; its text is never sent twice.
- β° A conversation reset keeps the reminder's text: when
/newinterrupts a reminder task, the original text arrives with a note; an explicit/stopkeeps the cancellation. - β° A failed reminder task arrives as a short line: the start of its text and "Not done: the turn gave no answer" instead of the whole task text.
- π©Ή The first progress reply arrives as an ordinary message: before a long chain of tools Iva says what she is doing, once the turn has run for more than 10 seconds.
- π©Ή A reply to Iva's own service message carries context: a reply to the bot's own text is marked as Iva's history; foreign quotes stay protected.
- π©Ή The message after
/newsurvives a restart in the middle of the reset: the new session receives the message sent right after/new. - π§ The night retries a temporarily failing model for weekly and monthly summaries: overload, HTTP 429 and dropped connections use growing pauses until the night's deadline; a successful retry closes the failure.
- π©Ή The night is not skipped after a restart that reused the process id: a schedule reservation left by the earlier process counts as abandoned at once.
- π
iva jobs statusnames the state of schedules: free, running, a dead process's reservation or an expired one, and the last outcome. - π§ Updates start from version 0.5.0: an older installation is refused with the recovery command and keeps running its version;
beta.shis gone,iva betaturns the beta on. - π οΈ A truthful update result: the success message appears after the new version is pinned in the installation.
- π§ Userbot: a wrong password can be entered again: the QR sign-in no longer starts over because of a typo in the two-factor password.
- πΎ A huge file no longer stops the memory backup: a vault file over 90 MB stays out of the commit and is named to the owner once; the rest of the memory is backed up as before.
- π§ The nightly graph and the write check judge a link the same way: a
[[β¦]]link accepted when the card was written is no longer called broken by the nightly graph. - π A failed plugin build undoes only its own switch: undoing
iva plugin enableortrustno longer restores trust or enablement removed during the build. - π©Ή A turn no longer takes Iva down when the Claude CLI exits early: it is now the failure of one turn, not of the process.
- π§Ή The eve copy without tests and docs: the eve sources inside Iva drop what Iva never loads; a plugin importing a removed eve entry point stops building.
- 𧩠Widget code stays hidden in live drafts: Iva no longer shows raw widget code in the reply draft while it is being typed.
- π Lighter, more exact widgets: Iva starts from Telegram's native unstyled card: a heading, a list, a table and buttons look like ordinary messages and weigh under a kilobyte. New patterns: a helper's steps with marks, rings, sparklines and receipts; a card fills the bubble to the edge, and a log grows upward.
- π§ Widgets go through the main Bot API address: Bot API 10.4 is out, and Iva no longer uses the beta address.
- π§ Fable 5.2 on the Claude model screen: the first button in
/modelβ Claude and in setup is now Fable 5.2, and it is the default Claude model. It needs Claude Code CLI 2.1.290 or newer; Fable 5.1 stays available throughCLAUDE_MODEL=claude-fable-5-1in.env. - π Widgets in replies: Iva draws a live card right in the message instead of lines of text wherever there is something to show: a calendar by day, week and month, the weather, a countdown while you wait, task and reminder lists, a chart with tabs, progress, a checklist. Turn them off in /menu β π¬ Rich replies.
- π§ Briefs and reminders read Telegram again: scheduled turns and fired reminders read chats through the userbot. Iva still never sends, replies, forwards, edits, deletes, reacts or marks as read on her own.
- π§ Google Contacts birthdays are complete: Brief keeps the full list, and a birthday counts as mentioned only after its message is delivered.
- π§ Plugins of different installations keep their services: service names are tied to the data folder, so removing, syncing or updating one installation leaves the other's services running.
- π§ Short button quotes in the daily journal: a tap keeps the button text and the first quoted line, up to 200 characters.
- π§ Tool search ranks names first: literal names beat long descriptions, so Telegram history and the chat list are found again.
- π§ Iva survives a Claude access rotation: after an early HTTP 401 she waits for the new access and repeats the call once.
- π§ The night raises its own limits for long days: within the configured ceilings it keeps going and retries git with a longer wait;
iva night show|setshows and changes the limits.
Full history β CHANGELOG.md.
eve 0.51.1-iva.7, Vercel's agent framework, runs the agent; Node 24's built-in SQLite runs the search index β no separate database. Iva grew out of agent-second-brain and autograph β that story is in docs/memory.md.
Iva gets better because people run it for real β contributors are welcome. Open an issue with what breaks, or send a PR. Everyone who already helped: docs/thanks.md.
MIT β take it, change it, run it on a hundred servers; just don't blame anyone if something breaks.