- Python 98.9%
- Dockerfile 1.1%
| .dockerignore | ||
| .gitignore | ||
| bluesky_client.py | ||
| config.example.env | ||
| crosspost.py | ||
| database.py | ||
| docker-compose.yml | ||
| Dockerfile | ||
| main.py | ||
| mastodon_client.py | ||
| README.md | ||
| requirements.txt | ||
Social Media Cross-Poster
A self-hosted application for cross-posting between GoToSocial/Mastodon and Bluesky. Designed to run in a Docker container on your homelab.
Features
- Bidirectional Sync: Automatically cross-post between Mastodon/GoToSocial and Bluesky
- Thread Support: Long posts (>300 chars) are automatically split into threaded posts on Bluesky
- Link Preservation: URLs in GTS/Mastodon posts are preserved when cross-posting to Bluesky
- Media Support: Syncs images and other media attachments
- Flexible Configuration: Choose sync direction (both ways, or one-way only)
- Hashtag Filtering: Optionally sync only posts with specific hashtags
- Duplicate Prevention: Tracks synced posts to avoid duplicates
- Docker Ready: Easy deployment with Docker Compose
- GoToSocial Compatible: Full support for GoToSocial instances via ActivityPub
Prerequisites
- Docker and Docker Compose
- A Mastodon or GoToSocial account with API access
- A Bluesky account with an app password
Quick Start
1. Get the Code
Option A: Clone from Git (if you've forked/hosted this repo)
# Clone to your preferred location
git clone https://github.com/yourusername/social-media-crossposter.git
cd social-media-crossposter
Option B: Download directly
# If you have the code locally, just navigate to it:
cd /path/to/social-media-crossposter
# Or copy/download the files to your homelab apps directory:
cd /path/to/your/homelab/apps
# Copy the project files here
2. Get API Credentials
For Mastodon:
- Log into your instance
- Go to Settings → Development → New Application
- Give it a name (e.g., "Cross-Poster")
- Set scopes:
read:statuses,write:statuses,write:media - Copy the access token
For GoToSocial:
GoToSocial doesn't have a web UI for creating application tokens, so you need to use the API directly with curl:
Step 1: Register your application
curl -X POST https://your-gts-instance.social/api/v1/apps \
-H "Content-Type: application/json" \
-d '{
"client_name": "Cross-Poster",
"redirect_uris": "urn:ietf:wg:oauth:2.0:oob",
"scopes": "read write"
}'
This will return a JSON response with client_id and client_secret. Save these values.
Step 2: Generate an access token
curl -X POST https://your-gts-instance.social/oauth/token \
-H "Content-Type: application/json" \
-d '{
"client_id": "YOUR_CLIENT_ID_FROM_STEP_1",
"client_secret": "YOUR_CLIENT_SECRET_FROM_STEP_1",
"redirect_uri": "urn:ietf:wg:oauth:2.0:oob",
"grant_type": "password",
"username": "your_gts_username",
"password": "your_gts_password",
"scope": "read write"
}'
This will return a JSON response with access_token. This is what you'll use in your .env file.
Example complete flow:
# Step 1: Register app
RESPONSE=$(curl -s -X POST https://gts.example.com/api/v1/apps \
-H "Content-Type: application/json" \
-d '{"client_name":"Cross-Poster","redirect_uris":"urn:ietf:wg:oauth:2.0:oob","scopes":"read write"}')
CLIENT_ID=$(echo $RESPONSE | grep -o '"client_id":"[^"]*' | cut -d'"' -f4)
CLIENT_SECRET=$(echo $RESPONSE | grep -o '"client_secret":"[^"]*' | cut -d'"' -f4)
echo "Client ID: $CLIENT_ID"
echo "Client Secret: $CLIENT_SECRET"
# Step 2: Get access token (replace USERNAME and PASSWORD)
curl -X POST https://gts.example.com/oauth/token \
-H "Content-Type: application/json" \
-d "{
\"client_id\":\"$CLIENT_ID\",
\"client_secret\":\"$CLIENT_SECRET\",
\"redirect_uri\":\"urn:ietf:wg:oauth:2.0:oob\",
\"grant_type\":\"password\",
\"username\":\"your_username\",
\"password\":\"your_password\",
\"scope\":\"read write\"
}"
The final response will include your access_token that you can use in the .env file.
For Bluesky:
- Log into Bluesky
- Go to Settings → App Passwords
- Create a new app password
- Copy the password (you won't see it again!)
3. Configure
Copy the example configuration:
cp config.example.env .env
Edit .env with your credentials:
# Mastodon/GoToSocial Configuration
MASTODON_INSTANCE_URL=https://your-instance.social
MASTODON_ACCESS_TOKEN=your_access_token_here
# Bluesky Configuration
# NOTE: Do NOT include the @ symbol in your handle
BLUESKY_HANDLE=yourhandle.bsky.social
BLUESKY_APP_PASSWORD=your_app_password_here
# Cross-posting Settings
POLL_INTERVAL_SECONDS=300
SYNC_DIRECTION=both # Options: both, mastodon_to_bluesky, bluesky_to_mastodon
# Bootstrap mode: Set to 'true' on first run to mark existing posts as synced WITHOUT posting them
# After first run, set back to 'false' to enable normal cross-posting
BOOTSTRAP_MODE=true
# Optional: Hashtag filter (comma-separated, leave empty to sync all posts)
HASHTAG_FILTER=
# Database
DATABASE_PATH=/data/crosspost.db
Important Notes:
- Bluesky Handle: Use
yourhandle.bsky.socialNOT@yourhandle.bsky.social - No Quotes Needed: Values don't need quotes unless they contain spaces
- GoToSocial Users: Use
read writescopes (not the granularread:statusesformat). See the curl instructions above for generating tokens via API.
4. Run with Docker Compose
First Run (with bootstrap mode to prevent syncing old posts):
# Make sure BOOTSTRAP_MODE=true in .env
docker-compose up -d
docker-compose logs -f # Wait for one sync cycle to complete
docker-compose down
# Edit .env and set BOOTSTRAP_MODE=false
docker-compose up -d
Normal Operation:
docker-compose up -d
To view logs:
docker-compose logs -f
To stop:
docker-compose down
Configuration Options
| Variable | Description | Default | Required |
|---|---|---|---|
MASTODON_INSTANCE_URL |
Your Mastodon/GoToSocial instance URL | - | Yes |
MASTODON_ACCESS_TOKEN |
API access token | - | Yes |
BLUESKY_HANDLE |
Your Bluesky handle | - | Yes |
BLUESKY_APP_PASSWORD |
Bluesky app password | - | Yes |
POLL_INTERVAL_SECONDS |
How often to check for new posts (in seconds) | 300 | No |
SYNC_DIRECTION |
Direction of sync | both | No |
BOOTSTRAP_MODE |
Mark existing posts as synced without posting | false | No |
HASHTAG_FILTER |
Comma-separated hashtags to filter (without #) | - | No |
DATABASE_PATH |
Path to SQLite database | /data/crosspost.db | No |
Sync Direction Options
both: Sync posts in both directions (Mastodon ↔ Bluesky)mastodon_to_bluesky: Only sync from Mastodon to Blueskybluesky_to_mastodon: Only sync from Bluesky to Mastodon
Hashtag Filtering
To only sync posts with specific hashtags:
HASHTAG_FILTER=crosspost,sync,public
This will only sync posts containing #crosspost, #sync, or #public.
Bootstrap Mode (First Run)
IMPORTANT: On first run, you should use bootstrap mode to prevent syncing historical posts.
When you first start the application, it will see all your recent posts (up to 20) as "new" and try to cross-post them. To prevent this:
- Set
BOOTSTRAP_MODE=truein your.envfile - Start the application:
docker-compose up -d - Let it run for one sync cycle (check logs:
docker-compose logs -f) - Stop the application:
docker-compose down - Set
BOOTSTRAP_MODE=falsein your.envfile - Start the application again:
docker-compose up -d
In bootstrap mode, the application will:
- Fetch recent posts from both platforms
- Mark them as already synced in the database
- NOT actually post them to the other platform
After bootstrap mode, only NEW posts will be cross-posted going forward.
How It Works
- The application polls both platforms at regular intervals (default: 5 minutes)
- It checks for new posts from your account
- Posts are checked against the sync database to avoid duplicates
- If configured, posts are filtered by hashtags
- New posts are cross-posted to the other platform
- Media attachments (images) are downloaded and re-uploaded
- The sync status is saved to the database
What Gets Synced
- Original posts (not replies or boosts/reposts)
- Text content (with links preserved)
- Image attachments (up to 4 images)
- Long posts are automatically split into threads when cross-posting to Bluesky
What Doesn't Get Synced
- Replies to other users
- Boosts/reposts
- Polls
- Videos (currently not supported)
Troubleshooting
Check logs
docker-compose logs -f crosspost
Permission issues
If you get database permission errors, create the data directory:
mkdir -p data
chmod 777 data
Posts not syncing
- Check that your API credentials are correct
- Verify the poll interval isn't too long
- Check logs for errors
- Ensure posts aren't filtered by hashtag settings
- Make sure posts aren't replies or boosts
Character limit handling
- Bluesky: 300 characters max
- Mastodon: Usually 500 characters (varies by instance)
- GoToSocial: Usually 5000 characters
GTS → Bluesky: Posts exceeding 300 characters are automatically split into threaded posts with indicators like (1/3), (2/3), (3/3)
Bluesky → Mastodon/GTS: Posts exceeding the instance limit are truncated with "..."
Running Without Docker
If you prefer to run without Docker:
# Install Python 3.11+
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
# Create .env file with your configuration
cp config.example.env .env
# Edit .env with your credentials
# Create data directory
mkdir -p data
# Run
python main.py
Data Persistence
The application uses SQLite to track synced posts. The database is stored in the ./data directory by default, which is mounted as a Docker volume. This ensures:
- Posts aren't duplicated after container restarts
- Sync history is preserved
- You can back up the database for migration
Security Notes
- Keep your
.envfile secure and never commit it to version control - Use app-specific passwords when possible
- The application only needs read and write access to posts, not full account access
- Regular Mastodon/GoToSocial access tokens can be regenerated if compromised
- Bluesky app passwords can be revoked and recreated
- GoToSocial curl authentication: When using curl to generate tokens, your password may be stored in bash history. Consider clearing it afterward (
history -c) or using environment variables instead of typing passwords directly in commands
Limitations
- Only syncs your own posts (not posts from others)
- Doesn't sync replies or boosts/reposts
- Video support not yet implemented
- Poll support not yet implemented
- Existing threads from GTS/Mastodon are synced as individual posts (but long individual posts are threaded automatically)
Contributing
This is a personal project, but suggestions and improvements are welcome!
License
MIT License - feel free to use and modify as needed.
Support
For issues or questions, please check the logs first. Most problems are related to:
- Incorrect API credentials
- Network connectivity
- Platform API rate limits
- Character limit truncation
Acknowledgments
Built with:
- Mastodon.py - Mastodon API client
- atproto - Bluesky/AT Protocol client