Skip to content

feat(kits): add a built-in playwright kit - #24

Draft
paveq wants to merge 1 commit into
mainfrom
feat/playwright-kit
Draft

paveq wants to merge 1 commit into
mainfrom
feat/playwright-kit

Conversation

@paveq

@paveq paveq commented Nov 16, 2026

Copy link
Copy Markdown
Contributor

What

Adds a built-in playwright kit so headless Chromium (Playwright's chrome-headless-shell) can start inside the macOS agent sandbox. Today it aborts at launch:

FATAL:base/apple/mach_port_rendezvous_mac.cc:159 Check failed: kr == KERN_SUCCESS.
bootstrap_check_in org.chromium.Chromium.MachPortRendezvousServer.<pid>: Permission denied (1100)

There is also a non-fatal Failed to read DnsConfig.

Typed Mach grants for built-in kits

  • sandbox::MachName { Global(String), Regex(String) } becomes (global-name "…") / (global-name-regex #"…").
  • kits::Expanded and AgentPolicy get mach_lookup / mach_register. run_agent copies them across next to the kit paths.
  • generate_agent_profile emits them after the harness profile rules and before the final denies. A name with a control character, a ", or a \ (plain names only) is refused with SandboxError::InvalidMachName.
  • Only built-in kits can produce these. RawKitConfig is unchanged, so no user config can add a Mach name. Linux/Landlock ignores them.
  • airlock config lists a kit's Mach names next to its paths.

playwright kit

  • Reads PLAYWRIGHT_BROWSERS_PATH if set, otherwise ~/Library/Caches/ms-playwright (macOS) or ~/.cache/ms-playwright (Linux). Grants nothing when it is 0, because the browsers are then in node_modules.
  • On macOS, in both modes:
    • mach-register and mach-lookup on ^org\.chromium\.Chromium\.MachPortRendezvousServer\.[0-9]+$;
    • mach-lookup on com.apple.SystemConfiguration.configd and com.apple.SystemConfiguration.DNSConfiguration.
  • com.apple.sysmond is not granted (it would list every user process).
  • isolated (default): the cache is read-only.
  • shared: the cache is writable, so playwright install works.

Review needed: shared mode writes executables

Every other kit refuses to write executables that run outside the sandbox. The mise kit, for example, refuses mise install. Shared playwright breaks that rule. The cache holds the browser builds that the user's own Playwright runs, and any unsandboxed Playwright MCP server, launch outside the sandbox. SECURITY.md documents this as an explicit, opt-in exception, and the docs recommend isolated mode. The alternative is to have shared mode match isolated, so no mode writes the cache. Please decide.

Docs

README (Kits), SECURITY (Kits + new "Kit Mach services"), SKILL, ARCHITECTURE (Kits), docs/airlock-v2-design.md (kit table + Mach paragraph), config templates.

Tests

  • kits.rs: playwright expansion in both modes and on both platforms, the PLAYWRIGHT_BROWSERS_PATH override and 0, Mach names on macOS only, and no other built-in granting Mach names. The hard-coded known-kit list is updated.
  • sandbox.rs (macOS): no mach-register/regex/SystemConfiguration without a kit, under every profile kind. Exact register/lookup blocks are checked, and they come after the Claude profile rules. Injection attempts are refused. The b7 final-denies test now includes kit Mach names.

Not verified locally

I wrote this inside an Airlock agent sandbox. It refused:

  • cargo build/cargo test: ~/.cargo → Operation not permitted;
  • nix build: /nix/var/nix/daemon-socket/socket → Operation not permitted;
  • nested sandbox-exec: sandbox_apply: Operation not permitted.

So nothing has been compiled or tested locally yet. Only cargo fmt --check ran. CI is the first compile.

A real Chromium launch under the generated profile is also unverified. To check it from a normal terminal:

airlock run --profile claude --kit playwright -- \
  ~/Library/Caches/ms-playwright/chromium_headless_shell-*/chrome-headless-shell-mac-arm64/chrome-headless-shell \
  --headless --no-sandbox --dump-dom about:blank

If Chromium then fails on another Mach name, log stream --predicate 'sender == "Sandbox"' shows which one.

🤖 Generated with Claude Code

Headless Chromium can't start in the macOS agent sandbox. Every Chromium
process checks in `org.chromium.Chromium.MachPortRendezvousServer.<pid>`
at startup, and the agent profile grants no `mach-register` at all, so
Playwright's chrome-headless-shell aborts with `bootstrap_check_in ...
Permission denied (1100)`. It also can't read the DNS config, because
the SystemConfiguration services aren't in the lookup allowlist.

Kits could only add paths and env, so this adds typed Mach grants to
them: `Expanded::mach_lookup`/`mach_register` hold `sandbox::MachName`
values (an exact `global-name` or an anchored `global-name-regex`).
`run_agent` copies them onto `AgentPolicy`, and `generate_agent_profile`
emits them after the harness profile rules and before the final denies.
The builder refuses a name with a control character, a quote, or a
backslash in a plain name. Only built-in kits produce them: no
`[kits.<name>]` field can, because a Mach service leads out of the
sandbox into whatever process serves it. Landlock ignores them.
`airlock config` lists them next to a kit's paths.

The `playwright` kit reads `PLAYWRIGHT_BROWSERS_PATH`, or the platform
cache, and on macOS grants register and lookup on the rendezvous regex
plus lookup on `com.apple.SystemConfiguration.configd` and
`.DNSConfiguration`. It doesn't grant `com.apple.sysmond`, which would
let the agent list every process the user runs. Shared mode makes the
browser cache writable so `playwright install` works. That breaks the
rule every other kit keeps of never writing executables that run
outside the sandbox, so SECURITY.md documents it as an explicit opt-in.

Not checked end to end: this was written inside an Airlock agent
sandbox, which refuses both a nested `sandbox-exec` and the cargo
registry, so the unit tests and a real Chromium launch under the
generated profile still need a run outside it.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant