KERNEL

What's Kernel?

Kernel provides sandboxed, ready-to-use Chrome browsers for browser automations and web agents. This repo powers our hosted services.

Sign up here!

Key Features

• Sandboxed Chrome browser that Chrome DevTools-based browser frameworks (Playwright, Puppeteer) can connect to
• Remote GUI access (live view streaming) for visual monitoring and remote control
• Configurable live view settings (read-only view, browser window dimensions)
• Controllable video replays of the browser's session

What You Can Do With It

• Run automated browser-based workflows
• Develop and test AI agents that use browsers
• Build custom tools that require controlled browser environments

Implementation

This image can be used to run headful Chromium in a Docker container or with Unikraft unikernels. The unikernel implementation builds on top of the base Docker image and has the additional benefits of running on a unikernel:

• Automated standby / "sleep mode" when there is no network activity (consuming negligible resources when it does)
• When it goes into standby mode, the unikernel’s state gets snapshotted and can be restored exactly as it was when it went to sleep. This could be useful if you want to reuse a session’s state (browser auth cookies, interact with local files, browser settings, even the exact page and window zoom you were on).
• Extremely fast cold restarts (<20ms), which could be useful for any application that requires super low latency event handlers.

Demo

https://github.com/user-attachments/assets/5888e823-5867-4c01-ad67-ec8989ba9573

Running in Docker

You can build and run the Dockerfile directly as a Docker container.

cd images/chromium-headful
IMAGE=kernel-docker ./build-docker.sh
IMAGE=kernel-docker ENABLE_WEBRTC=true ./run-docker.sh

Running on a Unikernel

Alternatively, you can run the browser on a Unikraft unikernel.

1. Install the Kraft CLI

curl -sSfL https://get.kraftkit.sh | sh

2. Add Unikraft Secret to Your CLI

export UKC_METRO=<region> export UKC_TOKEN=<secret>

3. Build the image

IMAGE=YOUR_UKC_USERNAME/chromium-headless-test:latest images/chromium-headless/build-unikernel.sh

4. Run it

IMAGE=YOUR_UKC_USERNAME/chromium-headless-test:latest images/chromium-headless/run-unikernel.sh or IMAGE=YOUR_UKC_USERNAME/chromium-headful-test:latest VOLIMPORT_PREFIX=official images/chromium-headful/run-unikernel.sh

When the deployment finishes successfully, the Kraft CLI will print out something like this:

Deployed successfully!
 │
 ├───────── name: kernel-cu
 ├───────── uuid: 0cddb958...
 ├──────── metro: <region>
 ├──────── state: starting
 ├─────── domain: https://<service_name>.kraft.host
 ├──────── image: onkernel/kernel-cu@sha256:8265f3f188...
 ├─────── memory: 8192 MiB
 ├────── service: <service_name>
 ├─ private fqdn: <id>
 ├─── private ip: <ip>
 └───────── args: /wrapper

Unikernel Notes

• The image requires at least 8gb of memory.
• To deploy the implementation with WebRTC desktop streaming enabled instead of noVNC: ENABLE_WEBRTC=true NEKO_ICESERVERS=xxx ./run-unikernel.sh
• Deploying to Unikraft Cloud requires the usage of a TURN server when ENABLE_WEBRTC=true, as direct exposure of UDP ports is not currently supported. NEKO_ICESERVERS: Describes multiple STUN and TURN server that can be used by the ICEAgent to establish a connection with a peer. e.g. [{"urls": ["turn:turn.example.com:19302", "stun:stun.example.com:19302"], "username": "name", "credential": "password"}, {"urls": ["stun:stun.example2.com:19302"]}].
• Various services (openbox, tint) take a few seconds to start-up. Once they do, the standby and restart time is extremely fast.
• The Unikraft deployment generates a url. This url is public, meaning anyone can access the remote GUI if they have the url. Only use this for non-sensitive browser interactions, and delete the unikernel instance when you're done.
• You can call browser.close() to disconnect to the browser, and the unikernel will go into standby after network activity ends. You can then reconnect to the instance using CDP. browser.close() ends the websocket connection but doesn't actually close the browser.
• VCPUS value can be adjusted using the variable: VCPUS=8

Connect to the browser via Chrome DevTools Protocol

Port 9222 is exposed via ncat, allowing you to connect Chrome DevTools Protocol-based browser frameworks like Playwright and Puppeteer. You can use these frameworks to drive the browser in the cloud. You can also disconnect from the browser and reconnect to it.

First, fetch the browser's CDP websocket endpoint:

const url = new URL("http://localhost:9222/json/version");
const response = await fetch(url, {
  headers: {
    "Host": "<this can be anything>" // Required if using a unikernel
  }
});
if (response.status !== 200) {
  throw new Error(
    `Failed to retrieve browser instance: ${
      response.statusText
    } ${await response.text()}`
  );
}
// webSocketDebuggerUrl should look like:
// ws:///devtools/browser/06acd5ef-9961-431d-b6a0-86b99734f816
const { webSocketDebuggerUrl } = await response.json();

Then, connect a remote Playwright or Puppeteer client to it:

// Puppeteer
const browser = await puppeteer.connect({
  browserWSEndpoint: webSocketDebuggerUrl,
});
// Playwright
const browser = await chromium.connectOverCDP(webSocketDebuggerUrl);

Browser Remote GUI / Live View

You can use the embedded live view to monitor and control the browser. The live view supports both read and write access to the browser. Both map to port 443.

• NoVNC: A VNC client. Read/write is supported. Set ENABLE_WEBRTC=false in ./run-docker.sh.
• WebRTC: A WebRTC-based client. Read/write, window resizing, and copy/paste is supported. It's much faster than VNC. Available when ENABLE_WEBRTC=true is set.

This is the beginning of the README. Read the rest at the original. Read the full README ↗