AI agent browser isolation is four orthogonal layers, not one toggle.

The point of decomposing it this way is that these four layers do not have to move together. You can want a logged-in session (layer 2 on) but a freshly-launched Chromium (layer 3 on). You can want a real Chrome (layer 1 off) but per-run artifact directories (layer 4 on). A single isolation flag cannot express any of those combinations.

Profile: where the cookies live, and why three modes

The profile is the disk directory Chromium passes to the --user-data-dir flag. It holds cookies, localStorage, IndexedDB, the cache, the list of installed extensions, the saved logins, and a handful of Chromium-internal lock files. In Assrt, the persistent profile is at ~/.assrt/browser-profile, declared at browser.ts:313 inside the persistent branch of launchLocal(). The path is constructed with join(homedir(), ".assrt", "browser-profile") and created with mkdirSync(userDataDir, { recursive: true }) on first use.

That is one of three possible profile modes. The full launch decision lives at browser.ts:296-347 and resolves in this order: extension mode wins if the extension flag is set, isolated wins next if isolated is set or the env var ASSRT_ISOLATED is truthy, otherwise the persistent branch runs. The first two are short. The third is what most of this page is about.

// /Users/matthewdi/assrt-mcp/src/core/browser.ts, lines 296-310
// Isolated mode. Nothing on disk, nothing to clean up.
// The agent always starts in a Chromium with no cookies,
// no localStorage, no service workers, no installed extensions.

const args = [
  cliPath,
  "--viewport-size", "1600x900",
  "--output-mode", "file",
  "--output-dir", outputDir,
  "--caps", "devtools",
];

if (extension) {
  args.push("--extension"); // skip profile entirely, attach to real Chrome
} else if (isolated) {
  args.push("--isolated"); // in-memory profile, nothing persisted
}

The shape of the difference matters more than the line count. Isolated mode hands one extra flag to @playwright/mcp and is done. Persistent mode runs an orphan-PID walk, an lstat-then-unlink loop over three Chromium lock files, and a structured fallback that flips the local mode variable from persistent to isolated when any of the unlinks fail. The fallback is what makes persistent mode safe to use in CI and on a developer laptop without hand-holding: when something has gone wrong, the code chooses correctness over inheritance.

Session: derived from layer 1, but worth naming

Session is not a separate flag. It is a consequence of layer 1 plus what your dev server stores in cookies. It is worth naming because most reasoning bugs about isolation come from confusing profile and session. The persistent profile inherits whatever session your last run ended in: log in once, every subsequent run inherits the cookies. Isolated mode starts every run logged out: the in-memory profile has no cookies, no localStorage, no service workers. Extension mode inherits whatever session your real Chrome has: same cookies, same OAuth state, same MFA tokens.

When you write a test plan for assrt_test, the session model determines whether step one is "log in" or "assume already logged in." Persistent profile lets you skip the login step on every run after the first. Isolated forces you to script it. Extension lets you take advantage of an MFA challenge you already passed in your real browser, which is the single most useful property of extension mode for debugging flaky-only-in-prod issues.

Process: who cleans up the previous Chromium

Process isolation is the layer that catches everyone. If a previous run crashed or was Ctrl-C'd mid-execution, Chromium did not get a chance to clean up. The user-data-dir still has a SingletonLock symlink whose target is the literal string hostname-PID, and depending on what crashed, the process behind that PID may still be alive and pinned to that directory. Launching a new Chromium into the same dir while the old one is still alive is what produces the "opening in existing browser session" mode, which from the agent's point of view looks like a hung navigate.

Assrt's answer is the orphan-PID walk at browser.ts:191-214. It runs unconditionally in the persistent branch, before the SingletonLock cleanup, before the --user-data-dir flag is appended. The walk is a static method on McpBrowserManager that finds every PID associated with the profile from three sources: a ps aux | grep for --user-data-dir=<path>, the PID encoded in the SingletonLock symlink target, and a one-level parent walk for the Playwright MCP wrapper if it owns one of the discovered PIDs. The deduped set gets SIGKILLed twice with a 750 ms gap between sweeps. The double sweep is there because a child process can respawn between the first kill and the second ps; in practice the second sweep usually finds nothing, which is the desired state.

The detail that surprises people is that the walk does not touch your normal Chrome. It only kills processes whose command line contains the literal --user-data-dir=/Users/you/.assrt/browser-profile string. Your real Chrome has a different user-data-dir, so it is invisible to the grep.

Artifacts: per-run UUID dir, always

Layer 4 is the cheapest and runs the same in every mode. Every call to the assrt_test MCP tool mints a fresh runId with crypto.randomUUID() at the very top of the handler, server.ts:429, before any agent state is constructed. The directory is computed as join(tmpdir(), "assrt", runId) at server.ts:430, and screenshots, video, the line-by-line execution log, and the structured event stream all hang off it. Two parallel runs produce two disjoint UUIDs and therefore two disjoint trees on disk.

Why this matters for isolation: the per-run artifact tree is completely independent of the profile. A run in isolated mode and a run in persistent mode write artifacts to the same shape of directory, just under different UUIDs. A run in extension mode attached to your real Chrome still writes its screenshots to /tmp/assrt/<UUID>/screenshots/, not into your Chrome profile. There is exactly one shared mutable path in any of these modes, the persistent profile dir, and that one is protected by layers 2 and 3.

Cloud isolated browsers vs local Assrt

Cloud isolation services collapse the four layers into one container per session. That is the right shape for general agentic browsing. For an AI test agent driving your own dev server, the trades look like this.

Both shapes are valid; the choice depends on whether the work is general agent browsing or end-to-end testing of code you own.

What ends up on disk after one assrt_test run

Three filesystem roots, three different lifetimes. After one run with the default settings (persistent profile, headless), an ls ~/.assrt shows you the literal layout:

~/.assrt/
  browser-profile/        # layer 1, persists across runs
    Default/
      Cookies
      Local Storage/
      IndexedDB/
      ...
    SingletonLock         # only present while Chromium is alive
    SingletonSocket
    SingletonCookie
  extension-token         # layer 1, extension mode only
  playwright-output/      # MCP file output, snapshot .yml + screenshots

/tmp/assrt/
  <UUID>/                 # layer 4, one per run
    screenshots/
      00_step1_navigate.png
      01_step2_click.png
      ...
    video/
      <run>.webm
    execution.log
    events.json

The split is intentional. The profile dir is large and slow to recreate (Chromium populates a few hundred files on first launch). The extension token is small and reusable. The per-run artifact tree is large but ephemeral, and on most systems tmpdir() is wiped on reboot. Three different decisions about what to keep for how long, three different roots, no shared mutable file across runs except the profile, which is itself protected by layers 2 and 3.

A picking rule, written down

The four-layer decomposition produces a picking rule that is shorter than the long form usually is.

• Default (persistent profile, headless). Use when you are running the agent against a local dev server you control, the test plan inherits a logged-in state from a previous run, and you do not want to re-script login on every run. This is the right setting for the loop that runs every time you save a file.
• Isolated (isolated: true). Use when the test must start clean, when you are testing the sign-up flow itself, when you want the test to be reproducible across machines without relying on prior state, or when CI is running on an ephemeral runner where persistence does not buy you anything.
• Extension (extension: true). Use when you need to repro a bug from your real session, when captcha or anti-bot heuristics block headless Chromium, or when the bug is OAuth-related and you would otherwise have to redo the entire OAuth dance per run. The cost is your real cookies and your real history are in the loop, so this is not the right mode for clean CI runs.

For two agents on one host that both want persistent, see the fallback behavior in layer 3: the second one transparently runs isolated for that call. If you want both agents on persistent state, give them different profile dirs (the path is the only shared resource) or run extension mode and let them attach to different tabs in the same Chrome.

Frequently asked questions