TeaNode · Documentation · Source

Reporting a security problem

Please do not open a public issue for anything exploitable. That includes mail handling — SPF, DKIM, DMARC and ARC verification, header parsing, the MIME reader — and authentication, session handling, certificate issuance and the aggregation pipeline behind the dashboard's filters.

Report it through GitHub's private vulnerability reporting, on the Security tab of this repository. It is private to the maintainers until an advisory is published, and it gives us somewhere to talk that is not a public issue thread.

Tell us what you did, what happened, and what you expected. A message that reproduces it — a .eml file, an SMTP transcript, a request — is worth more than a description of one.

What is in scope

The program in this repository, in its default configuration. In particular: accepting mail on port 25, authenticated submission on 587, everything under /api/v1, and the certificates it obtains.

What is not

• Anything that requires the operator's own credentials or configuration access. This is single-tenant software; the operator is trusted, and the documented ways for them to reach their own network — webhook aliases, forwarding targets, a relay host — are features.
• The services it is configured to talk to: PostgreSQL, ClamAV, SpamAssassin, an object store. They are trusted as configured, which is why the documentation says to keep them off the public internet.
• Denial of service by volume. Algorithmic denial of service is in scope.

What has already been looked at

docs/security/security-review.md records a review of the whole program: what was found, what was fixed, what is still open, and what the review did not cover. Reading it first will save you finding something that is already written down.

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.