TeaNode · Documentation · Source

Your own assistant, running in about a minute.

One command on a computer that stays on, an account, and a key from a model service. The video shows all of it on a fresh server; the steps below are the same, one at a time.

1. Run one command. On the computer TeaNode will live on: a Linux server, a spare PC, or a Mac with Docker Desktop. It installs Docker on Linux if it is missing, starts TeaNode and its database, and waits until the dashboard answers.

   curl -fsSL https://teanode.com/get.sh | sh

   It puts everything in /opt/teanode (~/teanode when you are not root) and listens only on 127.0.0.1:8080. Read the script first at teanode.com/get.sh if you like; running it again keeps your data.
2. Create your account. Open http://127.0.0.1:8080 in a browser and choose a username and a password. The first visitor becomes the administrator, so do it right away.

   ssh -L 8080:127.0.0.1:8080 you@your-server

   TeaNode on a server rather than the computer in front of you? Run the tunnel above on your own computer first, then open the same address.
3. Paste a model key. Choose OpenAI, Anthropic or Gemini and paste an API key from it, or choose Your own server for an Ollama or vLLM. Press Start my assistant: it checks the key, picks a good model and starts the assistant. Each service has a Get a key link. The key stays on your server. A ChatGPT plan you already pay for is signed in to under Manage instead.
4. Say hello. Your conversation opens and the assistant introduces itself. Ask it anything; it learns about you as you go. Mail, calendars and contacts are under Manage, Server, Setup whenever you want them.

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.