![\"Homebrew\"](\"https://img.shields.io/badge/Homebrew-tap-FBB040?logo=homebrew&logoColor=black\"){kind=icon}
\n ![\"npm\"](\"https://img.shields.io/npm/v/@apoorvdarshan/crossposter?logo=npm\")
\n\n
\n ![\"Crossposter](\"https://crossposter.apoorvdarshan.com/assets/logo-crossposter.png\"){kind=logo}
\n
\n Private crossposting dashboard for your own social accounts.
\n Compose once, attach media, publish now, or schedule posts from a local/self-hosted server.\n
\n Supported Channels\n · Run Locally\n · Provider Setup\n · Security\n
\n\n---\n\n## Overview\n\nCrossposter is a small local/self-hosted publishing dashboard. It is built for\npersonal use: no database, no queue service, and no multi-user product layer.\nPosts can be sent immediately with **Publish now** or saved to the local\nscheduler for a later time.\n\nThis is intentionally not a Postiz-style stack. Full scheduling products usually\nneed services such as Postgres, Redis, queues, workers, and separate background\njobs. Crossposter keeps the surface area narrow so it can run on your Mac, a\nsmall VPS, Render, or a simple Node host. Scheduled posts publish only while\nthat server process is running.\n\n## Unofficial Integrations And Platform Terms\n\nCrossposter includes a mix of official APIs and local unofficial integrations.\nX / Twitter, Instagram, YouTube, Pinterest, and Hacker News may use\ncookies, local sessions, private APIs, third-party tools, or normal web submit\nflows.\n\nUse Crossposter only with accounts, pages, boards, channels, and profiles you\nown or are authorized to manage. You are responsible for each platform's API\nterms, automation rules, rate limits, account policies, and content policies.\nUnofficial integrations can break when platforms change and may trigger login\nchallenges, rate limits, failed posts, or account restrictions.\n\n## Supported Channels\n\n| Channel | Current support |\n| --- | --- |\n| X / Twitter | Local posting through a dedicated, isolated headless browser (one-time login, like Instagram), with text, images, GIFs, and video |\n| LinkedIn | Personal profile posts and approved Page posts, with optional images or MP4 video |\n| Bluesky | Text posts and local image media |\n| Mastodon | Text posts and local media |\n| Instagram | Unofficial local media publishing through an isolated headless browser session |\n| YouTube | Unofficial local video uploads through YouTube.js/InnerTube cookies |\n| Dev.to | Markdown articles |\n| Pinterest | Unofficial local Pin uploads through `py3-pinterest` session folders |\n| Hacker News | Personal link/text submission through HN's normal form flow |\n| Nostr | Kind-1 text notes published to configured relays |\n| Dribbble | Official OAuth shot uploads through the Dribbble API |\n\n## Features\n\n- Dashboard composer for title, body text, channel selection, and media upload\n- Multiple account profiles per provider, selected as publish targets on the dashboard\n- Inline Schedule draft control for local timed posting\n- Scheduler calendar for scanning queued posts by month and reviewing posts by day\n- Scheduler page controls for editing timing and discarding queued or failed posts\n- Per-platform profile configuration from the UI\n- Local config saved to `poster.config.local.json`\n- Local publish history\n- Local media upload storage in `.poster-uploads`\n- Image conversion/compression with quality and target size controls\n- Dribbble crop tool for 400x300 or 800x600 shot images\n- Video conversion/compression to MP4 for supported channels\n- Platform preflight warnings before publishing\n- Per-platform title, post, and media limits shown only when a selected draft\n exceeds the limit\n- Light/dark/system theme controls\n- macOS auto-start service for `http://localhost:2004`\n\n## Scheduled Posting\n\nUse **Schedule draft** next to **Publish now** on the Dashboard. It opens a\nlocal date/time popup next to the button you clicked, then saves the post to\n`poster.config.local.json`.\n\nManage the queue from:\n\n```text\nhttp://localhost:2004/scheduled\n```\n\nThe Scheduler page lets you:\n\n- view the current month calendar by default\n- click a calendar date to review posts scheduled for that day\n- edit the scheduled timing\n- discard queued or failed posts\n- review target channels, media, and last publish errors\n\nWhen a scheduled post publishes successfully, it is added to local publish\nhistory and removed from the Scheduler queue.\n\nThe scheduler is local/self-hosted. The Crossposter server must be running at\nthe scheduled time:\n\n- `npx @apoorvdarshan/crossposter@latest` pings the scheduler every 30 seconds\n- the macOS auto-start service keeps `http://localhost:2004` alive after login\n- on Render or a VPS, keep the Node service running with persistent disk\n\nIf the server is offline when a post is due, it will publish the next time the\nserver starts and the scheduler tick runs.\n\n## Posting From An Agent (HTTP API)\n\nCrossposter exposes a small local HTTP API (`/api/health`, `/api/config`,\n`/api/media`, `/api/publish`, `/api/scheduled`, `/api/draft`) so an external\nagent or script can publish, schedule, or stage drafts (including media) without\nthe UI. See [`AGENT_POSTING.md`](AGENT_POSTING.md) — a self-contained guide you\ncan hand to an agent so it can post through your running server on\n`http://localhost:2004`.\n\n## Run Locally\n\n### Recommended: Homebrew\n\nInstall the production build and launch it locally:\n\n```bash\nbrew install apoorvdarshan/tap/crossposter\ncrossposter\n```\n\nHomebrew keeps the application code under its managed prefix. Crossposter keeps\nconfig, uploads, browser sessions, schedules, and history separately in\n`~/Library/Application Support/Crossposter` on macOS, so upgrading or\nuninstalling the Formula does not erase local publishing data.\n\nStart it automatically after login:\n\n```bash\nbrew services start crossposter\n```\n\nUpgrade without changing local data:\n\n```bash\nbrew upgrade apoorvdarshan/tap/crossposter\nbrew services restart crossposter\n```\n\n### npx Launcher\n\nUse the npx path when you want Crossposter running on localhost without cloning\nthe repo or installing a global binary:\n\n```bash\nnpx @apoorvdarshan/crossposter@latest\n```\n\nThe launcher opens or prints the local URL:\n\n```text\nhttp://localhost:2004\n```\n\nRun the command from the folder where you want Crossposter data to live. The\nlocal config, uploads, schedule, and history stay in that folder.\n\n```bash\nmkdir -p ~/Crossposter\ncd ~/Crossposter\nnpx @apoorvdarshan/crossposter@latest\n```\n\nIf you already have `poster.config.local.json` or `.poster-uploads`, run npx\nfrom that same folder so the app uses your existing data.\n\nFor a persistent command:\n\n```bash\nnpm install -g @apoorvdarshan/crossposter\ncrossposter\n```\n\nFor development from the Git repo:\n\n```bash\nnpm install\nnpm run dev:local\n```\n\n### Update The Local Package\n\nHomebrew installations are updated only through Homebrew. npm and npx\ninstallations check npm on startup by default and can also update from Settings\n> Version & Updates, or run:\n\n```bash\nnpx @apoorvdarshan/crossposter@latest\n```\n\nTurn off startup update checks from Settings by setting **Auto-update on launch**\nto off.\n\n### Change The Local Port\n\nSet `POSTER_LOCAL_PORT` in Settings or `poster.config.local.json`, then restart\nthe local service.\n\n```bash\nPOSTER_LOCAL_PORT=2080 npx @apoorvdarshan/crossposter@latest\n```\n\n### macOS Auto-Start\n\nFor a Homebrew installation, use Homebrew's managed service:\n\n```bash\nbrew services start crossposter\n```\n\nFor an npm or npx installation, install Crossposter's launchd service:\n\n```bash\ncrossposter install-service\n```\n\nYou can also control it from:\n\n```text\nSettings > Local Settings > Auto-start\n```\n\nTurn on **Always restart localhost** and macOS will keep\n`http://localhost:2004` available after login/restart.\n\nUse a custom port once:\n\n```bash\ncrossposter install-service --port 2080\n```\n\nRemove the service:\n\n```bash\nbrew services stop crossposter\n# npm/npx installation:\ncrossposter uninstall-service\n```\n\n## Configuration\n\nThe app reads configuration from:\n\n1. `poster.config.local.json`\n2. environment variables\n3. defaults in the code\n\n`poster.config.local.json` is gitignored. It is the preferred place for local\ntokens and profile settings because it is managed by the Settings UI.\n\nFor public/self-hosted deployments, set:\n\n```text\nPOSTER_REQUIRE_ADMIN_PASSWORD=true\nPOSTER_ADMIN_PASSWORD=strong-password-here\n```\n\n## Provider Setup\n\n### X / Twitter\n\nX publishing drives a **dedicated, isolated headless browser** — the same\napproach as Instagram. You log in once in a separate window, the session is\nsaved into an isolated per-profile folder (never your personal Chrome), and\nposts are then typed and sent through **X's own web composer**, headlessly.\nBecause X's own frontend generates and signs the request, this avoids the\nhand-crafted-API rate-limit pattern that direct API clients trip.\n\nIt reuses the same browser engine as Instagram. Install it once in Terminal with\n`crossposter install-instagram-browser-deps` (or\n`./scripts/install-instagram-browser-deps.sh` from the Git repo).\n\nRequired field:\n\n```text\nX_BROWSER_PROFILE_DIR\n```\n\nOptional fields:\n\n```text\nX_BROWSER_HEADLESS\nX_BROWSER_TIMEOUT_MS\nX_PYTHON_COMMAND\nX_PREMIUM_LONG_POSTS\n```\n\nSet `X_BROWSER_PROFILE_DIR` to a unique folder per X account, for example\n`.x-browser/apoorvdarshan`. Keep `X_BROWSER_HEADLESS=true` so posting runs\ninvisibly; set it to `false` to watch the browser if X changes its layout or\nshows a checkpoint. Click **Log in to X** in Settings once to sign in (including\n2FA); the session is reused for every post after.\n\nAfter clicking Post, Crossposter verifies X's own `CreateTweet` response and\ncaptures the new status URL. If neither the response nor the success UI can be\nobserved, the result is marked **check** rather than failed; inspect the profile\nbefore retrying because the post may already be live.\n\nSet `X_PREMIUM_LONG_POSTS=true` only for Premium accounts. It raises the X text\nlimit from 280 to 25,000 characters (X Premium long posts) and the video size\nlimit from 512 MB to 16 GB. Free accounts keep the 280 character limit.\n\nMedia limits:\n\n- photos: 5 MB\n- GIFs: 15 MB\n- video: 512 MB, or 16 GB when `X_PREMIUM_LONG_POSTS=true`\n\nUse this only for accounts you control, and keep posting occasional and\nhuman-paced. X is strict about automation and can still challenge, limit, or\nlock accounts for suspicious or high-volume activity.\n\n### LinkedIn\n\nLinkedIn can be connected from the local Settings page after creating a LinkedIn\ndeveloper app.\n\nAdd this callback URL in the LinkedIn app Auth tab:\n\n```text\nhttp://localhost:2004/api/auth/linkedin/callback\n```\n\nFor personal profile posting:\n\n1. Enable **Share on LinkedIn**.\n2. Enable **Sign In with LinkedIn using OpenID Connect**.\n3. Use scopes:\n\n```text\nopenid profile w_member_social\n```\n\n4. Add the LinkedIn client ID and secret in Crossposter.\n5. Click **Connect LinkedIn** from Settings.\n\nThe local callback saves `LINKEDIN_ACCESS_TOKEN` and a personal\n`LINKEDIN_AUTHOR_URN` automatically.\n\nFor LinkedIn Page posting:\n\n1. Create or choose the LinkedIn Page that owns the developer app.\n2. Make sure the signed-in member is an admin or content admin for that Page.\n3. Make sure the LinkedIn app has access to `w_organization_social`.\n4. Use scopes:\n\n```text\nopenid profile w_member_social w_organization_social\n```\n\n5. Click **Connect LinkedIn**.\n6. Replace `LINKEDIN_AUTHOR_URN` with the Page author:\n\n```text\nurn:li:organization:YOUR_PAGE_ORG_ID\n```\n\nValid author examples:\n\n```text\nurn:li:person:YOUR_PERSON_ID\nurn:li:organization:YOUR_PAGE_ORG_ID\n```\n\n`LINKEDIN_VERSION` defaults to `202605`.\n\nLinkedIn local media upload supports JPG, PNG, and GIF images, plus MP4 videos\nbetween 75 KB and 500 MB. Unsupported local media is rejected before publishing.\n\n### Bluesky\n\nCreate a Bluesky app password. Do not use your main account password.\n\nRequired fields:\n\n```text\nBLUESKY_IDENTIFIER\nBLUESKY_APP_PASSWORD\n```\n\n`BLUESKY_IDENTIFIER` should be your handle without `@`, for example:\n\n```text\nname.bsky.social\n```\n\n### Mastodon\n\nCreate an application/access token from your Mastodon instance settings.\n\nRequired fields:\n\n```text\nMASTODON_INSTANCE\nMASTODON_ACCESS_TOKEN\n```\n\nExample instance:\n\n```text\nhttps://mastodon.social\n```\n\nMastodon post text is limited to 500 characters.\n\n### Instagram\n\nInstagram publishing is unofficial local posting through a dedicated, isolated\nheadless browser with a one-time login per account, using its own profile folder\n(separate from your own Chrome profile). It reuses your real signed-in session\n(no stored password) and posts invisibly. It is still automation, not an official\nAPI, so use it for accounts you own and keep posting human-paced.\n\nIt prefers your installed **Google Chrome** (run in a separate, isolated profile),\nfalling back to Playwright's bundled Chromium when Chrome is not installed.\n**Video (MP4/MOV) uploads require Google Chrome** — the bundled Chromium lacks the\nH.264/AAC codecs Instagram's web uploader needs to read video, so it rejects MP4s\nwith \"could not be read by your browser\". Image posts work on either.\n\nInstall the browser engine once (Playwright + Chromium):\n\n```bash\ncrossposter install-instagram-browser-deps\n# or, from a Git clone:\n./scripts/install-instagram-browser-deps.sh\n```\n\nFields:\n\n```text\nINSTAGRAM_BROWSER_PROFILE_DIR # unique per account, e.g. .instagram-browser/apoorvdarshan\nINSTAGRAM_BROWSER_HEADLESS # true (invisible posting); false to watch the browser\nINSTAGRAM_BROWSER_TIMEOUT_MS # login wait + publish step timeout, default 180000\nINSTAGRAM_PYTHON_COMMAND # optional; defaults to .venv/bin/python, then python3\n```\n\nAdd one profile per Instagram account, give each a unique browser profile\nfolder, then click **Log in to Instagram** in Settings. A real browser window\nopens once so you can sign in (including any 2FA or checkpoint); the session is\nsaved into that folder and reused headlessly afterward. To add another account,\nadd another profile with its own folder and log in again. If Instagram changes\nits create-post layout and a publish fails, set `INSTAGRAM_BROWSER_HEADLESS` to\n`false` to watch the flow.\n\nAfter clicking Share, Crossposter verifies Instagram's media-configure response\nand uses its shortcode as the post/reel URL when available. If confirmation\ncannot be observed, the result is marked **check** and must be verified on the\nprofile before any retry.\n\nSupported media:\n\n- image: JPG, PNG, or WebP up to 8 MB\n- video: MP4 or MOV up to 300 MB\n\n### YouTube\n\nYouTube publishing is unofficial local upload through YouTube.js and InnerTube.\nCrossposter can read cookies from a signed-in Chrome profile at publish time.\n\nTitle becomes the YouTube video title. Post text becomes the description.\n\nRequired field:\n\n```text\nYOUTUBE_COOKIE_SOURCE\n```\n\nOptional fields:\n\n```text\nYOUTUBE_CHROME_PROFILE\nYOUTUBE_COOKIE\nYOUTUBE_PRIVACY\nYOUTUBE_TIMEOUT_MS\n```\n\n`YOUTUBE_PRIVACY` defaults to `PUBLIC`. Common video formats are accepted up to\n256 GB or 12 hours.\n\n### Dev.to\n\nCreate an API key from Dev.to account settings.\n\nRequired field:\n\n```text\nDEVTO_API_KEY\n```\n\nDev.to publishing expects a title and Markdown body text.\n\n### Pinterest\n\nPinterest publishing is unofficial local posting through `py3-pinterest`.\nCrossposter stores one session folder per Pinterest profile.\n\nRequired fields:\n\n```text\nPINTEREST_EMAIL\nPINTEREST_PASSWORD\nPINTEREST_USERNAME\nPINTEREST_BOARD_ID\nPINTEREST_CRED_ROOT\n```\n\nOptional fields:\n\n```text\nPINTEREST_SECTION_ID\nPINTEREST_ALT_TEXT\nPINTEREST_PYTHON_COMMAND\nPINTEREST_TIMEOUT_MS\nPINTEREST_HEADLESS\n```\n\nInstall Python dependencies:\n\n```bash\ncrossposter install-pinterest-deps\n# or, from a Git clone:\n./scripts/install-pinterest-deps.sh\n```\n\nPinterest requires a board ID because every Pin belongs to a board. Title is\nlimited to 100 characters and description/post text is limited to 800\ncharacters.\n\nSupported media:\n\n- image: JPG, PNG, GIF, or WebP up to 20 MB\n- video: MP4 or MOV up to 100 MB\n\n### Hacker News\n\nHacker News has no official write/submit API. Crossposter uses unofficial\npersonal automation through Hacker News' normal login and submit form flow.\n\nRequired fields:\n\n```text\nHACKERNEWS_USERNAME\nHACKERNEWS_PASSWORD\n```\n\nOptional field:\n\n```text\nHACKERNEWS_COOKIE\n```\n\nHow publishing works:\n\n- Title is required.\n- Link is optional. If set, it is submitted as Hacker News' `url` field.\n- Post text is optional for Hacker News. If set, it is submitted as Hacker News'\n `text` field.\n- Leave Link empty to submit a discussion/text post.\n- For non-Hacker News channels, Crossposter still requires Post text.\n- Local media is ignored.\n- A saved browser cookie can be used before password login.\n\nUse this only for your own Hacker News account and normal personal submissions.\nDo not use it for spam, vote/comment solicitation, or bulk promotional posting.\nIf Hacker News requires browser validation or CAPTCHA for the login, Crossposter\nwill fail and you must submit manually.\n\n### Nostr\n\nNostr publishes signed kind-1 text notes directly to relay WebSocket URLs.\n\nRequired fields:\n\n```text\nNOSTR_PRIVATE_KEY\nNOSTR_RELAYS\n```\n\n`NOSTR_PRIVATE_KEY` can be an `nsec...` key or a 64-character hex private key.\nUse a dedicated Nostr key if you do not want Crossposter to sign as your main\nidentity.\n\n`NOSTR_RELAYS` is a comma or newline separated list of relays:\n\n```text\nwss://relay.example.com,wss://another-relay.example\n```\n\nLocal media is ignored for Nostr. Paste public image/video links into the post\nbody if you want Nostr clients to render media previews.\n\n### Dribbble\n\nDribbble publishing uses the official Dribbble API. Create a Dribbble API app\nand connect the profile from Settings.\n\nCallback URL:\n\n```text\nhttp://localhost:2004/settings/socials/dribbble/callback\n```\n\nRequired after OAuth:\n\n```text\nDRIBBBLE_ACCESS_TOKEN\n```\n\nSetup fields:\n\n```text\nDRIBBBLE_CLIENT_ID\nDRIBBBLE_CLIENT_SECRET\nDRIBBBLE_OAUTH_SCOPES\n```\n\nOptional fields:\n\n```text\nDRIBBBLE_TAGS\nDRIBBBLE_TEAM_ID\nDRIBBBLE_LOW_PROFILE\n```\n\nDribbble requires a title and a local JPG, PNG, or GIF shot image that is\nexactly 400x300 or 800x600 and no larger than 8 MB. Crossposter can crop\nnon-GIF images before publishing.\n\n## Local Media Conversion\n\nThe composer can convert and compress media before publishing:\n\n- images are converted to JPG output with quality, target size, and estimated size\n- videos are transcoded to MP4 with quality and target size controls\n- platform warnings offer conversion only when conversion can fix a selected\n channel's media problem\n- Dribbble image warnings can open a cropper that outputs a valid 800x600 JPG\n\n## Static Website\n\nThe `web/` folder contains a standalone static docs website with overview,\nquickstart, provider setup, limits, privacy, and terms sections. It is intended\nfor a domain such as:\n\n```text\ncrossposter.apoorvdarshan.com\n```\n\nLive site:\n\n```text\nhttps://crossposter.apoorvdarshan.com\n```\n\nThe static site is deployed as a Cloudflare Worker with static assets:\n\n```bash\ncd web\nnpm install\nnpm run build\nnpx wrangler dev\nnpx wrangler deploy\n```\n\nCloudflare Workers Builds watches `web/*` on `main`, runs `npm run build` from\n`web/`, and deploys with `npx wrangler deploy`. Wrangler publishes `web/dist/`\nand routes `crossposter.apoorvdarshan.com` to the Worker.\n\nFiles:\n\n```text\nweb/index.html\nweb/assets/logo-crossposter.png\nwrangler.jsonc\n```\n\nPrivacy and terms are published inside `web/index.html` so the static website is\nthe canonical policy page.\n\n## Deploy\n\n### Vercel\n\n```bash\nvercel\n```\n\nSet environment variables in Vercel Project Settings. At minimum:\n\n```text\nPOSTER_ADMIN_PASSWORD\nPOSTER_REQUIRE_ADMIN_PASSWORD=true\n```\n\nThen add provider credentials only for the channels you want to use.\n\n### Render Or VPS\n\nRender or a self-hosted Node server can run the same app. Persistent disk is\nrecommended if you want uploaded media and local publish history to survive\nrestarts.\n\n## Security\n\nCrossposter is private by convention, not a full multi-user auth system.\n\nFor local-only use:\n\n```text\nPOSTER_REQUIRE_ADMIN_PASSWORD=false\n```\n\nBefore exposing it publicly:\n\n- set `POSTER_REQUIRE_ADMIN_PASSWORD=true`\n- use a strong `POSTER_ADMIN_PASSWORD`\n- keep `poster.config.local.json` private\n- keep `.instagram-sessions`, `.instagram-browser`, `.pinterest-sessions`, and\n `.poster-uploads` private\n- never commit API keys, access tokens, refresh tokens, app secrets, browser\n cookies, session files, or platform passwords\n- only connect accounts, pages, and profiles you own or are authorized to manage\n\n## Contact And Support\n\n- Email: apoorvdarshan@gmail.com\n- Email: ad13dtu@gmail.com\n- X: https://x.com/apoorvdarshan\n- Report an issue: https://github.com/apoorvdarshan/crossposter/issues/new\n- Request a feature: https://github.com/apoorvdarshan/crossposter/issues/new\n- View open issues: https://github.com/apoorvdarshan/crossposter/issues\n\nDo not post API keys, tokens, app secrets, or private account details in public\nissues.\n\n## Star History\n\n\n![\"Crossposter](\"https://crossposter.apoorvdarshan.com/api/star-history.svg?theme=dark&v=3\")
\n