Kernel Agent Rules

Sandboxed browser infrastructure with APIs for browser control, recording, and process execution.

Overview

Kernel Images documents the cloud VM and container setup for its browser server. It pairs setup and test commands with known failures in CDP routing, recorder cleanup, image quotas, and telemetry.

Hard prohibitions Verification by change type

Documents

├── 
└── server
    └──

Techniques in this file

Explain the clock behind event timestamps

The guide connects clock choice to VM suspension: a monotonic clock can pause while a machine sleeps. It names the affected event field and the wall-clock source producers should use.

5213. **`events.Event.Ts` must be wall-clock (`time.Now()`) captured at emit/observe — never a monotonic or source-derived clock.** On scale-to-zero VMs, `CLOCK_MONOTONIC` freezes during suspend, so any timestamp derived from it (notably the kmsg envelope timestamp behind OOM events) skews backward by the suspended duration. `publishLocked` already defaults a zero `Ts` to wall-clock at ingest, so the real hazard is a producer setting `Ts` to a *non-zero, non-wall-clock* value (exactly the envelope bug). HTTP-published events leave `Ts` unset and get stamped by the API handler at ingest; in-process producers that set `Ts` themselves (sysmon kmsg reader, cdpmonitor, etc.) must use `time.Now()`.

02 / Hard prohibitions

Route producers through the configuration boundary

Telemetry producers must use TelemetrySession so customer category settings apply. The rule identifies both the bypass and the limited callers allowed to reach the underlying event stream.

5012. **All telemetry producers must publish through `TelemetrySession`, never directly to the raw `EventStream`.** Producers take a `func(events.Event) (events.Envelope, bool)` callback wired to `telemetrySession.Publish` in `cmd/api/main.go`; this is what enforces category gating from `PUT /telemetry`. Publishing straight to `EventStream` bypasses the customer's telemetry config. The only legitimate `EventStream.Publish` callers are `TelemetrySession` itself and tests.

Document the actual CDP routing behavior

The proxy ignores the requested WebSocket path and forwards to the browser endpoint. The guide gives the target-attachment sequence required for page-level interaction.

323. **CDP proxy on port 9222 routes ALL WebSocket connections to the browser-level endpoint** (ignores request path). Use `Target.createTarget` + `Target.attachToTarget` with `flatten: true` for page-level interaction. Playwright/Puppeteer handle this automatically.

04 / Verification by change type

Tie tests to infrastructure prerequisites

Unit tests exclude e2e, while end-to-end tests require Docker and prebuilt images. Naming the image variables makes the dependency explicit before a contributor diagnoses a test failure.

428. **E2e tests** use `testcontainers-go` and require Docker + pre-built images. Set `E2E_CHROMIUM_HEADFUL_IMAGE` and `E2E_CHROMIUM_HEADLESS_IMAGE` env vars to point to the correct image tags.

Ideas for your repo

Document runtime failures together with the condition that triggers them.
Name the shared boundary that enforces user configuration.
Separate fast local checks from tests that require infrastructure.
Specify clock semantics for timestamps produced by suspended systems.