Eva is a personal AI assistant that runs on a computer of your own. You talk to her from your phone, your computer or any other device, through Telegra 8000 m or her web page. She keeps what she learns in your vault, a private folder of notes that only you own.
Eva is a "super harness". A harness is a program that runs an AI agent, such as Claude Code or pi. Eva does not think by herself: she runs these harnesses for you, and organizes their work. You can change the harness, and keep the same chats, notes and projects.
Think of Eva as a helper who lives in one computer at your home:
| Piece | In everyday words | Technical name |
|---|---|---|
| The helper's desk | A computer that stays on, such as an old laptop. Eva runs there. | the hub |
| The vault | A private folder of notes. Eva reads and writes it, and keeps a copy on GitHub so that nothing gets lost. | a git repository |
| The brain | An AI harness that does the thinking, with your own subscription. | the engine (Claude Code, pi) |
| The phone line | How you talk to Eva: a Telegram chat, or her web page. | the front ends |
| The private road | A free app that connects your phone and computers to the helper's desk, and to nothing else. Strangers cannot reach Eva. | Tailscale |
- A computer that stays on, with Windows or Linux: an old laptop, a desktop, or a rented server in the cloud.
- An AI subscription: Claude, or another provider through pi, such as ChatGPT.
- A GitHub account. Eva keeps a private copy of your notes there.
- Optional: Telegram on your phone, to chat with Eva, and Tailscale (free), to open her page from your phone or any other device.
Run one command on the computer that stays on. It also works over SSH, a secure terminal connection from another computer.
-
Linux:
curl -fsSL https://github.com/guplem/eva/releases/latest/download/install.sh | sh -
Windows, in PowerShell:
irm https://github.com/guplem/eva/releases/latest/download/install.ps1 | iex
The command installs what Eva needs, and starts eva setup. Setup starts Eva and shows her address. Open it on your phone, and finish there, or in the terminal. docs/guide/setup.md explains each step.
Eva updates herself from new releases. You choose which ones in Settings > Updates.
Write to your bot as you write to a person. Eva answers in the same Telegram chat. Each Telegram topic (a thread inside your bot's Telegram chat) is a separate Eva chat. Send /new to start one. Telegram, the web page and the terminal share the same chats: see Chats.
Type / in the Telegram chat to see all the commands, with a short note for each.
You can also send voice notes, photos and files.
Eva's web page shows your chats, your projects, your files, your schedules (reminders), the cases, people, objects, pets and periods of your life notes, and the settings. Its address looks like https://your-computer.your-tailnet.ts.net: send /link in Telegram to get it. See Open Eva on your phone.
On Eva's own computer, run eva open to open her page. On Windows, her icon next to the clock opens it too: see Open Eva on her own computer.
A device without Tailscale cannot open Eva. That is on purpose: Eva can act on your computer, so only your own devices may reach her.
Settings explains each setting.
| Word | Meaning |
|---|---|
| Vault | Your private folder of notes, which Eva reads and writes, saved on GitHub. |
| Hub | The computer that runs your Telegram bot and your schedules. Only one computer is the hub. |
| Satellite | Any other computer with Eva and the same vault. It keeps the vault up to date, but stays quiet in Telegram. |
| Token | A long secret code that works like a password for one service. Never share it. Eva keeps each token on her own computer, never in the vault. |
| Tailscale | A free app that links your own devices privately, so your phone can open Eva's page from anywhere. |
| Project | A folder in your vault for one piece of work, often with code on GitHub. |
| Sync | Saving the vault to GitHub, and getting what other computers saved. |
| Sandbox | A box around a program, built by Linux or macOS. A project chat runs its commands in one, so it cannot see your vault. |
Eva tells you when something goes wrong. She sends a message to your Telegram chat when a problem starts, once a day while it lasts, and once more when it ends. The bell on the web page's home page opens the notification center: the open problems with their fix, and the last 30 days of notices. /status starts with "All good" or the number of problems. Send /logs to see the details.
Eva does not answer in Telegram.
Open the web page and look at Settings, or run eva status on Eva's computer. Check that the computer is on and connected. If you run Eva on two computers, check which one is the hub.
The web page does not open on my phone.
Open the Tailscale app and check that it says "Connected", with the same account as Eva's computer. Then send /link in Telegram and open that exact address.
Eva says "conflict" for the vault.
Two computers changed the same note. Eva stops saving to GitHub until you pick a version, so that nothing is lost. Send /conflicts in Telegram: see Vault conflicts.
A project chat says "This path is outside this chat's folder", or "No such file or directory" (on macOS, "Operation not permitted") for a note of the vault. That is the file wall: a project chat cannot open your vault, your other projects or Eva's own folder. A chat in a clone reads the notes of its own project, and Eva tells it where they are. Mention any other file to give the chat a copy. See What a chat can reach.
Something else.
Run eva doctor on Eva's computer. It lists the tools that are missing, and how to install each one.
- docs/guide/setup.md: the full installation, step by step, for Windows and for Linux. Its last section, Remove Eva, removes Eva again.
- docs/guide/reference.md: every command and setting, several computers, updates, and the optional features (voice notes, PDFs, Google Calendar).
- docs/guide/how-eva-works.md: how Eva works inside. Ask Eva herself too: she reads these guides when you ask how she works.
Eva is written in TypeScript and runs with Bun. AGENTS.md describes the architecture and the rules of the code; it is written for AI coding agents and for developers. Its section "What must not change" lists the goals that guide every change.
To run Eva from source, clone this repository and run bun install. Then type bun run eva where the guides say eva. A copy from source updates itself from main, not from releases.
| Task | Command |
|---|---|
| Install the dependencies and the git hooks | bun install |
| Run every check | bun run check |
| Format the code | bun run format |
| Run the tests | bun run test |
| Run every check but the tests | bun run check:static |
| Run the browser tests | bun run test:e2e |
| Build the single executable | bun run build:executable |
bun run check runs the same checks as the Linux job of the continuous integration (CI, the checks that GitHub runs) on every pull request. CI also runs the tests on Windows, the browser tests, the checks of the widget template, a build of the executable and a secret scan.
How Eva works inside explains her parts, one turn step by step, the vault sync and the safety rules.
docs/lessons-from-v1.md holds what the previous version, Wall-I v1, learned.
Steps that only a person can do are GitHub issues with the requires-human-intervention label.
MIT. See LICENSE.