Deployment

Worker can run from a Docker image, a release binary, or a local source build. Docker is the usual deployment path when scripts need the CDP browser driver, because the Worker image includes a Chromium runtime.

Docker

Worker images are published to Docker Hub and GitHub Container Registry.

$docker run --rm -p 8080:8080 montferret/worker:2.0.0-rc.31

$docker run --rm -p 8080:8080 ghcr.io/montferret/worker:2.0.0-rc.31

Both commands pin the documented release for repeatable deployments. The release image starts Chromium through the image entrypoint and then starts Worker on port 8080.

Configure the container

The image’s default command starts Chromium and then starts Worker. Use environment variables for most container configuration:

$docker run --rm -p 8080:8080 \$  -e LOG_LEVEL=info \$  -e BODY_LIMIT=10M \$  -e REQUEST_LIMIT=10 \$  montferret/worker:2.0.0-rc.31

If you need to pass flags instead, keep the Chromium startup command:

$docker run --rm -p 8080:8080 montferret/worker:2.0.0-rc.31 \$  /bin/sh -c '/entrypoint.sh & /worker -log-level=info -body-limit=10M -request-limit=10'

Mount a directory and set POLICY_FS_ROOT when scripts need filesystem access:

$docker run --rm -p 8080:8080 \$  -v "$PWD/data:/data:ro" \$  -e POLICY_FS_ROOT=/data \$  montferret/worker:2.0.0-rc.31

Use a read-only mount when scripts only need to read files.

Prebuilt binary

Download v2.0.0-rc.31 from the Worker release page.

Release archives follow the GoReleaser platform naming pattern, such as worker_linux_x86_64.tar.gz, worker_darwin_arm64.tar.gz, or worker_windows_x86_64.zip.

After extracting the archive, place the worker binary on PATH and run:

$worker -version$worker

Local binary deployments need a reachable Chrome or Chromium process when scripts use { driver: "cdp" }.

Build from source

The Worker source is a Go module at github.com/MontFerret/worker. Building v2.0.0-rc.31 requires Go 1.26.5 or later.

$git clone --branch v2.0.0-rc.31 --depth 1 https://github.com/MontFerret/worker.git$cd worker$make compile$./bin/worker -version

The build embeds Worker and Ferret version metadata through linker flags when built by the Makefile or release pipeline.

Chrome dependency

Worker waits for Chrome during startup unless Chrome is disabled with -no-chrome. By default it checks:

http://127.0.0.1:9222

When running outside the Docker image, start Chrome with remote debugging enabled before starting Worker:

$google-chrome --headless --remote-debugging-port=9222$worker

If Chrome runs on another host or port, set -chrome-ip and -chrome-port.

Health checks

Use GET /health for load balancer and orchestration checks.

$curl -i http://localhost:8080/health

Status codes:

The health endpoint returns an empty body and is skipped by Worker rate limiting.

Network and security

Worker binds to 0.0.0.0 on the configured port. Put it behind your normal deployment boundary: a private network, reverse proxy, ingress controller, API gateway, or service mesh.

Worker does not include built-in authentication, authorization, TLS termination, request signing, durable queues, scheduling, or tenant isolation. Add those at the deployment layer when Worker is exposed beyond a trusted network.

Ferret HTTP egress is disabled by default. Prefer an exact host allowlist when deployed scripts need outbound access:

$docker run --rm -p 8080:8080 \$  -e POLICY_HTTP_ALLOWED_HOSTS=api.example.com \$  montferret/worker:2.0.0-rc.31

HTTP_ALLOW_ALL_HOSTS=true allows requests to arbitrary hostnames while retaining the configured timeout, size, redirect, blocked-host, blocked-header, and literal-address policies. Hostnames are not DNS-resolved before policy evaluation, so prefer POLICY_HTTP_ALLOWED_HOSTS for SSRF-sensitive deployments. See Configuration for the complete policy surface.

Use body limits and rate limits for public or shared deployments:

$worker \$  -log-level=info \$  -body-limit=10M \$  -request-limit=10 \$  -request-limit-time-window=60

The historical baseline in the Worker README is 2 CPU and 2 GB of RAM. Browser-backed scripts, large pages, PDF generation, screenshots, and high concurrency may require more.

Next steps