Postern

The Personal Context Gateway. Connect the sectors of your life once — finance, health, mail, contacts, calendar, home — and reach them from any agent through one surface. Read them, and act on them where the source allows.

Postern runs on your own machine, and there is nothing in the middle: no account to create, no service to sign up for, no model provider in the loop, and no correlation happening across your domains behind your back. Nothing leaves the box you started it on unless you ask it to.

getpostern.com is the front door — the live demo, and a field guide for every provider.

The Gatehouse — a real gate with four sources connected, everything freshly synced. This is localhost:8787 once your first sources are in.

What it removes

Postern is best understood by what stops being your problem.

• API discovery. Every provider is a different API with a different auth dance, a different pagination model, a different idea of what a "transaction" is and which direction money flows. Today an agent pays that cost at runtime — reading docs, guessing field names, discovering the sign convention by getting it wrong. Postern pays it once, in code, and publishes a typed schema with the traps written down: get_schema carries the notes and per-field semantics an agent must read before composing a filter.
• Per-agent re-integration. Every new agent, harness or assistant currently re-does the whole integration: its own OAuth app, its own tokens, its own connectors, its own permission model. With Postern you connect a source once and mint a scoped key; the next agent gets the same context in one step and inherits the same grants and the same audit trail.
• The harness ceiling. Because the integration lives in the harness, leaving the harness means leaving the context. Postern is harness-agnostic on purpose: swap Claude for something else, add a second agent, move to a different client — the context, the capabilities, the permissions and the log stay where they are, because they were never inside the agent.

What it deliberately does not do: no LLM runs inside the gateway, no cross-domain correlation, no derived facts written back into your store. It is a faithful cache and a dispatcher. The agent reasons; Postern authenticates, normalizes, stores, serves, and dispatches.

Three properties

• One place. One surface, one grant. A granted sector covers reading and acting across every provider in it.
• Lightning fast. Reads come from a local cache in milliseconds. fetch_live is the one read path that touches a source, and actions add no gateway overhead around the single unavoidable dispatch.
• Harness-agnostic. MCP, REST, or whatever comes next — every edge is an adapter over the same seven core primitives. There is never a second implementation.

Quickstart

You need Docker and about five minutes. No .env file is required to get to a running Console.

git clone https://github.com/getpostern/postern.git && cd postern
echo "POSTGRES_PASSWORD=$(openssl rand -hex 24)" > .env
docker compose up -d

(Only docker-compose.yml is actually needed — download that one file if you would rather not clone.)

Then open http://localhost:8787 — that is the Console. It walks you through connecting your first source.

The compose file pulls a published multi-arch image (ghcr.io/getpostern/postern) and publishes every port on 127.0.0.1 only.

The password has to go in .env, not in front of the command. It has no default on purpose — compose refuses to start without one — and Postgres bakes it into the data directory on first boot. Set it inline and you generate a different one on every invocation: the second docker compose up cannot authenticate, and every other compose subcommand fails outright on the missing variable. Keep it alphanumeric, too: it is substituted into a connection URL as literal text, so openssl rand -hex 24 is the safe generator (base64 output contains / and +, which break the URL).

Building from source instead? docker-compose.dev.yml carries the build: key, and CONTRIBUTING.md has the rest.

Next: docs/SETUP.md is the full self-host path — every provider, the traps, and how to connect an agent. If you are an agent doing this setup on someone's behalf, read AGENTS.md instead: it is the same path written as a contract, with each step marked human-required or automatable.

The agent surface

Seven primitives, not a tool per question. The MCP adapter maps 1:1 onto them; the REST mirror serves the reads.

primitive	what it does
describe_context()	connected sectors + per-connection freshness
get_schema(sector?)	the queryable objects and fields per sector, with the semantics notes
query({sector, where?, select?, limit?})	structured read, fields validated against the schema, results capped
get_record(sector, id)	drill to the raw source record
fetch_live	bounded live pull beyond the cache — sector sync-now or per-record drill
list_actions(sector?)	the cache-served action catalog (connectors that support acting)
invoke_action(...)	dispatch one action to the source (deterministic target resolution)

query and get_record are always cache-only and instant. query reads one sector — there are no cross-sector joins, by design; an agent fans out and correlates on its own side.

From the agent's side it looks like this — one gate, three agents each holding its own key, every read landing in the owner's ledger:

From the live demo — it moves at getpostern.com.

What connects today

source	how you connect it	sectors	screen by screen
SimpleFIN	paste a setup token	finance	field guide
Plaid	your own Plaid app + a hosted Link session	finance	field guide
iCloud	Apple ID + an app-specific password	mail, calendar, contacts	field guide
Gmail	address + an app password (IMAP)	mail	field guide
Microsoft	your own OAuth app	mail, calendar, contacts	field guide
Google	your own OAuth app	calendar, contacts	field guide
WHOOP	your own OAuth app	health	field guide
Apple Health	a Shortcut on your iPhone pushes to your gateway	health	field guide
Home Assistant	instance URL + a long-lived token	home	field guide

Home Assistant is the one that also acts: the action catalog is served from the cache and dispatched through invoke_action. Adding a source is a connector plus a schema-registry entry and a migration — never a control-plane change. See CONTRIBUTING.md.

License and model

The whole gateway is open source under AGPL-3.0-or-later — the engine, every connector, both agent edges, the Console. Nothing here is a crippled tier: the open core is the product, not a demo of it.

The paid surfaces sit beside it, not inside it — a contextual-memory tier, a person-to-person trust layer, and hosted convenience for people who would rather not run a box. None of them is a gate on anything in this repository.

Contributions are inbound under the same license, by DCO sign-off — see CONTRIBUTING.md. The Postern name and door mark are not licensed with the code; see TRADEMARK.md.

A note on PCI_ and pci

Environment variables, the default database name and some log prefixes still carry a PCI_ / pci prefix from the project's working name before it became Postern. They are wire identifiers, not branding, and renaming them would break every existing install for no functional gain — so they stay. If you see PCI_MASTER_KEY or a pci database, that is Postern.

Where the detail lives

you want	read
to install it and connect your sources	docs/SETUP.md
every provider console, screen by screen — with the traps	getpostern.com/guides
an agent to do the setup	AGENTS.md
you are an agent, connecting to someone's gate	getpostern.com/for-agents
to know exactly what is trusted, and what is not	SECURITY.md
to reach your gateway from away	docs/runbooks/remote-access.md
to know why something has the shape it has	docs/specs/decisions/ — the ADRs, indexed
to build a connector or send a patch	CONTRIBUTING.md
the architecture end to end	docs/architecture.html