Mastodon Instance Captcha Provider: How to Switch From hCaptcha

If you run a Mastodon instance, you likely use hCaptcha to prevent automated spam account registrations. However, hCaptcha has changed its pricing model and now charges per verification, which can become expensive for larger instances. This article explains how to switch your Mastodon instance from hCaptcha to an alternative captcha provider such as MastoCaptcha or a custom solution. You will learn the exact configuration file edits and environment variable changes needed to complete the switch.

Why Switch From hCaptcha on Your Mastodon Instance

Mastodon uses a captcha provider to verify that new account registrations are made by humans rather than automated scripts. By default, Mastodon integrates with hCaptcha, a privacy-focused alternative to reCAPTCHA. However, hCaptcha changed its pricing model in 2024, introducing a per-verification fee that can cost instance administrators several dollars per thousand verifications. For a medium-sized instance with hundreds of new registrations per day, this cost adds up quickly.

Mastodon also supports other captcha solutions. The built-in alternative is MastoCaptcha, which is a self-hosted captcha system that does not require external API calls. MastoCaptcha generates simple math or text challenges and stores the verification state locally. This eliminates ongoing costs and keeps all user data on your server. You can also disable captchas entirely by setting the provider to none, though this is not recommended for public instances.

To switch providers, you must modify two files on your Mastodon server: the .env.production file and the mastodon.yml configuration file. The exact changes depend on which provider you choose. This guide covers switching to MastoCaptcha and disabling captchas entirely.

Steps to Change the Captcha Provider in Mastodon

Before starting, ensure you have SSH access to your Mastodon server and sudo privileges. You should also back up your current configuration files. The following steps assume you are using a standard Mastodon installation with systemd service files.

Switch to MastoCaptcha

1. Access your Mastodon server
   SSH into your server using a terminal. For example: ssh admin@your-server-ip. Switch to the Mastodon user account: sudo su - mastodon.
2. Open the .env.production file
   Use a text editor like nano: nano /home/mastodon/live/.env.production. Find the line that reads CAPTCHA_PROVIDER=hcaptcha. Change it to CAPTCHA_PROVIDER=mastocaptcha. If the line does not exist, add it at the end of the file. Save the file with Ctrl+O and exit with Ctrl+X.
3. Open the mastodon.yml configuration file
   Run nano /home/mastodon/live/config/mastodon.yml. Locate the production section. Find or add the key captcha_provider and set it to mastocaptcha. The section should look like this:
   production:
captcha_provider: mastocaptcha
   Save and exit.
4. Restart Mastodon services
   Exit the mastodon user session with exit. Run the following commands to restart all Mastodon services:
   sudo systemctl restart mastodon-web
sudo systemctl restart mastodon-sidekiq
sudo systemctl restart mastodon-streaming
5. Test the new captcha
   Open your instance’s registration page in a private browser window. Complete the registration form. You should see a MastoCaptcha challenge instead of an hCaptcha widget. If the captcha does not appear, check the Mastodon logs: journalctl -u mastodon-web -n 50.

Disable Captchas Entirely

1. Edit .env.production
   Open the file as described in the previous method. Change or add CAPTCHA_PROVIDER=none.
2. Edit mastodon.yml
   Open the configuration file and set captcha_provider: none under the production section.
3. Restart Mastodon services
   Run the same three systemctl restart commands as shown above.
4. Verify the change
   Visit your registration page. The captcha section should be absent entirely. New users can register without completing any challenge.

Common Issues After Switching Captcha Providers

MastoCaptcha Does Not Display on the Registration Page

If the MastoCaptcha widget does not appear, the most common cause is a missing or incorrect secret key. MastoCaptcha does not require an external API key, but Mastodon expects a SECRET_KEY_BASE to be present in .env.production. If this key is missing, run RAILS_ENV=production bundle exec rails secret from the Mastodon live directory and add the output as SECRET_KEY_BASE=your-new-key in .env.production. Then restart Mastodon services.

Registration Page Shows an Error After Switching Captcha Providers

A registration error usually indicates a syntax mistake in mastodon.yml. YAML is sensitive to indentation. Ensure the captcha_provider line is indented exactly two spaces under production. Also check that no tabs were used. Run ruby -c /home/mastodon/live/config/mastodon.yml to validate the file syntax. Fix any reported errors, then restart services.

Existing Users Cannot Register After Switching Captcha Providers

This issue occurs if the captcha provider change is not applied to the Sidekiq background worker processes. Restarting only the web service is not enough. Always restart all three Mastodon services — web, sidekiq, and streaming — as shown in the steps above. If the problem persists, clear the Rails cache: RAILS_ENV=production bundle exec rails tmp:cache:clear from the Mastodon live directory.

Mastodon Captcha Providers: hCaptcha vs MastoCaptcha vs None

Item	hCaptcha	MastoCaptcha	None
Description	External captcha service with per-verification pricing	Self-hosted captcha built into Mastodon	No captcha verification at registration
Cost	Pay per verification after free tier	Free	Free
Data privacy	User data sent to hCaptcha servers	All data stays on your instance	No captcha data collected
Setup complexity	Requires API keys from hCaptcha	No external keys needed	No setup beyond config change
Accessibility	Audio challenge available	No audio challenge	Not applicable

You can now switch your Mastodon instance captcha provider from hCaptcha to MastoCaptcha or disable it entirely. Use the CAPTCHA_PROVIDER environment variable and the captcha_provider key in mastodon.yml to make the change. After switching, test the registration page in a private browser to confirm the new captcha works. For a balance between security and cost, MastoCaptcha is the recommended alternative because it blocks bots without external dependencies. Consider enabling rate limiting on the registration endpoint as an additional layer of protection if you disable captchas.