Postfalcon
Open-source social media scheduler. Write a post once, schedule it on a calendar, and
Postfalcon publishes it on time to Mastodon, Bluesky, Facebook, Instagram, Threads,
Telegram, YouTube, TikTok, Pinterest and LinkedIn (X is built in too, for anyone on a paid
X API plan).
- Calendar with drag-to-reschedule, drafts and a failed-posts view
- Cross-posting: one composer, many channels, with per-platform options (TikTok privacy,
YouTube title and visibility, Pinterest board)
- Recurring posts: daily, weekly or monthly
- Analytics: views, likes, comments and shares pulled back from the platforms that report them
- REST API and an MCP server, so scripts and AI agents (Claude, ChatGPT, Cursor, …)
can plan and publish posts
- Outbound webhooks when a post publishes or fails
- Admin pages for everything an operator needs: who can sign up, invite links, admin
rights, which platforms are offered, setup checks, backups and logs. No SQL needed.
Use the hosted version at postfalcon.co, or run it yourself: this
repository is the whole thing.
Writing a post: one caption and image, sent to several channels at a chosen time.
Analytics: views and engagement pulled back from the platforms that report them.
Accounts: connected channels, and the connect forms for each platform.
Admin → Platforms: switch each platform on or off and see which app keys are still missing.
The account shown is demo data (node scripts/seed-demo.js on a development database).
Install with Docker (recommended)
You need a Linux server (x86 or ARM) and a domain or subdomain whose DNS points at it, with
ports 80 and 443 open. Caddy, included, gets the HTTPS certificate on its own. It uses about
100 MB of memory at rest, so a 1 GB server is enough.
One-line install
curl -fsSL https://postfalcon.co/install.sh | sh
It checks for Docker (and offers to install it), asks for your domain, generates the passwords,
and starts Postfalcon in ~/postfalcon from the published image. It changes nothing else on the
machine and never overwrites an existing install. To read it before running it:
curl -fsSL https://postfalcon.co/install.sh -o install.sh
less install.sh
sh install.sh
When it finishes, open the address it prints and choose Sign up. The first account becomes
the admin, so do this straight away, before anyone else can reach the server.
To update an install made this way:
cd ~/postfalcon
docker compose pull
docker compose up -d
The installer follows latest, which is every change on main. To stay on numbered
releases instead, set POSTFALCON_IMAGE in
.env to ghcr.io/postfalcon/postfalcon:1 (any 1.x release) or :1.0.0 (exactly that release),
then pull as above.
Install by hand, from source
The same thing step by step, building the image on the server instead of downloading it (2 GB of
memory is comfortable while it builds). Install Docker if the server doesn't have it, and let
your user run it:
curl -fsSL https://get.docker.com | sudo sh
sudo usermod -aG docker $USER # then log out and back in
Then get Postfalcon:
git clone https://github.com/postfalcon/postfalcon.git
cd postfalcon
cp .env.example .env
Edit .env (e.g. nano .env) and fill in the REQUIRED section:
| Setting | What to put |
|---|
BASE_URL | https:// + your domain, e.g. https://social.example.com |
DOMAIN | the domain on its own, e.g. social.example.com |
SESSION_SECRET | a random string: run openssl rand -hex 32 and paste it |
POSTGRES_PASSWORD | another random string, for the bundled database |
Then start it (the first start builds the image, which takes a few minutes):
docker compose up -d
docker compose ps # db, app and caddy running; app shows "healthy" after ~30 seconds
Open your BASE_URL: you'll see the log in page. Choose Sign up. The first account
becomes the admin, so do this straight away, before anyone else can reach the server.
Trying it out without a domain, on your own computer or a machine on your network: use
localhost or the machine's IP address (with the installer, enter it as the domain; by hand, use
it for both, e.g. DOMAIN=192.168.1.20 and BASE_URL=https://192.168.1.20). Your browser will warn about the certificate; that's expected,
choose to continue. Most social platforms only accept a real public https:// domain for their
login callbacks, so on a test setup like this only Mastodon, Bluesky and Telegram can be
connected.
To update an install from source:
git pull
docker compose up -d --build
Updates, data and backups (either way)
Database changes are applied automatically when the app starts. Admin → Overview → Version
shows how many commits behind GitHub your server is, and whether every database change is applied.
Your data (database, uploaded media, backups, certificates) lives in Docker volumes, not in the
postfalcon folder, so updating, rebuilding or docker compose down never touches it.
docker compose down -v does delete the volumes; don't use it unless you mean to start over.
This is the beginning of the README. Read the rest at the original. Read the full README ↗
