Configuration

For the Git path (see How publishing works). Point Postwright at the repo your site builds from and enable pushing to trigger your host’s deploy.

These STEP_ZERO_* names are legacy (Postwright grew out of that project); a future release renames them. In the packaged product the publisher is chosen per brand — Git, folder, WordPress, Ghost, Beehiiv, webhook, or none.

WordPress, Ghost, Beehiiv, DEV, Hashnode, Kit, and Mailchimp have no environment variables. You set them for each brand in Settings > Brand, and the keys go into the encrypted store. Each has a Test connection button that signs in and checks access without posting anything. A brand with no blog destination can’t publish; choosing no blog is an explicit option.

A WordPress or Ghost key is saved for the site address it was entered with and is only ever sent there. How each destination behaves is in How publishing works, and the sign-in steps are in Connections.

LinkedIn and Facebook post through a signed-in browser profile. Instagram and Threads use Meta tokens. Bluesky, Mastodon, the channels, X, and Pinterest are normally set up from the Connections page, which saves what you enter into the encrypted store; the variables below are for a hand-managed setup. Step-by-step sign-ins are in Connections.

Substack Notes have no setting to connect: Postwright never posts to Substack. The Connections > Substack Notes (by hand) switch has a Note drafted for you to post yourself. After removing X or Pinterest in Connections, delete its variables from the environment too, or the next start saves them again.

A client’s approval recorded by hand needs no configuration at all. Review links (the page a client opens) need only your public media URL, and nothing else to set.

Reviews, their answers, and a copy of the images each revision showed stay on your Mac (at most 40 images and 50 MB per revision). The hold stays in force if a Team license lapses; you can still publish the post anyway from the Schedule page. More in Client reviews.

Nothing in Postwright’s own environment turns the MCP server on. You create an agent token in Settings > Agent access; Postwright keeps only its SHA-256 hash and shows the token once. Tokens are listed and revoked in the same place. The MCP server process reads two variables from its own environment:

An agent token works only on the content, schedule, cadence, and approval routes its scopes allow; never on connections, credentials, settings, auth, or the license; only from this computer, never through your public tunnel; and never to send a newsletter. On a Studio install you can’t create a token. Setup and scopes are in Agent access.

The optional wake helper has no setting in the environment. You turn it on in Settings > Wake for scheduled posts, and its limits are fixed. What it does and doesn’t do is in Getting started.

A missing or broken helper only shows in the status and never delays a post. Demo mode never runs it and shows sample wakes.

Keys you enter on the Connections page go into an encrypted store on your Mac, not into a settings file. The one thing Postwright keeps in the macOS Keychain is the master key that unlocks that store. A value saved in the app wins over the same setting in .env, and the programs Postwright launches never receive your keys.

The master key is kept per data folder. The packaged install’s folder keeps the original Keychain item; any other folder (a source checkout, a custom DB_PATH) gets its own. If Postwright finds saved credentials but no key that opens them, it stops and tells you rather than making a new key that would orphan them. A Keychain that is locked is waited out for up to 10 minutes, not crashed on.

If you see “found saved credentials but no master key that decrypts them”:

1. Unlock your login keychain (open Keychain Access, or log out and back in) and restart Postwright. Choose Always Allow if a prompt appears.
2. Did you move or rename the data folder? Move it back, or copy the matching master.key into it.
3. If the folder holds a master.key from another install, delete that file.
4. Restore the Keychain item from a backup, such as Time Machine.
5. Last resort: clear only the saved credentials and sign in to each connection again. Your posts, schedule, and settings stay; links already emailed (unsubscribe, preferences, confirmation) stop working. Never delete or move the database itself. The exact steps are in the app’s own configuration reference, and if you are unsure, contact support first.