Configuration

Global Pool Configuration

CobaltEngine.Configure must be called once at application startup, before any render takes place. Calling it after the pool has initialised throws an InvalidOperationException.

CobaltEngine.Configure(options =>
{
    options.MinSize            = 2;
    options.MaxSize            = 8;
    options.MaxUsesPerBrowser  = 100;
    options.BrowserLeaseTimeout = TimeSpan.FromSeconds(30);
});

PoolOptions Reference

Property	Type	Default	Description
MinSize	int	1	Browsers kept warm at all times. Must be ≥ 0 and ≤ MaxSize.
MaxSize	int	5	Maximum concurrent browser leases. Must be ≥ 1.
MaxUsesPerBrowser	int	100	A browser is recycled after this many renders to prevent memory growth. Must be ≥ 1.
BrowserLeaseTimeout	TimeSpan	30s	How long a call to GetBrowserAsync waits before throwing TimeoutException.
ExtraArgs	List<string>	[]	Raw Chromium command-line flags appended to every browser launch.

Warning

Invalid combinations (e.g. MinSize > MaxSize, MaxSize < 1) throw ArgumentException immediately when the pool is first used, not at configure time.

Cloud Environment Presets

Rather than configuring ExtraArgs flags manually, use the built-in CloudEnvironment presets. Each preset applies the correct flags and sensible pool sizes for its target environment:

using CobaltPdf.Configuration;

// Linux VM or bare-metal server
CobaltEngine.Configure(CloudEnvironment.ConfigureForLinux);

// Docker container
CobaltEngine.Configure(CloudEnvironment.ConfigureForDocker);

// Azure App Service (Linux) or Azure Functions Premium Plan
CobaltEngine.Configure(CloudEnvironment.ConfigureForAzure);

// AWS ECS / Fargate
CobaltEngine.Configure(CloudEnvironment.ConfigureForAwsEcs);

// Memory-constrained (AWS Lambda custom container, small VMs)
CobaltEngine.Configure(CloudEnvironment.ConfigureForLowMemory);

Presets can be combined with custom overrides:

CobaltEngine.Configure(o =>
{
    CloudEnvironment.ConfigureForDocker(o);  // apply preset first
    o.MaxSize = 4;                           // then override specific values
    o.ExtraArgs.Add("--proxy-server=host:port");
});

Preset Summary

Preset	Additional Flags	Pool Sizing
ConfigureForLinux	--no-sandbox, --disable-gpu	Min=1, Max=CPUs/2
ConfigureForDocker	--no-sandbox, --disable-dev-shm-usage, --disable-gpu	Min=1, Max=CPUs/2
ConfigureForAzure	--no-sandbox, --disable-dev-shm-usage, --disable-gpu, --single-process	Min=1, Max=CPUs/2
ConfigureForAwsEcs	--no-sandbox, --disable-dev-shm-usage, --disable-gpu	Min=1, Max=CPUs/2
ConfigureForLowMemory	--no-sandbox, --disable-dev-shm-usage, --disable-gpu, --single-process	Min=0, Max=1

Tip

On Linux, --no-sandbox, --disable-gpu, and --disable-dev-shm-usage are added automatically as defaults — you do not need to add them manually. Cloud presets skip duplicates, so applying a preset on top of the defaults is safe and recommended.

Common ExtraArgs

Flag	When to use
--no-sandbox	Always required on Linux (added automatically)
--disable-dev-shm-usage	Docker / environments with small /dev/shm (added automatically on Linux)
--disable-gpu	Headless servers without GPU (added automatically on Linux)
--single-process	Memory-constrained environments (merges browser + renderer process)
--proxy-server=host:port	Route Chromium through a proxy
--ignore-certificate-errors	Self-signed certs during development

Warning

--single-process reduces memory at the cost of slightly lower crash isolation. Avoid it in high-throughput production environments unless memory is genuinely constrained.

Pre-warming

By default the pool starts browsers lazily — on the first render. To eliminate first-request latency, pre-warm immediately after configuring:

CobaltEngine.Configure(o => { o.MinSize = 2; /* … */ });
await CobaltEngine.PreWarmAsync(); // launches MinSize browsers now

Logging

CobaltPdf can forward browser console messages (console.log, console.error, etc.) to three destinations, which can be combined with bitwise OR:

// Print browser logs to your application's stdout
CobaltEngine.LoggingMode = BrowserLoggingMode.Console;

// Write browser logs to a rotating file
CobaltEngine.LoggingMode = BrowserLoggingMode.File;
CobaltEngine.BrowserLogPath  = "logs/browser.log";
CobaltEngine.RetainedLogCount = 7; // keep 7 daily files

// Both at once
CobaltEngine.LoggingMode = BrowserLoggingMode.Both;

// Custom callback (e.g. forward to ILogger)
CobaltEngine.OnBrowserLog = message => myLogger.LogDebug("[Browser] {Message}", message);

BrowserLoggingMode Values

Value	Description
None	No browser logs captured (default)
Console	Logs written to Console.WriteLine
File	Logs written to BrowserLogPath with daily rotation
Both	Console and file simultaneously

Licensing

To activate a CobaltPdf license and remove the trial watermark, call SetLicense before any renders:

CobaltEngine.SetLicense("YOUR-LICENSE-KEY");

See Licensing for details.

Shutdown

Always shut down the pool when the application exits to terminate Chromium cleanly:

await CobaltEngine.ShutdownAsync();

In ASP.NET Core, register this with the application lifetime — see Dependency Injection.