> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getpostern.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Postern

> A personal context gateway you run yourself. AI assistants ask Postern; Postern answers from your own machine.

Postern is a personal context gateway you run yourself. It covers six areas of your
life: finance, mail, calendar, contacts, health and home.

MCP is the standard way AI assistants connect to outside tools. Postern speaks it, so
Claude, ChatGPT and Cursor connect the same way.

Each agent gets its own key. A new key can reach nothing until you tick a sector.
Postern records what your agents do. Only Home Assistant lets an agent act as well as
read.

It runs on a machine you own. Agents connect to your machine, not to a Postern cloud.
Free and open source (Apache-2.0).

## The short version

Three commands, then one address. You need Docker, Git and a terminal. macOS and Linux
are the tested paths. Nobody has run Postern on Windows —
[Install Postern](/start/install) carries the untested Windows lines.

Keep `.env`. Postgres records that password on the first start, and it never accepts a
different one against the same data.

```bash theme={"system"}
git clone https://github.com/getpostern/postern.git && cd postern
printf 'POSTGRES_PASSWORD=%s\n' "$(openssl rand -hex 24)" > .env
docker compose up -d
```

The first run downloads the image, so it takes minutes. Then open
[http://localhost:8787](http://localhost:8787) — that is the Console.

Postern, its database and the Console start together, and Postern opens its ports to
this computer only.
[Only this computer can reach these addresses. Nothing on your Wi-Fi, and nothing on the internet, can.](/reference/security-model#the-trust-boundary)

[Install Postern](/start/install) covers the rest: the password you can never change,
what `docker compose down -v` destroys, and the Console from another computer. It also
does the same install without Git.

## Start here

<Columns cols={2}>
  <Card title="Install Postern" href="/start/install">
    Docker and a terminal · about 10 minutes · no cloud account
  </Card>

  <Card title="Set up remote access" href="/start/remote-access">
    Tailscale, and Funnel only if a hosted agent needs a public address · about 20
    minutes, once · off by default
  </Card>

  <Card title="Mint your first key" href="/start/first-key">
    a name, the sectors it opens, a deadline · a few minutes · Postern shows the key once
  </Card>

  <Card title="Connect an agent" href="/start/connect-an-agent">
    a key you created · a few minutes, plus a restart of the agent · claude.ai and
    ChatGPT need a public address first
  </Card>
</Columns>

## Connect a source

Eight sources, each with its own page. Connect as many or as few as you want. A sector
answers with whatever you connected in it.
[A new source never changes a grant you already made.](/reference/grants-and-sectors#what-a-grant-covers)

* **Finance** — [SimpleFIN](/connect/simplefin), the one to start with; [Plaid](/connect/plaid) for banks SimpleFIN cannot reach
* **Mail, calendar and contacts** — [Google and Gmail](/connect/google), [Microsoft](/connect/microsoft), [iCloud](/connect/icloud)
* **Health** — [Apple Health](/connect/apple-health), which your iPhone sends; [WHOOP](/connect/whoop)
* **Home** — [Home Assistant](/connect/home-assistant), the only source an agent can act on

[ChatGPT](/connect/chatgpt) is not a source. It is an agent that reads from Postern,
and it needs a public address first.

## Understand how it works

* [Security model](/reference/security-model) — the premise the rest of this list follows from, and what has not been reviewed
* [Which computers can reach Postern](/reference/ports) — the two ports, and why the Console has no password
* [The vault and the master key](/reference/vault) — what Postern encrypts, what it does not, and the one command that destroys the key
* [Provider sign-ins](/reference/provider-sign-ins) — the redirect address, what each provider needs, and the credentials that behave like passwords
* [Grants and sectors](/reference/grants-and-sectors) — six sectors, nothing granted until you tick it, read and act together
* [MCP tools](/reference/mcp-primitives) — the address an agent connects to, and what every call returns
* [The OAuth bridge](/reference/oauth-bridge) — how a hosted agent signs in, and the eight addresses the internet reaches
* [Read data](/reference/mcp-reading) — `get_schema`, `query` and `get_record`
* [Freshness and live reads](/reference/mcp-freshness) — `describe_context`, `fetch_live`, and how often Postern checks
* [Act on a source](/reference/mcp-actions) — `list_actions` and `invoke_action`
* [The audit log](/reference/audit-log) — what a row holds, and what gets no row
* [Read the record](/reference/read-the-record) — the ledger screen and `GET /api/audit`
* [What the record cannot promise](/reference/record-limits) — what is dropped before it lands, and what nothing in the database prevents

## Where things are

* Source code — [github.com/getpostern/postern](https://github.com/getpostern/postern)
* Image — `ghcr.io/getpostern/postern`, for Intel, AMD and ARM machines
* [Back up, export and erase](/operate/backup-and-export)
* [Frequently asked questions](/about/faq)