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.

By the end of this guide you will have a fully working Webhood instance running on your own machine, a configured scanner connected to the backend, and a completed URL scan with a screenshot, HTML capture, and network trace you can inspect in the UI. The entire process takes under 10 minutes on any host that meets the prerequisites below.
Do not expose the PocketBase admin panel (/_/) to the public internet in production. The Kong gateway does not proxy that path by default, but if you bind the backend container port directly or use a reverse proxy that exposes it, restrict access with firewall rules or HTTP basic auth at the reverse-proxy level.

​
Steps

1

Install Prerequisites

Webhood requires:
  • Docker Engine 20+ — Install Docker Engine
  • Docker Compose v2 — bundled with Docker Desktop; on Linux servers install the docker-compose-plugin package
Verify both are available:
docker --version
docker compose version
2

Clone the Repository

git clone https://github.com/webhood-io/webhood.git && cd webhood
The repository contains the docker-compose.yml, kong.yml, and an .env.example template that you will configure in the next step.
3

Configure the Environment File

Copy the example file to create your local configuration:
cp .env.example .env
Open .env in your editor. The file looks like this:
############
# Required configuration
############

SCANNER_TOKEN=

############
# Optional configuration
############

EXTERNAL_URL=
# EXTERNAL_URL=http://backend:8090 # for development and testing

# SCANNER_LOG_LEVEL is one of debug, info, warn, error, fatal
SCANNER_LOG_LEVEL=
# SCANNER_NO_PRIVATE_IPS is one of true, false
SCANNER_NO_PRIVATE_IPS=

WEBHOOD_HTTP_PORT=
WEBHOOD_HTTPS_PORT=
WEBHOOD_TLS_CERT=
WEBHOOD_TLS_KEY=

HTTP_PROXY=
HTTPS_PROXY=
NO_PROXY=
VariableRequiredDescription
SCANNER_TOKENYes (after initial setup)Authentication token for the scanner. Leave blank for the first boot; you will generate it from the UI in a later step.
EXTERNAL_URLNoOverride the URL the core UI uses to reach the backend API. Defaults to / (Kong proxy). Only needed when the backend is on a different host or port.
SCANNER_LOG_LEVELNoScanner logging verbosity. One of fatal, error, warn, info (default), debug, trace.
SCANNER_NO_PRIVATE_IPSNoSet to true to block the scanner from visiting URLs that resolve to private/RFC-1918 IP addresses. Useful for preventing SSRF-style scanning of internal hosts.
WEBHOOD_HTTP_PORTNoHost port for HTTP traffic. Defaults to 8000.
WEBHOOD_HTTPS_PORTNoHost port for HTTPS traffic. Defaults to 8443.
WEBHOOD_TLS_CERTNoPath to a TLS certificate file on the host for HTTPS termination at Kong.
WEBHOOD_TLS_KEYNoPath to the matching TLS private key file.
HTTP_PROXY / HTTPS_PROXY / NO_PROXYNoStandard proxy environment variables forwarded to the scanner container for environments that require outbound HTTP proxying.
To run Webhood on a non-default port, set WEBHOOD_HTTP_PORT and/or WEBHOOD_HTTPS_PORT in your .env file before starting the stack. For example, WEBHOOD_HTTP_PORT=9000 moves the UI to http://localhost:9000.
4

Review the Docker Compose Services

The docker-compose.yml defines the four services that make up Webhood:
version: "3.8"

services:
  kong:
    container_name: webhood-proxy
    image: kong:3.5
    restart: unless-stopped
    ports:
      - ${WEBHOOD_HTTP_PORT:-8000}:8000/tcp
      - ${WEBHOOD_HTTPS_PORT:-8443}:8443/tcp
    # ...

  scanner:
    container_name: webhood-scanner
    image: ghcr.io/webhood-io/webhood/scanner:latest
    restart: always
    environment:
      ENDPOINT: http://kong:8000
      SCANNER_TOKEN: ${SCANNER_TOKEN}
    # ...

  core:
    container_name: webhood-core
    image: ghcr.io/webhood-io/webhood/core:latest
    restart: always
    # ...

  backend:
    container_name: webhood-backend
    image: ghcr.io/webhood-io/webhood/backend:latest
    restart: always
    volumes:
      - data:/pb/pb_data
    # ...

volumes:
  data:
Scan data (SQLite database, screenshots, HTML, and trace files) is persisted in the named Docker volume data.
5

Start the Stack

docker compose up -d
Docker will pull the container images and start all four services. The backend runs a health check, and the scanner waits for the backend to be ready before it starts.Confirm all containers are running:
docker compose ps
You should see webhood-proxy, webhood-scanner, webhood-core, and webhood-backend all in a running or healthy state.
6

Open the UI

Navigate to http://localhost:8000 in your browser (or substitute the hostname and port you configured).The first time you open Webhood you will be prompted to create an administrator account. Complete the registration form to set your admin email and password.
7

Create a Scanner and Copy the Token

The scanner container needs an API token to authenticate with the backend. Generate one from the UI:
  1. Click Settings in the left sidebar.
  2. Open the General tab.
  3. Use the dropdown to create a scanner instance and give it a name.
  4. Once created, select the scanner and click Copy token (or refresh the token if needed) to copy the SCANNER_TOKEN value to your clipboard.
8

Set SCANNER_TOKEN and Restart the Scanner

Paste the copied token into your .env file:
SCANNER_TOKEN=your_token_here
Then restart only the scanner container to pick up the new value:
docker compose restart scanner
The scanner will authenticate with the backend and begin listening for new scan jobs. You should see a log line indicating a successful realtime subscription:
docker compose logs scanner --follow
9

Submit Your First URL

Return to http://localhost:8000, paste a URL into the scan input field, and click Scan.The scanner picks up the job immediately via realtime subscription (or within 10 seconds via the polling fallback). Once complete, the scan result page shows:
  • Screenshot — full-page capture of the rendered page
  • HTML — the DOM as rendered by the browser
  • Trace — all HTTP requests and responses with headers, status codes, and host IPs
  • Details — request headers, links found on the page, and other metadata
  • Metadata — timing information (initiated, started, finished, duration) and scanner configuration

​
Next Steps

Build docs developers (and LLMs) love

Get started for freeTalk to us