Configuration

Configure once at startup, before the first render:

using CobaltPdf.WebKit;

CobaltEngine.Configure(o =>
{
    o.MinSize = 1;
    o.MaxSize = 4;
    o.MaxMemoryMb = 2048;
});

CobaltEngine.Configure throws if called after the pool has started; call CobaltEngine.ShutdownAsync() first to reconfigure (tests).

Worker pool

Option	Default	Meaning
`MinSize`	1	Warm workers kept alive. `PreWarmAsync()` spawns them at startup.
`MaxSize`	5	Max concurrent renders. Budget ~0.5 GB per worker; on small cloud instances use 1 per ~1.5 GB.
`MaxUsesPerBrowser`	5	Renders per worker before it is recycled. Recycling bounds steady-state memory at the cold-start baseline; raise it to trade memory for fewer respawns.
`BrowserLeaseTimeout`	30 s	How long a request waits for a free worker before failing with a clear pool-saturated error. On slow single-core hosts (Azure B1) raise this to ≥ 2× your worst-case render time so queued requests don't give up while a long render finishes.
`RenderTimeout`	120 s	Wall-clock cap per render; a wedged worker is killed and replaced, and the render retried once on a fresh worker.

Memory

Option	Default	Meaning
`MaxMemoryMb`	4096	Soft cap — the render aborts cleanly with a descriptive error above this, instead of an opaque kernel OOM-kill. Set it below your host's limit (e.g. 2048 on a 3.5 GB plan).
`ContainerMemoryLimit`	—	Docker-mode only hard cap (`--memory`). Prefer `MaxMemoryMb`.

A first render after a fresh bundle extraction automatically primes the engine's font caches on a throwaway page before any caller-visible render, so cold instances never serve a degraded first PDF.

Skipping post-processing (`WithoutPostProcessing`)

After WebKit prints the page, a post-processing pipeline normally optimises the PDF: fonts are subset to used glyphs, images re-encoded, duplicate fonts merged, and metadata stamped. WithoutPostProcessing() skips that stage and returns the engine's raw output:

var pdf = await engine
    .WithoutPostProcessing()        // raw engine output
    .RenderHtmlAsPdfAsync(html);

	Full pipeline (default)	`WithoutPostProcessing()`
Peak memory per render	baseline	~30 MB lower
Render latency	baseline	faster (skips pikepdf/fontTools)
File size	baseline	~70 % larger (whole fonts, unoptimised images)
Watermarks / encryption / metadata	applied	ignored — they are implemented by the pipeline

Use it on memory-constrained hosts when the PDF is transient (a preview, an in-memory stream) and bytes-on-disk don't matter. The equivalent wire-model flag is PdfRequest.SkipPostProcessing (CobaltPDF.Requests ≥ 1.5.0). The Chromium edition accepts this method for drop-in compatibility but ignores it — Chrome's PDF backend already performs these optimisations natively.

Bundle provisioning

Covered in depth in The Render Bundle: BundleCacheDirectory, BundleBaseUrl, BundleSha256Override, AutoDownloadBundle, BundleDownloadTimeout (default 5 min), QuietBundleDownload, OnBundleDownloadProgress.

Backend selection (development machines)

Covered in Rendering Backends: PreferWsl, ForceWsl, ForceDocker, WslDistribution, SkipWslDependencyCheck, DockerImage, DockerExecutable, StubModeOnWindows. All ignored on Linux, which always renders natively in-process.

Chromium-compatibility notes

ExtraArgs accepts Chromium flags (--no-sandbox, --disable-gpu, …) for drop-in API compatibility but ignores them — this engine is WebKitGTK, and its equivalents are managed internally.
PostLoadSettle (default 1 s) is the safety delay between page load and print, the same as the Chromium edition.
Per-render options are identical to the Chromium edition and fully documented on this site: Rendering, Wait Strategies, Headers, Footers & Watermarks, Fonts, Encryption, Metadata, Splitting & Merging, and more in the table of contents.

Logging

CobaltEngine.LoggingMode = BrowserLoggingMode.Console;   // default: None

With logging on, the library states its chosen backend once per process, announces bundle downloads with the source URL, and surfaces worker stderr — the first things support will ask for. BrowserLoggingMode.File and OnBrowserLog callbacks work as in the Chromium edition.

Table of Contents