Install & setup

• A Mac with Apple silicon (M1 or later), macOS 14 or newer. The installer bundles its own Node.js runtime, so there’s nothing to install first.
• A folder for your content. Any folder works: Obsidian, iA Writer, VS Code, or plain Finder. Postwright watches it.
• For video: ffmpeg with caption support (brew install ffmpeg-full). For phone shorts, a speech-to-text engine too, either installed locally or through OpenAI (see Phone shorts). The setup’s system check tells you what’s missing.
• Git, if you’ll publish a blog through the Git path on Pro (see How publishing works).

1. Your license key arrives by email, for free Studio as well as Pro and Team. Paste it on your account page and download the .pkg installer.
2. Open it and follow the prompts. It installs for your user account only, so no admin password is needed.
3. When it finishes, your browser opens Postwright at http://127.0.0.1:8002, ready for setup.

Postwright runs as a background service on your Mac. It starts again after a restart and recovers from crashes on its own. It checks for new versions once a day and shows a banner when one is out; it never installs updates by itself.

The first screen asks you to choose an admin password. A one-time setup code protects this step so that no web page can set the password before you do. The installer opens your browser with the code already filled in, so normally you just choose a password.

If you open Postwright some other way, the page asks for the setup code. Run this in Terminal and paste the result:

cat "$HOME/Library/Application Support/Postwright/data/setup-token"

The code changes each time Postwright restarts before setup is done, so use the latest one. The file is deleted once your password is set.

After the password, the wizard takes you through these steps. Only the first two are required; you can skip the rest and come back to them later.

1. Content folder. Pick the folder Postwright watches. It creates the folders it needs inside.
2. Your brand. Your brand or show name is the only required field. You can add your name as the creator, your website, who your audience is, voice notes, and a mailing address. The audience description shapes the wording of the titles, descriptions, and posts Postwright drafts; it’s never pasted into your copy. The mailing address is needed before Postwright sends a newsletter or marketing email from its own list (Kit, Mailchimp, Ghost, and Beehiiv use the address kept in your account there instead), and you can add it later.
3. Connect an AI. Paste an Anthropic, OpenAI, or Google key, which is checked live and stored encrypted on your Mac. Or choose Use Claude Code if it’s installed. Skip it and AI drafting stays off; everything else works.
4. Where should posts go? Cards for YouTube, Instagram, LinkedIn, and Telegram, each with a Connect button and its status. YouTube uses your own Google Cloud sign-in client, and LinkedIn opens a browser window for you to sign in. Step-by-step help is in Connections.
5. Phone shorts. Choose the synced folder your phone saves videos into and how to transcribe them: automatic, a local engine, or OpenAI (which uploads the audio). There’s also an optional public media URL for Instagram Reels, which most people leave empty. See Phone shorts.
6. System check. A list of what this Mac has and lacks, with the fix beside each problem: ffmpeg with caption support, a speech-to-text engine, the posting browser, free disk space, whether the content folder can be written, whether the phone inbox can be read, and whether an AI is connected. Re-check runs it again after you fix something. Warnings never stop you. Only an unwritable content folder blocks the next step.
7. Finish. Postwright restarts into the full app with your brand and connections in place.

If your content folder or phone inbox lives in Google Drive, Dropbox, or iCloud, macOS may block Postwright from reading it without telling you. The system check flags this. Allow Postwright in System Settings > Privacy & Security > Files and Folders (or Full Disk Access), then choose Re-check.

Scheduled posts go out only while your Mac is awake and Postwright is running. Without administrator rights, Postwright does three things:

• Keeps an awake Mac awake while a post is due within 15 minutes, and while one is publishing, so an upload isn’t cut off. On battery, macOS honors only the idle-sleep part.
• Catches up when the Mac wakes. Within about 10 seconds of waking it runs the publishing check and logs how long it slept and which posts came due. The usual order still applies, and a bundle far past its slot (6 hours by default) moves to its next open day instead of going out late.
• Checks the sleep setting. The system check warns when your Mac sleeps on its own while plugged in, and names the System Settings switch to change.

Optional: wake the Mac for scheduled posts

The installed app includes an optional Postwright Wake Helper. Turned on, it asks macOS to wake the Mac 2 minutes before each scheduled post, so a Mac that went to sleep still posts on time. It is off until you turn it on, and it is in every tier, Studio included.

What it does:

• Wakes a sleeping Mac before a scheduled post is due, and only for scheduled posts: the ones Postwright publishes by itself. Sequence emails and LinkedIn-scheduled video uploads don’t get wakes.
• Plans the wakes from your schedule, at most 12 at a time and up to 7 days ahead. Posts less than 10 minutes apart share one wake, and a post due in under about 12 minutes needs none, because Postwright already keeps an awake Mac awake for the next 15 minutes.
• Only wakes the Mac. It accepts a list of wake times and nothing else, and it never turns on a Mac that is shut down.

What it doesn’t do:

• A closed laptop with no external display goes back to sleep within seconds of waking, so it can’t post. The helper works with the lid open (or a laptop closed with power, an external display, and an input device attached), on power or on battery, with you signed in. A locked screen is fine.
• After a restart, nothing posts until you log in. With FileVault on, macOS asks for your password before any login, and Postwright runs as you.
• If the helper is off, unapproved, or broken, scheduled posts behave exactly as described above. It never delays a post.

To turn it on: open Settings > Wake for scheduled posts and choose Enable. macOS says a background item was added; approve Postwright Wake Helper in System Settings > General > Login Items & Extensions (the names vary a little between macOS versions), enter an administrator’s name and password when macOS asks, then choose Re-check in Postwright. The status turns On and lists the upcoming wakes. The same status shows in the system check. Disable in the same place cancels the wakes and removes the background item.

The helper is part of the installed app. A source checkout has none, and the setting reads “Available in the installed app”.

Everything runs on your Mac. Your footage, subscriber list, and signed-in posting sessions stay there, and there’s no Postwright server in the middle. Keys go into an encrypted store. What leaves your Mac goes only to services you connected: drafting text to your AI provider, posts to the platforms you publish to, and phone-short audio to OpenAI if you choose it for transcription.