# kernel/kernel-images architecture

> Architecture diagram of the GitHub repository kernel/kernel-images, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/kernel/kernel-images
- Repository: https://github.com/kernel/kernel-images

## Overview

Kernel provides sandboxed Chromium sessions for browser automation, with optional interactive live view and session replay. The main workflow is an automation client connecting over CDP to a running browser; the API also exposes browser controls and agent-oriented tools. A wrapper starts and monitors the browser environment. Separate branches cover the remote GUI and lifecycle telemetry/standby. The README documents these capabilities; unsampled API and UI internals are represented at their enclosing source paths, so uncertain internal wiring is omitted.

Main entry points: [`server/cmd/api/main.go`](https://github.com/kernel/kernel-images/blob/main/server/cmd/api/main.go) (Kernel API), [`server/cmd/api/api`](https://github.com/kernel/kernel-images/tree/main/server/cmd/api/api) (Browser API handlers), [`server/lib/events/eventstream.go`](https://github.com/kernel/kernel-images/blob/main/server/lib/events/eventstream.go) (Event stream), [`server/lib/devtoolsproxy/proxy.go`](https://github.com/kernel/kernel-images/blob/main/server/lib/devtoolsproxy/proxy.go) (DevTools proxy)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Browser runtime"]
  node_wrapper["Environment wrapper<br/>[main.go]"]
  node_launcher["Chromium launcher<br/>[main.go]"]
  node_chromium["Chromium browser"]
end

subgraph group_api["API and automation"]
  node_api["Kernel API<br/>[main.go]"]
  node_handlers["Browser API handlers"]
  node_cdpproxy["DevTools proxy<br/>[proxy.go]"]
  node_chromedriver["ChromeDriver proxy<br/>[proxy.go]"]
  node_browserinspect["Browser surface tracking<br/>[tracker.go]"]
  node_webmcp["WebMCP tools<br/>[manager.go]"]
  node_repl["Browser REPL<br/>[browser-repl.ts]"]
end

subgraph group_live["Remote live view"]
  node_gui["Live-view client<br/>[app.vue]"]
  node_neko["Neko service"]
  node_recording["Session recording<br/>[recorder.go]"]
end

subgraph group_ops["Lifecycle and telemetry"]
  node_events["Event stream<br/>[eventstream.go]"]
  node_telemetry["Telemetry API<br/>[telemetry.go]"]
  node_s2[("S2 event storage<br/>[s2storage.go]")]
  node_otlp["OTLP exporter<br/>[otlpstorage.go]"]
  node_scale["Scale-to-zero<br/>[scaletozero.go]"]
end

node_framework(("Automation client"))
node_operator(("Live-view user"))

node_wrapper -->|"starts"| node_launcher
node_launcher -->|"executes"| node_chromium
node_wrapper -->|"starts services"| node_api
node_framework -->|"connects CDP"| node_cdpproxy
node_cdpproxy -->|"proxies commands"| node_chromium
node_framework -.->|"connects"| node_chromedriver
node_chromedriver -.->|"forwards requests"| node_chromium
node_api -->|"starts proxy"| node_cdpproxy
node_api -->|"starts proxy"| node_chromedriver
node_api -->|"serves routes"| node_handlers
node_handlers -->|"tracks targets"| node_browserinspect
node_handlers -->|"uses tools"| node_webmcp
node_handlers -->|"exposes REPL"| node_repl
node_operator -->|"views and controls"| node_gui
node_gui -->|"connects live view"| node_neko
node_chromium -.->|"screen capture"| node_recording
node_api -->|"serves telemetry"| node_telemetry
node_telemetry -->|"publishes events"| node_events
node_events -.->|"appends events"| node_s2
node_events -.->|"exports records"| node_otlp
node_api -->|"applies standby middleware"| node_scale

click node_wrapper "https://github.com/kernel/kernel-images/blob/main/server/cmd/wrapper/main.go"
click node_launcher "https://github.com/kernel/kernel-images/blob/main/server/cmd/chromium-launcher/main.go"
click node_api "https://github.com/kernel/kernel-images/blob/main/server/cmd/api/main.go"
click node_handlers "https://github.com/kernel/kernel-images/tree/main/server/cmd/api/api"
click node_cdpproxy "https://github.com/kernel/kernel-images/blob/main/server/lib/devtoolsproxy/proxy.go"
click node_chromedriver "https://github.com/kernel/kernel-images/blob/main/server/lib/chromedriverproxy/proxy.go"
click node_browserinspect "https://github.com/kernel/kernel-images/blob/main/server/lib/browsersurface/tracker.go"
click node_webmcp "https://github.com/kernel/kernel-images/blob/main/server/lib/webmcpclient/manager.go"
click node_repl "https://github.com/kernel/kernel-images/blob/main/server/runtime/browser-repl.ts"
click node_gui "https://github.com/kernel/kernel-images/blob/main/images/chromium-headful/client/src/app.vue"
click node_recording "https://github.com/kernel/kernel-images/blob/main/server/lib/recorder/recorder.go"
click node_events "https://github.com/kernel/kernel-images/blob/main/server/lib/events/eventstream.go"
click node_telemetry "https://github.com/kernel/kernel-images/blob/main/server/cmd/api/api/telemetry.go"
click node_s2 "https://github.com/kernel/kernel-images/blob/main/server/lib/events/s2storage.go"
click node_otlp "https://github.com/kernel/kernel-images/blob/main/server/lib/events/otlpstorage.go"
click node_scale "https://github.com/kernel/kernel-images/blob/main/server/lib/scaletozero/scaletozero.go"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_wrapper,node_launcher,node_chromium,node_framework,node_operator toneBlue
class node_api,node_handlers,node_cdpproxy,node_chromedriver,node_browserinspect,node_webmcp,node_repl toneAmber
class node_gui,node_neko,node_recording toneMint
class node_events,node_telemetry,node_s2,node_otlp,node_scale toneRose
```

## Components

### Browser runtime

- [Environment wrapper](https://github.com/kernel/kernel-images/blob/main/server/cmd/wrapper/main.go): `server/cmd/wrapper/main.go`
- [Chromium launcher](https://github.com/kernel/kernel-images/blob/main/server/cmd/chromium-launcher/main.go): `server/cmd/chromium-launcher/main.go`
- **Chromium browser**

### API and automation

- [Kernel API](https://github.com/kernel/kernel-images/blob/main/server/cmd/api/main.go): `server/cmd/api/main.go`
- [Browser API handlers](https://github.com/kernel/kernel-images/tree/main/server/cmd/api/api): `server/cmd/api/api`
- [DevTools proxy](https://github.com/kernel/kernel-images/blob/main/server/lib/devtoolsproxy/proxy.go): `server/lib/devtoolsproxy/proxy.go`
- [ChromeDriver proxy](https://github.com/kernel/kernel-images/blob/main/server/lib/chromedriverproxy/proxy.go): `server/lib/chromedriverproxy/proxy.go`
- [Browser surface tracking](https://github.com/kernel/kernel-images/blob/main/server/lib/browsersurface/tracker.go): `server/lib/browsersurface/tracker.go`
- [WebMCP tools](https://github.com/kernel/kernel-images/blob/main/server/lib/webmcpclient/manager.go): `server/lib/webmcpclient/manager.go`
- [Browser REPL](https://github.com/kernel/kernel-images/blob/main/server/runtime/browser-repl.ts): `server/runtime/browser-repl.ts`

### Remote live view

- [Live-view client](https://github.com/kernel/kernel-images/blob/main/images/chromium-headful/client/src/app.vue): `images/chromium-headful/client/src/app.vue`
- **Neko service**
- [Session recording](https://github.com/kernel/kernel-images/blob/main/server/lib/recorder/recorder.go): `server/lib/recorder/recorder.go`

### Lifecycle and telemetry

- [Event stream](https://github.com/kernel/kernel-images/blob/main/server/lib/events/eventstream.go): `server/lib/events/eventstream.go`
- [Telemetry API](https://github.com/kernel/kernel-images/blob/main/server/cmd/api/api/telemetry.go): `server/cmd/api/api/telemetry.go`
- [S2 event storage](https://github.com/kernel/kernel-images/blob/main/server/lib/events/s2storage.go): `server/lib/events/s2storage.go`
- [OTLP exporter](https://github.com/kernel/kernel-images/blob/main/server/lib/events/otlpstorage.go): `server/lib/events/otlpstorage.go`
- [Scale-to-zero](https://github.com/kernel/kernel-images/blob/main/server/lib/scaletozero/scaletozero.go): `server/lib/scaletozero/scaletozero.go`

### Other components

- **Automation client**
- **Live-view user**

## Connections

- Environment wrapper → Chromium launcher: starts
- Chromium launcher → Chromium browser: executes
- Environment wrapper → Kernel API: starts services
- Automation client → DevTools proxy: connects CDP
- DevTools proxy → Chromium browser: proxies commands
- Automation client → ChromeDriver proxy: connects
- ChromeDriver proxy → Chromium browser: forwards requests
- Kernel API → DevTools proxy: starts proxy
- Kernel API → ChromeDriver proxy: starts proxy
- Kernel API → Browser API handlers: serves routes
- Browser API handlers → Browser surface tracking: tracks targets
- Browser API handlers → WebMCP tools: uses tools
- Browser API handlers → Browser REPL: exposes REPL
- Live-view user → Live-view client: views and controls
- Live-view client → Neko service: connects live view
- Chromium browser → Session recording: screen capture
- Kernel API → Telemetry API: serves telemetry
- Telemetry API → Event stream: publishes events
- Event stream → S2 event storage: appends events
- Event stream → OTLP exporter: exports records
- Kernel API → Scale-to-zero: applies standby middleware