The email assistant

The email assistant is three plugins on the harness: the mail providers (gmail, imap) and email_workflows (the sweep, the judge, categories, the digest, setup and the demo). An install with the email plugins runs the email profile with no setting at all; evarness --dump-config shows the profile in effect and every plugin it mounts.

Start with Connect your mailbox. This page is what comes after.

Run the Evarness API

The scheduled jobs (the email sweep that fetches new mail, and the judge that sorts it on the local model) run inside the Evarness API service, which also serves the web console. Set a long random shared secret first: every API call needs it, except the /healthz probe. Write it to a file once, rather than re-running the generator in every shell -- openssl rand -hex 32 makes a different value each time it runs, so exporting its output straight in a second terminal does not reproduce the first shell's secret, and the API answers with a 401 that gives no sign why:

openssl rand -hex 32 > .auth-secret
export EVARNESS_AUTH_SECRET="$(cat .auth-secret)"
evarness serve

Use the same two commands (export EVARNESS_AUTH_SECRET="$(cat .auth-secret)", then whatever you're running) in every other shell that talks to this API -- evarness device pair, evarness status, a second terminal open to the same install.

evarness serve runs the API in the foreground on 127.0.0.1:8003; --port (or EVARNESS_API_PORT) moves it. From a clone of the repository, the same command is poetry run evarness serve. Run with Docker keeps it up as a service, and an installed wheel or a container image ships the web console already built.

From a source checkout, build the console first. A bare git clone + poetry install has no console at all -- evarness serve answers /chat and friends, but http://localhost:8003 shows nothing -- until you build it and point evarness serve at the result:

cd webui && npm install && npm run build && cd ..
export EVARNESS_WEBUI_DIST="$PWD/webui/dist"
evarness serve

The API listens on 127.0.0.1 only unless you pass --host (or set EVARNESS_API_HOST). It serves plain HTTP, so any other address puts the shared secret and your mail on the network unencrypted; evarness serve warns when you do.

Open the console at http://localhost:8003 and pair the browser: in another shell with the same EVARNESS_AUTH_SECRET (export EVARNESS_AUTH_SECRET="$(cat .auth-secret)", not a fresh openssl rand), evarness device pair prints a one-time code to type there.

A "Governor not reachable" banner is expected if this is all you started: the Governor is a separate HTTP frontend on port 8080 for the same governance kernel evarness serve already runs in-process, so nothing above needs it. Start it too, with the same secret, only if you want the warning gone or want the full stack the README describes:

export EVARNESS_AUTH_SECRET="$(cat .auth-secret)"
evarness serve &   # or: poetry run evarness serve &, from a source checkout
uvicorn evarness.server.governor.main:app --port 8080

Day to day

What	How
Ask about your mail	evarness -p "what's in my inbox?", or plain evarness for the REPL, or the console's Chat
See how the judge sorted recent mail	evarness email judgments (--bucket "Needs reply", --limit 20)
Judge new mail now, instead of waiting for the schedule	evarness email judge
Search the stored mail	evarness email search "invoice"
Correct a classification	evarness email recategorize --account <id> --message-id <id> --to <category>
Approve, check or take back mailbox writes	evarness email writes approve --account <id>, writes status, writes revoke
Where setup stands	evarness email setup --status
What is waiting for you	evarness actions, or the console's Actions screen
What every call did	the console's Governance and Call trace screens; evarness audit --help

Each command's --help lists its options. Only evarness doctor, evarness serve, evarness email demo, evarness email setup and evarness email writes approve are part of the stable CLI; the rest may change in a 0.x release.

Your own categories

The judge's buckets (Bill, Event, Needs reply, FYI, Unsure) and the categories setup discovers are configuration, not code. The custom-categories example adds your own and shows them live in the assistant.

Privacy, by construction

• Email is classified personal, so the governance kernel lets it reach local models only. A cloud model never sees your mail, whatever you configure for other work.
• Nothing changes in the mailbox without the account's write approval. Evarness never archives, marks read or deletes on its own; a move to Trash is a governed write like a label, and needs the same approval.
• Credentials (app passwords, OAuth tokens) live in the encrypted vault, under the master key evarness doctor checks.
• Every model call, tool call and answer leaves an audit row. The proof bundle checks these invariants offline.