Was this helpful?
How to use sandbox mode
Technical engineer
Introduction
If you're building an integration with 2Captcha and want to test how your app sends tasks and handles responses, the sandbox mode is your go-to debugging companion.
In this mode, captchas appear right in your interface, and you solve them manually. This lets you walk through the entire workflow—from crafting a request to receiving a response—without involving external workers. This guide covers sandbox setup, captcha type limitations, and practical tips for smooth testing.
Heads up: Sandbox mode only becomes available after your first account top-up.
What is sandbox mode?
Sandbox mode is a special account setting on 2Captcha where tasks you submit aren't sent to workers. Instead, they show up in your personal dashboard for you to solve by hand.
Why it's useful:
- No charges — sandbox testing is completely free
- Tasks stay private — they never enter the public worker queue
- You're in control — set your own pace and verify solution quality
- Perfect for debugging — test your logic, validate parameters, and handle errors safely
Important: Once you're done testing, remember to turn sandbox mode off. Otherwise, all new tasks will keep appearing in your interface and won't be processed by workers.
Getting ready
Before flipping the sandbox switch, make sure you have:
- An active 2Captcha account
- A script or app configured to send tasks via the API
- A clear idea of which captcha types you plan to test
If you're testing token-based captchas (the recommended approach), you'll also need:
- The latest version of CaptchaBotRS, downloaded from the official release page
- Access to the worker interface: switch to it via the toggle in the top-right corner of 2captcha.com
- Your worker key, copied from the interface and added to CaptchaBotRS settings
Captcha compatibility check
Not every captcha type works in sandbox mode. Before you start testing, double-check this compatibility table:
| Captcha type | Sandbox support |
|---|---|
| reCAPTCHA v2 / reCAPTCHA Enterprise | Yes |
| hCaptcha | Yes |
| FunCaptcha | Yes |
| GeeTest V3 / V4 | Yes |
| All simple/image captchas | Yes |
| Amazon CAPTCHA | Yes |
| Friendly CAPTCHA | Yes |
| Tencent CAPTCHA | Yes |
| CaptchaFox | Yes |
| reCAPTCHA v3 | No |
| Cloudflare Turnstile | No |
| VK CAPTCHA | No |
| DataDome | No |
Turning on sandbox mode
Enabling sandbox mode is quick and straightforward:
- Head to your account settings
- Toggle Sandbox Mode to On
- Save your changes
Once activated, every new task sent via API with your key will appear in your sandbox interface instead of going to workers.
Pro tip: use CaptchaBotRS for token captchas
For testing token-based captchas like reCAPTCHA v2 or GeeTest, we highly recommend using the CaptchaBotRS desktop app instead of the web interface. It's more stable and developer-friendly.
After installing the app:
- Switch to the worker interface on 2captcha.com
- Copy your displayed worker key
- Paste it into CaptchaBotRS settings
- Launch the app and wait for the connection to establish
Common pitfalls
The most frequent hiccup? Your app hangs while waiting for a captcha to load. This usually means one of two things:
- There's a typo or missing parameter in your API request
- The captcha type you're testing isn't supported in sandbox mode
If you're certain the captcha should work, take a fresh look at the payload you're sending. Try extracting the parameters again and resubmit the task. Small mistakes happen—this is exactly why sandbox mode exists!
Helpful resources
- Account settings — enable sandbox mode
- CaptchaBotRS on GitHub — worker app source and downloads
- API documentation — full reference for methods and parameters
- Support center — get help when you're stuck
Quick pre-flight checklist
- Your 2Captcha account is active
- Sandbox mode is enabled in account settings
- You've identified which captcha types to test—and confirmed they're supported
- CaptchaBotRS is installed (for token-based captchas)
- Your worker key is copied and configured in the app
- Your script sends tasks with correct, validated parameters
- Response handling and error logic are implemented
- Logging is enabled for easier debugging
- Sandbox mode is disabled after testing is complete
Wrapping up
2Captcha's sandbox mode is a powerful, low-risk way to polish your integration—no reliance on external solvers required. You stay in the driver's seat at every step, from sending a task to processing the response, which makes spotting and fixing issues much faster.
Just keep a few things in mind:
- Not all captcha types are supported in sandbox
- No charges apply while testing (but remember: real solving does cost credits)
- Always switch back to production mode when you're done
For token-based captchas, stick with CaptchaBotRS—it delivers the reliability and smooth UX that the web interface can't quite match. And don't forget to check the GitHub repo regularly for updates, bug fixes, and new features.
Once your integration is solid, flip sandbox mode off and let 2Captcha's professional solvers handle the rest. Bypass any captcha, confidently and at scale, with our API.