Skip to content

The headless browser for AI agents and web scraping

Correct effective V8 heap flag documentation

SGavrl1eba7ef8ffe8
diff --git a/docs/Environment-variables.md b/docs/Environment-variables.md
index 5780dd38..d00acfd1 100644
--- a/docs/Environment-variables.md
+++ b/docs/Environment-variables.md
@@ -185,10 +185,12 @@ OPENSSL_NO_VENDOR=1 cargo build --release --features render
V8 flags are passed via `--v8-flags`, not environment variables:
```bash
-obscura serve --v8-flags "--max-old-space-size=2048 --expose-gc"
+obscura --v8-flags "--max-old-space-size=2048 --expose-gc" serve
```
-Defaults are `--max-old-space-size=4096 --max-semi-space-size=4 --optimize-for-size` on 64-bit systems (a 4 GB old-space ceiling, a capped young generation, and codegen tuned for a smaller footprint to cut RSS). Anything you pass with `--v8-flags` is appended after these, and V8 uses the last value for a repeated flag, so your value wins for that flag while the other defaults stay in effect.
+Defaults are `--max-old-space-size=4096 --max-semi-space-size=4 --optimize-for-size` on 64-bit systems. In the current V8, `--optimize-for-size` overrides the requested semi-space cap to **1 MiB**, not 4 MiB. The old-generation ceiling remains 4 GB.
+
+User flags are appended after the defaults, but V8 applies flag implications afterwards. To change the young-generation cap, also disable size optimization, for example `obscura --v8-flags "--no-optimize-for-size --max-semi-space-size=8" serve`. This can reduce GC CPU at the cost of more memory; measure the complete workload before adopting it. Use `--v8-flags "--print-flag-values"` to inspect the effective settings after V8 initialization.
## HTTP proxy environment
diff --git a/docs/Run-in-production-at-scale.md b/docs/Run-in-production-at-scale.md
index 1207961d..c3d8ece5 100644
--- a/docs/Run-in-production-at-scale.md
+++ b/docs/Run-in-production-at-scale.md
@@ -86,13 +86,13 @@ Use one worker per CPU core. Each worker handles its own pool of pages. Sessions
## V8 heap
-Default V8 heap is 4 GB on 64-bit systems. The defaults also cap the young generation (`--max-semi-space-size=4`) and pass `--optimize-for-size` to hold RSS down. Override:
+The V8 old-generation ceiling is 4 GB on 64-bit systems. The defaults request `--max-semi-space-size=4`, but the current V8's `--optimize-for-size` implication overrides the effective semi-space cap to 1 MiB. Override the old-generation ceiling with:
```bash
-obscura serve --v8-flags "--max-old-space-size=2048"
+obscura --v8-flags "--max-old-space-size=2048" serve
```
-Flags you pass are appended after the defaults, and V8 uses the last value for a repeated flag, so your `--max-old-space-size` wins while the memory-tuning defaults stay in effect. Lower for memory-constrained hosts, raise for heavy SPAs.
+Flags you pass are appended after the defaults, so this old-generation override retains memory tuning. To change the young-generation cap, also pass `--no-optimize-for-size`; V8's flag implications otherwise override your cap. Disabling size optimization can save GC CPU but increase peak memory. Benchmark both before changing production defaults.
## Parallel scrape