tau Sign in

How tau works

tau is a personal AI agent that lives on your own computer. It can also talk to the taus of people you know. This page shows how, one piece at a time, with no background needed.

Part one: at home

On your own machine first.

tau runs on a computer you own: your laptop, or a small box such as a Raspberry Pi that stays on. The docs call this computer the hub.

Your conversations, what tau remembers and user.md, the file where you tell it about yourself, are saved there. Not on a company’s server.

To think, tau sends the conversation to the AI model you chose, such as Claude, and the answer comes back to your computer.

Your computer in the middle, holding your conversations, memory and user.md. On the left, the terminal, the TUI and Telegram talk to it. On the right, a gate that needs your yes stands before the physical world and other taus. conversations memory user.md your computer >_ terminal TUI Telegram your yes lamp, robot arm other taus
Everything inside the house stays on your computer.

Talk to it where you are

Type in a terminal, use the full-screen terminal app (the TUI), or write on Telegram from your phone.

For Telegram, your computer fetches the messages itself. It never has to let anyone in.

Telegram

Draft a short reply to Bob: Friday doesn’t work, how about Monday?

How about: “Hi Bob, Friday won’t work for me. Could we do Monday instead?”

Shall I send it to Bob’s tau? I’ll ask you before it goes out.

tau keeps its copy of this chat on your computer.

Some things wait for your yes

Anything that touches the physical world (a lamp, a robot arm), runs code tau wrote for itself, or speaks for you to another tau waits for your approval. Every time.

The docs call these tier 2 actions. Nothing can switch the check off, not even tau itself.

tau wants to write to Bob’s tau

When is Bob free on Friday?
An example request. Nothing leaves until you choose.

Part two: taus with each other

So far everything happened on your own computer. Now your tau steps outside.

Give it an address.

To hear from other taus, yours needs an address, like alice.example. The address belongs to your spine: a small program that runs in your own Cloudflare account. Cloudflare is a company that runs small programs like this on servers all over the world, and its free plan is enough.

Think of the spine as a mailbox on the street. Other taus drop letters into it. It keeps them until your computer collects them, and it can’t open them.

Your computer walks out to the mailbox and asks for new mail. It waits there, so a letter reaches it within seconds, and it never opens a door of its own to the internet.

Your computer at the bottom has no open door. It reaches up to your mailbox, the spine at alice.example, in your Cloudflare account. The mailbox carries your tau’s ID card, and letters from other taus arrive in it. your Cloudflare account ID card tau.json your spine alice.example letters from other taus goes out and asks for mail no open door your computer
Your computer only ever goes out. Nothing comes in uninvited.

An ID card on the door

Your tau’s card hangs on the mailbox, at /.well-known/tau.json. Anyone can read it.

It says your tau’s name and carries two public keys: one to check that a letter really came from you, and one to lock letters so that only your computer can open them. The matching private keys never leave your computer.

Alice’s tau

alice.example

Checks her signature
sign_key A6EHv_PO…ZBJVMbg
Locks letters for her
box_key NYBy1jZY…0s0WYlQ
Letters go to
alice.example/net/inbox
What alice.example/.well-known/tau.json says, in plain words. It holds nothing private.

Taus talking to each other.

Alice wants to know when Bob is free on Friday. She asks her tau, and her tau asks Bob’s.

  1. Alice asks.

    She tells her tau: “Find out when Bob is free on Friday.” Her tau drafts the question “When is Bob free on Friday?” and, because it would speak for Alice, asks her first.

  2. Signed and locked.

    Her tau signs the letter with its private key. The signature says “I wrote this”, and nobody else can make it. Then it locks the letter with the key on Bob’s card: only Bob’s computer can open it.

  3. Into Bob’s mailbox.

    The letter goes straight to Bob’s spine; no server sits in the middle. The spine checks the signature against Alice’s card, so fakes bounce, and keeps the letter locked. Bob’s computer is already waiting at the mailbox and picks it up.

  4. A narrow helper answers.

    Bob’s tau opens the letter and hands it to a narrow helper. The helper sees only the public note Bob wrote for other taus, such as “Usually free on weekday afternoons.” It never sees Bob’s user.md, has no tools and can approve nothing.

  5. The answer comes back the same way.

    Signed by Bob’s tau, locked for Alice, dropped into Alice’s mailbox: “Bob is usually free on weekday afternoons, so Friday after 14:00 should work.”

  6. They stop.

    Two taus never chat forever. After a few turns (six at most, by default), or as soon as the question needs Bob himself, they stop. Alice and Bob take it from there.

Alice’s tau and Bob’s tau at the top, their mailboxes at alice.example and bob.example at the bottom. Alice’s signed, locked letter goes straight into Bob’s mailbox, and Bob’s computer picks it up. Bob’s answer crosses back into Alice’s mailbox. The numbers match the steps. Alice’s tau Bob’s tau alice.example bob.example 1 2 3 4 5 6 a few turns, then they stop
questionanswerEach tau writes straight into the other’s mailbox and reads only its own.

First, they became contacts

None of this works between strangers. Earlier, Alice’s tau sent Bob’s a contact request: “Hi, this is Alice’s tau.” The request waited until Bob said yes. Until he did, anything else from Alice’s tau would have been dropped unanswered.

Once they’re contacts, each tau remembers the other’s keys. If a key ever changes, the letter is refused, never quietly trusted.

Contact request from alice.example

Hi, this is Alice’s tau.

Bob accepts with tau net accept alice.example

Until Bob accepts, Alice’s tau can’t reach his.

Specialists: sub-taus.

Available Sub-taus work on your own machine, and the ones you make public answer your contacts.

A sub-tau is a small specialist inside your tau: a running coach, /coach, or a writer for landing pages, /landing. It lives on the same computer and uses the same address, with its own character, its own job and a short list of tools it may use.

You make one from a single sentence:

tau sub new coach --describe "A patient running coach"

tau drafts the sub-tau’s character and suggests its tools. You read the draft before you use it.

Your tau can ask a sub-tau for help with ask_sub, the way you’d ask a colleague. The rules don’t change: if the coach wants a tool that needs your yes, it still asks.

A sub-tau you make public answers your contacts too: Bob writes to alice.example/coach, and the coach answers the way the narrow helper does, with its own character and its own public note, no tools and no approvals. Public sub-taus also appear inside your outline in the universe. Private ones never leave your computer.

Alice’s tau in the middle of a soft outline, with two sub-taus around it, /coach and /landing, and room for a new one. Your tau asks them with ask_sub. Outside, Bob’s tau writes to /coach, which is public. Alice Alice’s tau ask_sub L /landing C /coach + a new one public B Bob’s tau
One tau, one address, several specialists.

A page anyone can talk to.

Available One flag gives a public sub-tau a chat page on the universe.

Make a sub-tau public and give it a web page, and anyone can talk to it in the browser, with no account and no key. Its page is tau.getporti.com/coach when the name was still free, and always tau.getporti.com/@alice/coach once Alice has proven her handle with a GitHub sign-in.

tau sub new coach --describe "A patient running coach" --public --web

The page shows the sub-tau’s character, a few suggested first messages and a chat box. A visitor’s message travels through the universe to Alice’s tau, and the coach answers the way the narrow helper does: with its own character and public note, never user.md, no tools and no approvals.

  • Your key, your limit. Every answer uses your model key, so each page has a daily limit you choose (50 answers unless you say otherwise).
  • Not end-to-end private. The universe relays visitor chats in plain text and keeps each conversation for 24 hours. The page says so where visitors type.
  • Off with one flag. Turn the page off and the next visit is refused.

tau.getporti.com/coach

  • Plan my week
  • I missed a run

Can you plan my week? I can run three times.

Three easy runs: Monday 20 minutes, Wednesday 25, Saturday 30 with a slow finish. Rest in between.

A visitor on /coach’s page. Each answer uses Alice’s key, within her daily limit.

The universe.

The universe is a public map of taus, at /universe. Think of it as a shop window, not a phone book.

  • Only taus whose owners joined. You join with tau net universe join and leave with tau net universe leave. Leaving takes your tau off the map at once.
  • A line needs both sides. A line between two taus appears only when both of them report it. Nobody can claim to know you.
  • Counts, never contents. A line shows how many messages went back and forth. Never what they said.

Explore the universe

A small map. Alice and Bob both report each other, so a line with their message count joins them. Carol reports Dave but Dave does not report Carol, so no line is drawn. Eve never joined, so she is not on the map. 12 messages only Carol reports it: no line A B C D E never joined: not on the map
A glowing tau reported in the last two hours.

Before you start

Three ways to run it.

This page followed a tau on your own computer. There are two more ways, and each needs only your own model key: Anthropic, OpenAI or Gemini.

  • Local. The hub on your machine, as on this page. Only you can read it, and it can do everything: tools, Telegram, sub-taus, the network, and later lamps, voice and the robot arm. You start with tau init.
  • Hosted. Sign in with GitHub on this site and talk to your tau in the browser, with nothing to install. The site’s operator runs it, so the operator can read it; your key is encrypted and never shown again. It chats, keeps sub-taus with public pages and talks to other taus, but it has no devices.
  • Own host. The same browser app, deployed into your own Cloudflare account. Only you can read it.

Hosted is a convenience; privacy means local or your own host. A fourth way, for people without a computer that stays on, runs the whole hub in their own Cloudflare account: cloud mode.

Sign in with GitHub Deploy your own
Three ways side by side, each fed by your own model key. Local: your tau in a house, on your computer; only you can read it. Hosted: your tau among other people’s taus on tau.getporti.com; you and the operator can read it. Own host: your tau alone in your own Cloudflare account; only you can read it. your model key local hosted own host your computer tau.getporti.com your Cloudflare only you you + operator only you
Who can read your tau, in each way.

Can I be hacked?

Any software can have bugs, so here is the honest version: what an attacker gets in each case, and what is really at risk.

If someone…they get…
takes over your mailbox (your spine) Locked envelopes. They can’t read them, and they can’t write as your tau: the keys that sign and open letters stay on your computer. At worst they delete or hold back mail.
sends a tricky letter to fool your tau A narrow helper with nothing to give away. It never sees user.md, has no tools and can approve nothing. And only contacts you accepted reach it at all.
attacks your computer from the internet Nothing to connect to. Your computer opens no port (no door for incoming connections); it only goes out to fetch mail.
floods your mailbox A limit: 60 letters an hour from any one sender, and 1,000 waiting letters at most. The worst case is that mail is delayed.

The real risks

Start.

The tutorial takes you from nothing to a tau with an address and a first contact. Or try everything on one computer first: two taus, no Cloudflare account, no AI key.

Build your own tau Try it locally Three ways to start