# Wigolo Performance Metrics and Resource Requirements: Optimization Guide

> Discover Wigolo performance metrics and resource needs. Learn how to optimize with environment caps for efficient deployment on modest VPS with this guide from KnockOutEZ.

- Repository: [Towhid Khan/wigolo](https://github.com/KnockOutEZ/wigolo)
- Tags: performance
- Published: 2026-07-29

---

**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`](https://github.com/KnockOutEZ/wigolo/blob/main/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`](https://github.com/KnockOutEZ/wigolo/blob/main/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`](https://github.com/KnockOutEZ/wigolo/blob/main/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`](https://github.com/KnockOutEZ/wigolo/blob/main/docs/rest-api.md) under the **Resource limits** section and implemented in [`src/server.ts`](https://github.com/KnockOutEZ/wigolo/blob/main/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`](https://github.com/KnockOutEZ/wigolo/blob/main/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`](https://github.com/KnockOutEZ/wigolo/blob/main/src/server.ts) and documented in [`docs/rest-api.md`](https://github.com/KnockOutEZ/wigolo/blob/main/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`](https://github.com/KnockOutEZ/wigolo/blob/main/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`](https://github.com/KnockOutEZ/wigolo/blob/main/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`](https://github.com/KnockOutEZ/wigolo/blob/main/docs/rest-api.md)** – Defines specific resource limits including the 5 MiB body cap and 30-second timeout thresholds.
- **[`docs/cli.md`](https://github.com/KnockOutEZ/wigolo/blob/main/docs/cli.md)** – Describes the `wigolo serve` command initialization and HTTP server configuration.
- **[`src/server.ts`](https://github.com/KnockOutEZ/wigolo/blob/main/src/server.ts)** – Implements the request routing logic and enforces runtime resource limits at the middleware level.
- **[`package.json`](https://github.com/KnockOutEZ/wigolo/blob/main/package.json)** – Contains default scripts and configuration metadata used during service initialization.

## Configuration Examples

Start Wigolo with resource constraints appropriate for minimal hardware:

```bash
MAX_BROWSERS=1 MAX_BODY_SIZE=5m wigolo serve

```

Increase concurrent request handling for IO-bound workloads:

```bash
WIGOLO_MAX_CONCURRENCY=8 wigolo serve

```

Monitor real-time resource consumption on Unix systems:

```bash
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`](https://github.com/KnockOutEZ/wigolo/blob/main/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`](https://github.com/KnockOutEZ/wigolo/blob/main/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`](https://github.com/KnockOutEZ/wigolo/blob/main/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.