TeaNode · Documentation · Source
TeaNode
A personal agent for your whole life, on a server you own.
Your mail, calendar and contacts, your photos and where you have been, your health, your coding sessions, your meetings, your money, your shopping and your passwords, joined up in one agent that sees how they connect and keeps a journal of your days. It all runs on your own hardware, one program and one PostgreSQL, so your life is stored with you and nowhere else. You choose the model, you choose what it may reach, and you can take any of it back. Point it at an Ollama or a vLLM of your own and nothing leaves the machine at all.
Everything it looks after
- Chat. Talk to your agent, and to your people. One conversation with your agent on every page of the dashboard, in the iPhone app and on a call, with your family's and friends' chats beside it, where you can write, leave a voice message or call. Bring your agent into any of them with an @.
- Search. One search across all of it. Type a word and your server looks in nine places at once: your conversations with your agent, mail, contacts, photos, memory, documents, recordings, places and finance. A few results from each, grouped, with a way into the full list. It asks no model and builds no new index.
- Journal. Every day, put back together. Your server already holds your day: the photos, the places you went, the mail, the meetings, the money, the coding sessions and the steps. Journal joins them into one page for each day, in the order they happened. You add your own words and how the day felt, and your agent writes the story of it in its dreams, every mention a link to the real thing.
- Mail. Mail that sorts itself, and follows through. Your agent reads what arrives, marks what matters and what is waiting on you, keeps track of the bills, parcels and deadlines in it, and writes the replies for you to send. It is a whole mail server for your own domain, read here, in the app or in any mail program.
- Calendar. A calendar that keeps up with you. Calendars and reminders on your server, in step with every device. Invitations that arrive as mail become events, your agent answers "am I free Thursday" and books the time, and a family calendar sits beside your own.
- Contacts. An address book that knows who is who. The people you keep, with photographs, birthdays and addresses, in step with your phone and known to your agent, so "ask my father" or "Sam's new number" reaches the right person.
- Photos. Your photo library, on your own server. Your iPhone backs its library up in the background, and the Photos page, the app and your agent all read the same library: by month, by album, by place and by the people in it. The faces are found on your server itself, never by a service elsewhere.
- Location. Where you have been, kept by you. The iPhone app keeps your visits to places, also while it is closed, and your server names them, finds the trips between them and draws your day on a map. Share where you are with the people you choose, and ask your agent when you last went somewhere.
- Health. Your health, on your server. The iPhone app copies your Apple Health data to your own server: steps, sleep, heart rate, workouts and the rest. The dashboard and the app chart it, and nobody else sees any of it unless you share it.
- Coding. Your coding sessions, from anywhere. Keep your Claude Code and Codex sessions in herdr, and your agent sees every one of them on every computer you attached. Their questions come to you wherever you are, and each session starts knowing what your agent knows.
- Knowledge. A memory that learns you. What your agent knows is a graph of pages, people, projects, places and things, joined by links that say how. Every fact is numbered, carries the words it came from and can be cited in an answer, and every change says who made it, so you can put it back.
- Recordings. Meetings, written up for you. Record a meeting on your iPhone and your agent writes it up: a transcript as it happens, the speakers by name, a summary of what was decided, and what it taught filed in memory. The original stays on your server.
- Finance. Your money, and your taxes. Link your banks, cards and brokerages through Plaid or SimpleFIN, or import a statement, and see where the money went, where the month is heading and what it all adds up to. The rows are kept in your own database, and your agent reads the same rows, so you can just ask.
- Shopping. Shopping lists the whole house shares. Keep lists like Groceries or Hardware and share them with your circle. At the store you shop the store, not a list: everything your lists need there, by aisle. The others see the cart fill as you go, and the receipt checks off what you bought.
- Payments. Payments, with your word on each one. Your agent pays through a payment skill running on your own computer, such as Link, and never sees a card number. Lend it to somebody in your household with limits, and anything above them waits for you.
- Passwords. Passwords your server cannot read. Logins, passkeys, one-time codes, cards and notes are sealed on your phone or in your browser before they reach your server, so neither the server nor whoever runs it can read them. Fill them in Chrome and on the iPhone, share them with your circle, and let your agent sign in with the few you choose.
Yours, and only yours
An agent that reaches every part of your life is only worth having if that life stays yours. TeaNode runs on hardware you own, keeps everything in your own database, and does nothing you have not turned on.
- On your hardware. One program and one PostgreSQL on a machine you own. Your mail, photos, health and money are stored there, with no account with us at all, and your passwords are sealed on your own devices, so even the server cannot read them.
- Your choice of model. A hosted model is sent only what a turn needs. Point it at an Ollama or a vLLM of your own and nothing leaves the machine at all.
- Nothing without your say. Every part is off until you turn it on, the agent reaches only what you grant, and it stops for your word before anything it cannot undo.
- Open, and yours to keep. MIT licensed, every line on GitHub. Back it up, export it, erase any of it, or switch it off.
TeaNode for iPhone
Chat with it, call it, answer it from a notification, and hand it what you are looking at from any app. One app for every TeaNode server: scan the code your dashboard shows and it connects as you, with nothing to type. It carries what the dashboard does, from mail and the calendar to photos, finance and knowledge, drawn in the system's own controls and at your text size, on the iPhone and on the iPad held either way.
In TestFlight now, and on its way to the App Store.
Getting started
One command for just the assistant, and add your own mail when you want it.
- Just the assistant. No domain and no mail ports. It listens on 127.0.0.1:8080; put an HTTPS proxy in front of it to reach it from your phone.
- With your own mail. Mail at your domains, with the assistant and everything above.
Get started installs the assistant with one command, curl -fsSL https://teanode.com/get.sh | sh; the commands for both are in the Quick start.
What you need
- A computer that stays on. The install command brings Docker on Linux, and PostgreSQL with it.
- A model to think with. An API key, a ChatGPT plan you already pay for, or an Ollama or vLLM of your own.
- For the iPhone app and for away from home, an HTTPS address in front of it, from any reverse proxy.
- For your own mail, a domain whose DNS you can edit and ports 25, 80, 443, 587 and 993 open.
Documentation
Getting started
- What is TeaNode: Send and receive mail at your own domains: mailboxes read here or over IMAP, forwarding, what it does, and what you need to run it.
- Quick start: TeaNode running with docker compose in a few minutes: the assistant first, with no domain, then mail at your own domain if you want it.
- Getting started: Standing up a mail server for one domain, from nothing to mail arriving in a mailbox you can read in a mail program, including the DNS records and the port 25 problem.
Running it
- Deploying: The container image and the compose file, what runs beside the server, how it upgrades itself, and what to back up.
- Configuration: Where the settings live, the environment variables that say how to reach them, and every field an operator can set.
- Agents: The personal agent: what it needs, what it does with a mailbox, and what to weigh before turning it on.
- Memory: What your agent keeps between conversations: a graph of pages it writes without being asked, the places it reads from, and what it does with all of it in its dreams.
- Voice: Call your agent from the chat drawer: say what you want, hear the answer as it is written, and cut in when you like. On a laptop or a phone.
- Coding sessions: Your Claude Code and Codex sessions in herdr, on every computer you attached: your agent reads them, types into them where you can see, and brings you their questions to answer from anywhere.
- Memory in coding sessions: Claude Code and Codex shown what your agent knows about the checkout they run in: the project page and the last session when one starts, recall kept to the project before each prompt, and the transcript read within a minute.
- Model Context Protocol: TeaNode on both ends of the protocol: answering it, so your editor can use your agent's tools and ask it questions, and connecting out to servers of your own.
- Finance: Your banks, cards and brokerages linked through Plaid or SimpleFIN: transactions in your own categories, budgets that say where the month is heading, savings targets, net worth, and a tax year put together from your paystubs, W-2s, 1099s and 1098s, all kept in your own database.
- Circles and chats: The people on one server in circles: chats with each other in the drawer and the app, with voice messages and voice and video calls, with or without their agents, and calendars, albums, memory pages, skills, finance and location shared at the level each owner picks.
- Photos: Photos and videos on your own server: backed up from the iPhone in the background, found by place, date or what is in them, faces grouped into people you name, and albums shared with your circle.
- Location: Visits to named places recorded by the iPhone app, the trips between them and how you traveled, a map of your day, where you are shared with the people in your circle, and what leaves the server to name a place.
- Passwords: Logins, passkeys, one-time codes, cards and notes, encrypted on your own devices: filled in Chrome and on the iPhone, shared with your circle, and used by your agent only on the logins you turn on.
- Journal: A page for each day that links everything that happened, with your words, your mood and the weather, and the story your agent writes of it; weeks, months and years above the days.
- Shopping lists: Lists shared with your circle, shopped store by store and aisle by aisle, checked off live and by the receipt, with pictures, prices and a reminder at the store.
- The command line: The two programs: the server and the few things only its host can do, and the client that administers it from anywhere through the API.
Security
- Reporting a security problem: Where to report something exploitable, what is in scope, and what is not.
- Security review: A review of the whole program: what was examined, what was found, what was fixed, and what is still open.
Contributing
- Contributing: Naming, comments, the invariants that bite, tests, commits and the changelog that cuts a release.
- Local development: Getting a working build and a database to point it at, a development server that cannot send mail, and the optional scanners.
- Project structure: What each package is for and which way the dependencies point.
Every document is also plain markdown, listed in /llms.txt.