什么是 Kernel？

Kernel 提供沙箱化（sandboxed）、开箱即用的 Chrome 浏览器，用于浏览器自动化和 Web 代理（web agents）。本仓库为我们的托管服务提供支持。

立即注册 这里！

核心特性

• 沙箱化的 Chrome 浏览器，可被基于 Chrome DevTools 协议的浏览器框架（如 Playwright、Puppeteer）连接
• 支持远程图形界面访问（实时画面流），便于可视化监控与远程控制
• 可配置的实时视图设置（只读模式、浏览器窗口尺寸）
• 支持对浏览器会话进行可控的视频回放

你可以用它做什么

• 运行基于浏览器的自动化工作流
• 开发和测试使用浏览器的 AI 代理（AI agents）
• 构建需要受控浏览器环境的自定义工具

实现方式

该镜像可用于在 Docker 容器中运行带图形界面的 Chromium，或配合 Unikraft unikernel 使用。unikernel 实现基于基础 Docker 镜像，并额外具备以下优势：

• 当无网络活动时自动进入待机 / “睡眠模式”（此时资源消耗可忽略不计）
• 进入待机模式时，unikernel 的状态会被快照保存，并可在唤醒时精确恢复（包括浏览器认证 Cookie、本地文件交互、浏览器设置，甚至页面和窗口缩放比例）
• 极快的冷启动速度（<20ms），适用于任何需要超低延迟事件处理器的应用场景

演示

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

在 Docker 中运行

你可以直接构建并运行 Dockerfile 作为 Docker 容器。

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

在 Unikernel 上运行

你也可以选择在 Unikraft unikernel 上运行浏览器。

1. 安装 Kraft CLI

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

2. 为 CLI 添加 Unikraft 密钥

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

3. 构建镜像

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

4. 运行镜像

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

部署成功后，Kraft CLI 将输出类似如下内容：

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.sh

Unikernel 注意事项

• 该镜像至少需要 8GB 内存。
• 若需启用 WebRTC 桌面流而非 noVNC，请使用：ENABLE_WEBRTC=true NEKO_ICESERVERS=xxx ./run-unikernel.sh
• 当 ENABLE_WEBRTC=true 时，部署到 Unikraft Cloud 需要使用 TURN server，因为目前尚不支持直接暴露 UDP 端口。NEKO_ICESERVERS：描述多个 STUN 和 TURN 服务器，ICEAgent 可通过它们与对端建立连接。例如：[{"urls": ["turn:turn.example.com:19302", "stun:stun.example.com:19302"], "username": "name", "credential": "password"}, {"urls": ["stun:stun.example2.com:19302"]}]。
• 多个服务（如 mutter、tint）启动需数秒时间。启动完成后，待机与重启速度极快。
• Unikraft 部署会生成一个 URL。该 URL 是公开的，意味着任何人只要拥有该 URL 即可访问远程 GUI。请仅用于非敏感的浏览器交互，并在使用完毕后删除 unikernel 实例。
• 你可以调用 browser.close() 断开与浏览器的连接，当网络活动结束后，unikernel 会进入待机状态。之后可通过 CDP 重新连接实例。browser.close() 仅断开 websocket 连接，并不会真正关闭浏览器。
• 可通过变量调整 VCPUS 值：VCPUS=8

通过 Chrome DevTools Protocol 连接浏览器

端口 9222 通过 ncat 暴露，允许你连接基于 Chrome DevTools Protocol 的浏览器框架，如 Playwright、Puppeteer（以及基于 CDP 的 SDK，如 Browser Use）。你可以使用这些框架驱动云端的浏览器，也可断开后再重新连接。

首先，获取浏览器的 CDP websocket 端点：

const url = new URL("http://localhost:9222/json/version");
const response = await fetch(url, {
  headers: {
    "Host": "<this can be anything>" // 使用 unikernel 时必需
  }
});
if (response.status !== 200) {
  throw new Error(
    `Failed to retrieve browser instance: ${
      response.statusText
    } ${await response.text()}`
  );
}
// webSocketDebuggerUrl 应形如：
// ws:///devtools/browser/06acd5ef-9961-431d-b6a0-86b99734f816
const { webSocketDebuggerUrl } = await response.json();

然后，连接远程的 Playwright 或 Puppeteer 客户端：

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

浏览器远程 GUI / 实时视图

你可以使用内嵌的实时视图来监控和控制浏览器。实时视图支持对浏览器的读写操作。二者均映射到端口 443。

• NoVNC：VNC 客户端，支持读写操作。在 ./run-docker.sh 中设置 ENABLE_WEBRTC=false。
• WebRTC：基于 WebRTC 的客户端，支持读写、窗口缩放及复制粘贴功能，比 VNC 快得多。需设置 ENABLE_WEBRTC=true 才可用。

注意事项

• WebRTC 实现中的音频流当前不可用，有待修复。
• 实时视图默认为读写模式。可通过在 docker run 中添加 -e ENABLE_READONLY_VIEW=true \ 设置为只读模式。

录像捕获

你可以使用内置的录制服务器，在我们的有头（headful）镜像中捕获整个屏幕的录像。该功能一次仅支持一个录制会话，可通过设置 WITH_KERNEL_IMAGES_API=true 启用。

例如：

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

# 1. 开始新录制
curl http://localhost:10001/recording/start -d {}

# 正在录制中 —— 运行你的 agent

# 2. 停止录制
curl http://localhost:10001/recording/stop -d {}

# 3. 下载录制文件
curl http://localhost:10001/recording/download --output recording.mp4

注意：录制文件被编码为 H.264/MPEG-4 AVC 视频格式。QuickTime 存在已知播放问题，请确保使用兼容的媒体播放器！

文档

本仓库为我们的托管 浏览器基础设施（browser infrastructure） 提供支持。

贡献

提交 Pull Request 或 Issue 前，请先阅读我们的 贡献指南（contribution guidelines）。

许可证

详情请参阅 LICENSE 文件。

支持

如遇问题、疑问或反馈，请在此仓库 提交 Issue。你也可以加入我们的 Discord 社区。

致谢

• 我们的 WebRTC 实现改编自 Neko。
• 感谢 xonkernel 主导开发了我们的 WebRTC 实时预览功能。
• 感谢 Unikraft Cloud 团队在 unikernel 方面提供的帮助。

由 Kernel 团队 ❤️ 制作。

Kernel Images 快速上手指南

环境准备

• 系统要求：Linux 或 macOS（推荐 Ubuntu 20.04+ / macOS 12+）
• 内存要求：至少 8GB RAM（Unikernel 模式必需）
• 前置依赖：
  • Docker（用于容器模式）
  • Node.js + npm（用于连接 CDP 客户端，如 Puppeteer/Playwright）
  • 可选：Kraft CLI（用于 Unikernel 部署）

国内用户建议配置 Docker Hub 镜像加速器（如阿里云、腾讯云镜像源）以提升拉取速度。

---

安装步骤

方式一：Docker 容器运行（推荐新手）

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

方式二：Unikernel 运行（高性能场景）

1. 安装 Kraft CLI：

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

2. 设置 Unikraft Cloud 凭据：

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

3. 构建并运行：

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

成功部署后，CLI 将输出访问 URL（如 https://<service_name>.kraft.host），请妥善保管。

---

基本使用

1. 通过 CDP 连接浏览器（Puppeteer/Playwright）

获取 WebSocket 调试地址：

const url = new URL("http://localhost:9222/json/version");
const response = await fetch(url, {
  headers: {
    "Host": "<任意值>" // Unikernel 模式必需
  }
});
const { webSocketDebuggerUrl } = await response.json();

连接 Puppeteer：

const browser = await puppeteer.connect({
  browserWSEndpoint: webSocketDebuggerUrl,
});

或连接 Playwright：

const browser = await chromium.connectOverCDP(webSocketDebuggerUrl);

2. 启用远程 GUI 监控（WebRTC 推荐）

启动时设置 ENABLE_WEBRTC=true，即可通过浏览器访问实时桌面界面（默认端口 443）。

3. 录制屏幕操作（可选）

启动容器时启用录制 API：

WITH_KERNEL_IMAGES_API=true ENABLE_WEBRTC=true ./run-docker.sh

录制流程：

# 开始录制
curl http://localhost:10001/recording/start -d {}

# 执行你的自动化任务...

# 停止录制
curl http://localhost:10001/recording/stop -d {}

# 下载视频
curl http://localhost:10001/recording/download --output recording.mp4

录制文件为 H.264 格式，建议使用 VLC 或 MPV 播放（QuickTime 可能不兼容）。