TeaNode

A personal assistant that lives on your own server.

It reads your mail, keeps your calendar, files your receipts and tax forms, writes up your meetings and keeps an eye on your coding sessions, and it remembers what it learns about you. Talk to it from the iPhone app, a browser or a call. One program and one PostgreSQL on your hardware; point it at an Ollama or a vLLM of your own and nothing leaves the machine.

What it looks after

Your mail. Sorts what arrives, says what is waiting on you, and drafts the answer in your voice. Sending stays with you.
Your days. A calendar, reminders, notes and an address book your phone keeps in step, and invitations answered from the conversation.
Your money. Banks, cards and brokerages linked or imported, spending filed your way, budgets that look ahead, and receipts matched to their charges.
Your taxes. Paystubs, W-2s, 1099s and 1098s read from a PDF or a photo, and the year added up into what you are likely to owe or get back.
Your meetings. Record on your iPhone, and get a transcript as it happens, the speakers by name, and a summary filed where it belongs.
What you told it. A memory of the people, projects and places in your life, which it writes as you talk, cites when it answers, and tidies in its dreams.
Your coding sessions. Claude Code and Codex on every computer. Their questions come to you, and they start knowing what your agent knows.
Your computer and browser. Files, a terminal and a browser on the machines you attach, with your word asked before anything it cannot undo.

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 finance and knowledge, drawn in the system's own controls and at your text size.

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.
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.