SocialHandoff help center and docs
Step-by-step guides for connecting accounts and agents, approving posts, and running your own server.
Getting started
Getting started: your first approved post
Set up a workspace, connect one social account, point an agent at it, and approve the first draft. Every post an agent writes waits for you before it publishes.
Importing posts from Postiz
Bring queued Postiz posts across as drafts, keeping future schedule dates. Reconnect accounts in SocialHandoff, then approve the imported posts.
Troubleshooting failed, stuck, and rejected posts
Most problems fall into a few groups: a guardrail rejected the draft, the workspace is paused, a network refused the post, or a key or URL is wrong.
Networks
How to connect an X account
Link an X account with OAuth 2. Agents can then draft posts and reply-chain threads for X, and you approve each one before it publishes.
How to connect a LinkedIn account
Link LinkedIn with OAuth so agents can draft LinkedIn posts. Each publish is one post with up to one image and alt text.
How to connect a Bluesky account
Bluesky connects with an app password, not OAuth. No developer app is needed, on the hosted app or on your own server.
How to connect a Mastodon account
Mastodon works with any public instance. Paste an access token you create, or let the app register itself on your instance.
Agents
Connect an agent with MCP
Any MCP client can draft posts through SocialHandoff: locally over stdio with npx, or remotely over streamable HTTP at /mcp with a bearer key.
Agent keys and permission scopes
Give every agent its own key, limited to the networks and actions it needs. Keys are stored as hashes and can be revoked without touching other agents.
Brand memory: teach agents your voice
Brand memory holds the voice rules, products, and banned topics every agent reads before it drafts. You can rewrite drafts in that voice with your own model key.
Approvals & safety
Approving, editing, and rejecting drafts
Every agent draft waits in the approval inbox. You can approve now or for a time, edit inline, request changes, or reject with a reason.
The trust ladder for agent autonomy
A new agent can only draft. After enough clean approvals, you can let it publish on its own on networks you choose. One guardrail failure puts it back.
Guardrails for AI-drafted posts
Guardrails check every draft before it reaches your inbox, and again before it publishes. Some reject a draft outright; others flag it for you.
Pause all agents with the kill switch
The kill switch pauses the whole workspace: agents cannot schedule, and posts already in the queue are held until you resume.
The audit log and how to verify it
Every draft, edit, approval, publish, policy change, and pause is recorded in an append-only log. Each row is chained to the one before it, so tampering shows.
Automation
Turn GitHub releases into post drafts
Publish a GitHub release and get a draft for X, LinkedIn, Bluesky, or Mastodon that cites the release notes. You approve it before anything posts.
Outbound webhooks for published, failed, and pending posts
Get a signed HTTP call when a post publishes, fails, or needs approval. Use it to ping Slack, update a tracker, or start another workflow.
The REST API, SDK, and CLI
Everything the app does is available over a REST API with an OpenAPI description, a TypeScript SDK, and a CLI. Agents can also read /llms.txt.
Self-hosting
Account & billing
Let your agents post. Keep the final say.
Connect your first agent in minutes. Every draft waits in your inbox until you approve it.
14 days free. No card required.