Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/webhood-io/webhood/llms.txt

Use this file to discover all available pages before exploring further.

Scanner instances are the workers that actually load URLs inside a headless browser and capture the screenshot, HTML, and network trace. Each scanner must be registered in the Webhood UI before it can authenticate to the backend. During registration the UI generates a unique scanner token that the scanner container presents on every connection.

​
Creating a scanner

1

Navigate to Settings → General

Click the gear icon (or your username) in the navigation bar to open Settings, then make sure the General tab is selected. If no scanners have been registered yet, the page displays a prompt to add the first one.
2

Open the action dropdown and create a new scanner

Click the vertical ellipsis (⋮) icon next to the scanner selector to open the Action dropdown, then choose New scanner. A new scanner record is created and selected automatically.
3

Give the scanner a name

In the Name field of the settings form, enter a friendly name such as primary or scanner-eu-1. The name appears in scan metadata and in the scanner selector dropdown, making it easy to identify which worker performed each scan.
4

Copy the generated scanner token

Use the action dropdown again and select Refresh auth token. A dialog displays the newly generated token — copy it now, as it will not be shown again in full after you close the dialog.
5

Set SCANNER_TOKEN and restart

Paste the token into your .env file:
SCANNER_TOKEN=<paste token here>
Then restart the scanner container to apply the change:
docker compose restart scanner
The scanner will connect to the backend and begin polling for pending scans.

​
Action dropdown options

The action dropdown (⋮) on the General settings page exposes the following options for managing scanner instances:
ActionDescription
New scannerCreates a new scanner record and selects it in the UI.
Refresh auth tokenGenerates a new authentication token for the selected scanner and displays it once.
DeletePermanently removes the selected scanner record.
After using Refresh auth token, update SCANNER_TOKEN in your .env file and run docker compose restart scanner immediately. Until you do, the scanner container is presenting a revoked token and cannot pick up any new scans.

​
Scanner configuration fields

Select a scanner in the dropdown on the General tab and use the settings form to adjust its behaviour:
FieldDescription
NameFriendly display name for this scanner instance.
User AgentCustom browser user agent string (e.g. Mozilla/5.0 (Windows NT 10.0; Win64; x64) ...). Leave blank to use the browser default.
LanguageBrowser locale sent in the Accept-Language header (e.g. en-US, zh-CN, ja-JP).
Stealth modeEnables puppeteer-extra-plugin-stealth to configure the browser so it appears more like a real user. Useful for sites that block headless browsers.
Skip cookie promptsLoads the I Don’t Care About Cookies browser extension to automatically dismiss cookie consent banners before the screenshot is taken.
Simultaneous ScansMaximum number of scans the scanner runs at the same time. Defaults to 1 when not set. As a base rule, allow at least 150 MB of memory per simultaneous scan.
Click Save to persist changes. The scanner picks up the updated configuration on its next poll cycle.

​
Connecting to Webhood Cloud

The Use Cloud API toggle connects the selected scanner to cloud.webhood.io for additional capabilities. When enabled, two sub-options appear:
OptionDescription
API TokenYour cloud.webhood.io account token. Required when Use Cloud API is on.
Captcha SolverRoutes captcha challenges encountered during scans through the cloud captcha-solving service. Useful for phishing pages that use captchas to prevent automated analysis.
No data is sent to the cloud unless you explicitly enable Use Cloud API on at least one scanner.

​
Running multiple scanner instances

You can register as many scanner instances as you like. All scanners poll for pending scans and the first available scanner claims each one. This lets you scale horizontally across multiple hosts or geographic locations. To route a specific scan to a particular scanner, pass the scanner’s ID in the scannerId field of the scan options at submission time. This is available via the API; the ScanOptions type is defined as: 
type ScanOptions = {
  scannerId?: string;
  rate?: "slow" | "balanced" | "fast";
  screenshotSize?: { width: string; height: string } | "full";
} | null;
In multi-user deployments where analysts might scan internal infrastructure, set SCANNER_NO_PRIVATE_IPS=true in the scanner container’s environment to block the scanner from resolving and loading URLs that point to private IP address ranges. This prevents server-side request forgery (SSRF) attacks by malicious URLs.

Build docs developers (and LLMs) love

Get started for freeTalk to us