← Dashboard

CAPTCHA when the API runs on Ubuntu without a display

Automated headless Chromium cannot solve interactive CAPTCHAs for you. This app pauses tasks as waiting_captcha and shows a screenshot in the dashboard. On a headless server, you have three practical options:

1) Recommended: manual submit from your own browser

1. Open the task URL (shown in the Tasks / CAPTCHA tabs) in Chrome on your laptop or phone.
2. Fill the form and complete the CAPTCHA yourself, then submit the form on the real site.
3. In the dashboard, use “Manual submit” for that task (or call POST /api/tasks/{id}/manual-submit with {"confirm": true}).

The task becomes submitted_manual, the URL is recorded in dedupe, and your campaign stats treat it as a successful submission.

2) Headed Chromium on the server (virtual display)

Install a virtual framebuffer and optionally VNC so a real window exists:

sudo apt install -y xvfb x11vnc

Example: run Chromium inside Xvfb and connect with VNC (advanced; lock down firewall).

Set CAPTCHA_SOLVE_HEADED=true only if a display is available to that process (e.g. DISPLAY=:99 after starting Xvfb).

3) Remote debugging (expert)

Set PLAYWRIGHT_LAUNCH_ARGS in .env, e.g. Chromium flags for remote debugging on 127.0.0.1 only, then SSH port-forward from your workstation. Never expose debugging ports to the public internet.

Windows workstation

Set CAPTCHA_SOLVE_HEADED=true when running the API locally: the resume flow can open a visible browser window after you click “Solved”.