Document how to measure session memory with process execution

[andrewleesteele]

Summary

There's no per-session memory number in the API, CLI, or dashboard, and customers asking "how much memory are my sessions using?" currently have no self-serve answer. Until a real metric ships, process execution already gives them one — this documents it.

Adds a Measure memory and CPU usage section to browsers/process-execution.mdx:

• Whole-session memory with free, plus what the allocation is per browser type and why available is the number to watch rather than free.
• Per-process breakdown with ps -eo rss= -o comm= --sort=-rss, explaining why a tab-heavy workload appears as many mid-sized chromium rows, and how to sum them. Calls out that renderers aren't attributable to a specific tab.
• Sampling over time by spawning a loop and streaming it, so a customer can compute percentiles or alert on a threshold instead of taking one point-in-time reading. Notes that samples have to be persisted outside the VM.
• A note that process.status reports mem_bytes only for processes started through process.spawn and doesn't populate CPU, so ps/top are the answer for Chromium.
• A pointer to the system telemetry category for crash-time memory (system_oom_kill), framed as after-the-fact so it complements rather than replaces sampling.

Also adds free/top to the CLI examples and a warning that the CLI splits every --args value on commas — ps -eo rss,comm silently runs as ps -eo rss, even inside a quoted sh -c string. That's a CLI parsing bug worth fixing separately; documenting it here so it doesn't bite anyone in the meantime.

Verification

Every command and both SDK snippets were run against live headless and headful sessions. The ps sample output is real output. Confirmed free reports the session's allocation (974 MiB on a headless browser, 7954 MiB on a default headful one) and that htop isn't installed, so the examples use ps and top.

No test suite in this repo; Mintlify renders on deploy.

🤖 Generated with Claude Code

---

Note

Low Risk
Documentation-only changes with no runtime, API, or security impact.

Overview
Documents a self-serve workaround for the missing per-session memory metric in the API, CLI, and dashboard by using process execution inside the browser VM.

Adds a Measure memory and CPU usage section to process-execution.mdx: whole-session totals with free (including allocation by browser type and why available matters), per-process RSS with ps, summing Chromium processes, and time-series sampling via process.spawn + stdout streaming (with file I/O as an alternative). Clarifies that process.status only covers spawned processes, not Chromium or CPU, and points to system_oom_kill telemetry for post-crash context.

Also lists free/top in the CLI examples, adds a measure memory headroom production pattern, and warns that the CLI splits --args on commas, which breaks comma-containing ps flags unless you use comma-free forms or the SDKs.

^{Reviewed by Cursor Bugbot for commit 3534009. Bugbot is set up for automated code reviews on this repo. Configure here.}

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated
Kernel	🟢 Ready	View Preview	Sep 23, 2026, 2:08 AM

💡 Tip: Enable Automations to automatically generate PRs for you.

[cursor]

Risk assessment: Very Low

This PR changes one file, browsers/process-execution.mdx (+159 / −0). It adds a docs section on measuring session memory and CPU from inside an existing browser session (free, ps, top), with TypeScript and Python examples of the process-execution APIs already documented on this page, plus a CLI note that --args is split on commas.

Checked against the diff:

• No application code, API specs, auth, config, or infrastructure files changed
• No production behavior or shared systems modified
• The page is product documentation, not model instructions or prompts
• main does not require a code owners review

Approving.

  

_{Sent by Cursor Automation: Assign PR reviewers}

[cursor]

Cursor Bugbot has reviewed your changes using default effort and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

Want higher recall? High effort reviews run extra passes and find more bugs. A team admin can switch effort levels in the Cursor dashboard.

^{Reviewed by Cursor Bugbot for commit 3534009. Configure here.}

[cursor]

Relative API reference link

Medium Severity

The memory create-parameter link uses a relative /api-reference/ path. Those pages are generated from the remote OpenAPI spec and are not local .mdx files, so Mintlify's broken-link check treats the target as missing.

 

^{Triggered by learned rule: Use absolute URLs for /api-reference/ links}

^{Reviewed by Cursor Bugbot for commit 3534009. Configure here.}