Wigolo Performance Metrics and Resource Requirements: Optimization Guide

TLDR: Wigolo operates with an idle memory footprint of approximately 30 MiB, scaling to roughly 200 MiB per browser instance, while CPU usage remains low during idle periods but spikes to 30-50% during page rendering or AI inference, making it deployable on modest VPS infrastructure when properly configured with environment caps like MAX_BROWSERS.

Understanding the performance metrics and resource requirements for running wigolo is essential for cost-effective deployment of this browser automation tool. The KnockOutEZ/wigolo repository contains specific configuration options and documented limits that allow the service to run efficiently on hardware ranging from minimal single-core VPS instances to dedicated servers. This guide breaks down the concrete memory, CPU, and network constraints you will encounter when deploying the system.

Core Performance Metrics

Base Memory Footprint

When the Wigolo server starts without active browser instances, it maintains a minimal idle memory footprint of approximately 30 MiB (tens of MiB). This baseline consumption is documented in docs/self-hosting.md, which describes the server as having a "small" idle footprint suitable for constrained environments.

Per-Browser Memory Overhead

Each Chromium instance spawned by the browser pool adds roughly 200 MiB of RAM usage per instance. According to docs/self-hosting.md, "each pooled browser costs real memory," and this overhead must be accounted for when calculating total system requirements. Heavy web pages can push this figure higher, making the MAX_BROWSERS environment variable critical for memory management.

CPU Utilization Patterns

CPU consumption follows a spiky pattern rather than a constant load. During idle periods, the Node.js process uses minimal processor cycles. However, when browsers render pages or AI models execute inference, expect peaks of 30-50% utilization on a single core for moderate workloads. The docs/self-hosting.md file notes that "CPU is modest; most work is I/O-bound," though AI inference can temporarily saturate available processing capacity.

Network I/O and Request Limits

The wigolo serve command launches an HTTP/1.1 server with keep-alive connection support. Typical bandwidth usage averages approximately 10 Mbps for medium-size payloads. Hard resource limits are enforced at the server level:

• Request body cap: 5 MiB maximum (configurable via environment variables)
• Request timeout: 30 seconds default (slow-client timeout)
• Concurrency cap: 10 simultaneous requests (default)

These limits are defined in docs/rest-api.md under the Resource limits section and implemented in src/server.ts to prevent resource exhaustion.

Configurable Resource Limits

Browser Pool Management with MAX_BROWSERS

The MAX_BROWSERS environment variable controls the size of the Chromium pool, directly impacting memory consumption. The default value is 2, but this should be tuned to your hardware:

• Tiny VPS: Set MAX_BROWSERS=1 to prevent OOM (Out of Memory) errors
• Standard deployment: Leave at default 2 for balanced throughput
• High-capacity servers: Increase based on available RAM (calculate ~200 MiB per additional browser)

This configuration is detailed in docs/self-hosting.md alongside recommendations for "small VPS" deployments.

Request Size and Timeout Constraints

Runtime limits are enforced through environment variables parsed in src/server.ts and documented in docs/rest-api.md:

• MAX_BODY_SIZE: Defaults to 5 MiB; accepts units like 5m or 5120k
• Request timeout: 30 seconds per request protects against slow clients

These caps ensure that single requests cannot monopolize server resources or trigger memory pressure through excessive payload sizes.

AI Model Memory Considerations

AI inference components (using frameworks like LlamaIndex or LangChain) execute within the same Node.js process. Memory requirements vary significantly by model size:

• Small models: Consume less than 500 MiB RAM
• Large models: Require greater than 2 GiB RAM

When deploying AI features, ensure your host has sufficient memory beyond the base footprint and browser pool requirements described in docs/cli.md.

Deployment Recommendations by Infrastructure

Match your hardware profile to these specific configuration strategies to optimize wigolo performance metrics and resource requirements:

• Tiny VPS (1 vCPU, 1 GiB RAM): Configure MAX_BROWSERS=1 and select small LLMs with footprints under 500 MiB. Monitor swap usage closely, as the combined baseline (~30 MiB) plus browser (200 MiB) plus model (500 MiB) approaches system limits.

• Small VPS (2 vCPU, 2 GiB RAM): Set MAX_BROWSERS=2 (default) and deploy medium-size models around 1 GiB. This configuration handles moderate concurrency without swapping.

• Dedicated Server or Cloud VM: Scale MAX_BROWSERS upward based on monitored RAM availability (allowing ~200 MiB per browser), enable larger LLMs for improved inference quality, and adjust WIGOLO_MAX_CONCURRENCY beyond the default 10 requests if CPU monitoring permits.

Implementation in Source Code

Resource management logic is distributed across several key files in the repository:

• docs/self-hosting.md – Documents the idle memory footprint (~30 MiB), per-browser costs (~200 MiB), and recommended MAX_BROWSERS settings for various VPS tiers.
• docs/rest-api.md – Defines specific resource limits including the 5 MiB body cap and 30-second timeout thresholds.
• docs/cli.md – Describes the wigolo serve command initialization and HTTP server configuration.
• src/server.ts – Implements the request routing logic and enforces runtime resource limits at the middleware level.
• package.json – Contains default scripts and configuration metadata used during service initialization.

Configuration Examples

Start Wigolo with resource constraints appropriate for minimal hardware:

MAX_BROWSERS=1 MAX_BODY_SIZE=5m wigolo serve

Increase concurrent request handling for IO-bound workloads:

WIGOLO_MAX_CONCURRENCY=8 wigolo serve

Monitor real-time resource consumption on Unix systems:

watch -n 5 "ps -o pid,pmem,pcpu,cmd -C node"

Summary

• Base footprint: ~30 MiB RAM idle, scaling linearly with each browser instance (~200 MiB each).
• CPU pattern: Low idle usage with spikes to 30-50% single-core utilization during rendering or AI inference.
• Hard limits: 5 MiB request bodies, 30-second timeouts, and configurable MAX_BROWSERS (default 2) prevent resource exhaustion.
• VPS suitability: Runs on 1 GiB RAM instances with tuning (MAX_BROWSERS=1), while 2 GiB instances support default configurations comfortably.
• AI overhead: Model size determines additional memory requirements (500 MiB to 2+ GiB) beyond the core service footprint.

Frequently Asked Questions

How much RAM is required to run Wigolo on a minimal VPS?

A minimal viable deployment requires 1 GiB of RAM, configured with MAX_BROWSERS=1 and a small AI model under 500 MiB. This accommodates the ~30 MiB idle footprint, one 200 MiB browser instance, and the model while leaving headroom for the operating system.

What causes Wigolo's CPU usage to spike to 50%?

CPU spikes occur primarily during Chromium page rendering and AI model inference. According to docs/self-hosting.md, the system is I/O-bound for standard operations, but computational tasks like executing LlamaIndex or LangChain models temporarily increase processor utilization to 30-50% on a single core.

How do I prevent memory exhaustion when handling many concurrent requests?

Set the MAX_BROWSERS environment variable to limit the Chromium pool size, as each browser consumes ~200 MiB. Additionally, the default concurrency cap of 10 simultaneous requests and the 5 MiB request body limit (configurable via MAX_BODY_SIZE) work together to cap memory allocation per connection, enforced by the routing logic in src/server.ts.

Can I adjust the 30-second request timeout for slower workloads?

Yes, the 30-second slow-client timeout is configurable through environment variables documented in docs/rest-api.md. However, increasing this value requires proportionally more memory to maintain idle connections, so adjust MAX_BROWSERS and concurrency limits accordingly when raising timeout thresholds.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}