Skip to main content
Before you start
  • Docker. Install Docker first. It is the only thing you install by hand.
  • A machine that stays on. While it is off, your agents reach nothing. Keep it updated, the same as anything else you run.
  • About 10 minutes, plus the time the image takes to download.
  • Somewhere to keep one password. You create it in step 2. Postern’s database never accepts a different one afterwards, so open your password manager now.
  • Windows: not tested. Postern runs under Docker, so Windows should work. Nobody has run it there. Treat every Windows line on this page as untested.

​
Choose your path

Postern runs either way. A NAS or a spare machine works the same as the computer in front of you. The second path needs SSH on that computer, and nothing else changes.
1

Get the compose file

Open a terminal on the machine that will run Postern. On macOS, press Command-Space, type Terminal, press Return. On Windows, press the Windows key, type PowerShell, press Return.Make a folder and download the one file Postern needs:
On Windows, type curl.exe — in PowerShell, curl means something else. Nobody has tested these lines:
The folder now holds one file, docker-compose.yml. Every command below runs from this folder.You can clone the whole repository instead, if you have Git: git clone https://github.com/getpostern/postern.git && cd postern. Postern needs nothing else from it.
2

Write the database password

Postern’s database needs one password. It lives in a file named .env, beside docker-compose.yml.
Postgres records this password the first time it starts. It never accepts a different one against the same data, and there is no way to change it afterwards. Keep .env. Do not type the password in front of docker compose up. That creates a new one on every run, and every other docker compose command then fails.
In that folder, run the line for your system. It makes a password of letters and digits only. A /, :, @, ?, #, & or + breaks the address Postern uses to reach its database. Postern then exits at once. openssl rand -base64 32 is not a substitute: its output holds those characters often.
On Windows, run these four lines in PowerShell. Nobody has tested them:
.env now holds one line: POSTGRES_PASSWORD= and 48 letters and digits. That is the whole of Postern’s required configuration. Every other setting has a working default.Copy that line into your password manager now. The leading dot makes .env invisible in Finder and File Explorer. Do not make .env in Notepad — Notepad adds .txt to the name.
3

Start Postern

Docker must be open first. On macOS and Windows, open the Docker Desktop application and wait for it to finish its own start-up. On Linux, Docker runs as a service and needs nothing opened.From the folder that holds docker-compose.yml, start Postern:
The first run downloads the image ghcr.io/getpostern/postern, so it takes minutes. Later runs take seconds. The image runs on Intel and AMD machines, and on ARM machines such as Apple Silicon. Postern sets up its database tables before it answers anything, so port 8787 stays quiet for a few seconds after the command returns.Postern opens two ports to this computer only: 8787, the Console port, and 8788, the agent port. Only this computer can reach these addresses. Nothing on your Wi-Fi, and nothing on the internet, can. The database gets no port at all. Only Postern reaches it, over the private network Docker Compose creates.
If another program already holds 8787 or 8788, the app container does not start. Add a line to .env, below the password line:
Then run docker compose up -d again. The Console now answers at http://localhost:8790, and every 8787 below becomes 8790. MCP_HTTP_PORT moves the agent port the same way. If you already connected Google, Microsoft or WHOOP, change the address you registered there to the new port. They match it exactly, character for character.
Docker keeps two storage areas outside the containers: your data, and the key that unlocks every account you connect. docker compose down -v deletes both, permanently. Every account you connected becomes unreadable, and nothing can recover them. docker compose down without -v is safe: it removes the containers and leaves both storage areas alone.Take a copy of the key: Back up, export and erase. If Postern cannot open the vault at start-up, it refuses to start rather than starting broken. A database restored without its key stops there.
The VAULT KEY IS NOT BACKED UP notice. Postern prints it in its own log at every start. It is a reminder, not an error, and Postern runs anyway. It appears while Postern holds the key itself and no marker file sits beside it.The notice tells you to acknowledge the copy in the Console. No such control ships. Nothing in the Console writes that marker, and no address answers it. So the notice still appears after you hold a good copy.Two things stop it. Take your copy of the key first, then choose one.
  1. Write the marker yourself. Postern looks for a file named master.key.backed-up beside the key. From the folder that holds docker-compose.yml:
    Postern checks that the file is there. It never reads what is in it. Write the date anyway. It tells a later you when you took the copy.
  2. Hold the key yourself. Put PCI_MASTER_KEY in .env — a base64 32-byte key you keep — and restart. Make one with openssl rand -base64 32. Set it before the first start. A new key against accounts encrypted under an old one makes Postern refuse to start.
A restore brings the notice back. The marker sat in the old storage area, and the restore makes a new one.
Four commands cover the first week. Run them from the same folder:
To hold one release instead of the newest, add POSTERN_VERSION=v0.1.0 to .env.
4

Open the Console

The Console answers at http://localhost:8787, and only on the machine Postern runs on.If Postern runs on the computer in front of you, open http://localhost:8787.If Postern runs on another computer, forward the Console port to your own computer. Run this on your own computer, not on the machine Postern runs on. Turn on SSH on that machine first.
Replace YOUR_MACHINE with however you normally reach that computer: a name, a user@host, or an IP address. The terminal then prints nothing and does not return to a prompt. That is the command at work, not a hang. Leave that window open, use a second terminal window for anything else, and press Control-C when you want to stop. Now open http://localhost:8787 on your own computer.Anyone who can reach the Console port can change your settings and create agent keys. It has no password, so it stays on this computer. Do not change the address in docker-compose.yml to your network. Do not put a tunnel service in front of it. The full argument is in The Console has no authentication.The Console opens on a page headed Your gate is new. with one button, Add your first source. The left sidebar lists Gatehouse, then the six sectors, then Sources, Agents & keys, The ledger and Settings. A sector is one area of your life: finance, mail, calendar, contacts, health, home. It is the smallest thing you can grant.
The Postern Console on a fresh install: a page headed “Your gate is new.”, with one button labelled “Add your first source”.

The Console on a fresh install. The one button reads Add your first source.

To let an agent reach Postern from another device, see Remote access. It is off by default, and it never moves the Console off this machine.

​
Confirm it works

Run these on the machine Postern runs on.
  • docker compose ps lists db and app as running, and app turns healthy about 20 seconds after that.
  • curl -s localhost:8787/healthz prints {"status":"ok"}. The same address in a browser shows the same thing.
  • docker volume ls lists two names that end in pgdata and pci_master_key.
  • .env sits beside docker-compose.yml and holds one line that begins POSTGRES_PASSWORD=.

​
If something went wrong

​
What you have now

Postern runs on a machine you own. Docker downloaded a finished image from ghcr.io/getpostern/postern and built nothing on that machine. There is no Postern account and no Postern server in the middle. You have connected nothing yet, and no agent can reach anything until you grant it. Three things are now yours to keep: the machine, on and updated; the one line in .env; and a copy of the vault key.

​
Next

Mint your first key

a name, the sectors it opens, a deadline · a few minutes · Postern shows the key once

Set up remote access

Tailscale, and Funnel only if a hosted agent needs a public address · about 20 minutes, once · off by default