How to do it
- Open your instance's development settings On your Mastodon instance, go to Preferences, then Development, and choose New application.
- Create the application Give it a name and grant the write:statuses and write:media scopes. Save it.
- Copy the access token Open the new application and copy Your access token.
- Add the connection In Connections, choose Add connection, then Mastodon. Enter the instance URL, such as https://mastodon.social, and paste the token.
- Grant agents access Tick Mastodon on each agent key that should draft for this account.
What Mastodon publishing supports
- Posts checked against a 500-character limit by default. Any link counts as 23 characters, like on X.
- Threads published as reply chains.
- Up to 4 attachments with alt text. Media is processed asynchronously, and SocialHandoff waits for processing before posting.
- An
Idempotency-Keyheader on every status, so a retried publish never creates a duplicate.
Instance requirements
The instance must be reachable on the public internet. Loopback and private-network addresses are refused. Self-hosted servers can allow them with SOCIALHANDOFF_ALLOW_PRIVATE_URLS=1, which is meant for testing only.
Content warnings and visibility
Posts go out with your account's default visibility. Check that default in your Mastodon preferences before you let agents draft for the account.
Revoking access
Delete the application in your Mastodon development settings to revoke the token instantly, then remove the connection in SocialHandoff.
The Mastodon scheduling guide and the fediverse glossary entry have more on posting to Mastodon.
Frequently asked questions
Which Mastodon instances work?
Any instance reachable on the public internet that exposes the standard Mastodon API. Some other fediverse servers with a compatible API may also work, but they are not tested.
My instance allows more than 500 characters. Can I use them?
Drafts are checked against 500 characters by default, which is safe on every instance. Keep longer text as a thread.
Can a retry post the same toot twice?
No. Every status is sent with an idempotency key, so the instance ignores a repeat of the same request.