server

package module

v0.0.0-...-75e0b32 Latest Latest Go to latest Published: Oct 15, 2026 License: Apache-2.0 Imports: 1 Imported by: 0

Details

Valid go.mod file
Redistributable license
Tagged version
Stable version
Learn more about best practices

Repository

github.com/kernel/kernel-images

Links

Open Source Insights

README ¶

Kernel Images Server

A REST API server to start, stop, and download screen recordings.

🛠️ Prerequisites

Required Software

Go 1.24.3+ - Programming language runtime
ffmpeg - Video recording engine
- macOS: brew install ffmpeg
- Linux: sudo apt install ffmpeg or sudo yum install ffmpeg
pnpm - For OpenAPI code generation
- npm install -g pnpm

System Requirements

macOS: Uses AVFoundation for screen capture
Linux: Uses X11 for screen capture
Windows: Not currently supported

🚀 Quick Start

Running the Server

make dev

The server will start on port 10001 by default and log its configuration.

Example use

# 1. Start a new recording
curl http://localhost:10001/recording/start -d {}

# (recording in progress)

# 2. Stop recording
curl http://localhost:10001/recording/stop -d {}

# 3. Download the recorded file
curl http://localhost:10001/recording/download --output recording.mp4

⚙️ Configuration

Configure the server using environment variables:

Variable	Default	Description
`PORT`	`10001`	HTTP server port
`METRICS_PORT`	`10002`	Prometheus metrics port (`GET /metrics`)
`FRAME_RATE`	`10`	Default recording framerate (fps)
`DISPLAY_NUM`	`1`	Display/screen number to capture
`MAX_SIZE_MB`	`500`	Default maximum file size (MB)
`OUTPUT_DIR`	`.`	Directory to save recordings
`FFMPEG_PATH`	`ffmpeg`	Path to the ffmpeg binary
`KERNEL_METRO_API_BASE_URL`		Metro API base URL; answers the WebAuthn page hook (`PUT /webauthn/hook`)
`KERNEL_INSTANCE_JWT`		Instance credential sent to the metro API and the OTLP relay

Example Configuration

export PORT=8080
export FRAME_RATE=30
export MAX_SIZE_MB=1000
export OUTPUT_DIR=/tmp/recordings
./bin/api

API Documentation

YAML Spec: GET /spec.yaml
JSON Spec: GET /spec.json
Browser REPL guide: docs/repl.md

🔧 Development

Code Generation

The server uses OpenAPI code generation. After modifying openapi.yaml:

make oapi-generate

🧪 Testing

Running Tests

make test

Documentation ¶

Index ¶

Variables

Constants ¶

This section is empty.

Variables ¶

View Source

var OpenAPIYAML []byte

Functions ¶

This section is empty.

Types ¶

This section is empty.

Source Files ¶

View all Source files

openapi.go

Directories ¶

Path	Synopsis
cmd
api command
api/api
chromium-launcher command
config
shell command
supervisord-shim command Command supervisord-shim is a tiny supervisord eventlistener that translates PROCESS_STATE_EXITED (expected=0) and PROCESS_STATE_FATAL events into BrowserServiceCrashedEvent payloads and POSTs them to the local kernel-images-api telemetry endpoint.	Command supervisord-shim is a tiny supervisord eventlistener that translates PROCESS_STATE_EXITED (expected=0) and PROCESS_STATE_FATAL events into BrowserServiceCrashedEvent payloads and POSTs them to the local kernel-images-api telemetry endpoint.
wrapper command wrapper boots the chromium-headful and chromium-headless containers: prepares the environment, starts supervisord, brings services up in parallel where the dependency graph allows, and waits for CDP to be reachable through kernel-images-api.	wrapper boots the chromium-headful and chromium-headless containers: prepares the environment, starts supervisord, brings services up in parallel where the dependency graph allows, and waits for CDP to be reachable through kernel-images-api.
e2e
lib
browserlocation Package browserlocation describes the explicit locale and timezone values that the browser and image shipped together can apply.	Package browserlocation describes the explicit locale and timezone values that the browser and image shipped together can apply.
browsersurface
cdpclient
cdpmonitor
chromedriverproxy
chromiumflags
devtoolsproxy
egresspolicy Package egresspolicy holds what the VM has been told about the egress policy its session runs under.	Package egresspolicy holds what the VM has been told about the egress policy its session runs under.
events
forkidentity
livefocus Package livefocus tells the live view which editable element has focus in the browser, so a touch client can raise its soft keyboard for real text fields only, with the right keyboard, and close it when the field loses focus.	Package livefocus tells the live view which editable element has focus in the browser, so a touch client can raise its soft keyboard for real text fields only, with the right keyboard, and close it when the field loses focus.
logger
metrics Package metrics exposes VM- and browser-level metrics in the Prometheus text exposition format, intended to be scraped by an external collector and aggregated across VMs.	Package metrics exposes VM- and browser-level metrics in the Prometheus text exposition format, intended to be scraped by an external collector and aggregated across VMs.
mousetrajectory
nekoclient
oapi Package oapi provides primitives to interact with the openapi HTTP API.	Package oapi provides primitives to interact with the openapi HTTP API.
policy
ptyio Package ptyio provides shared utilities for PTY I/O operations and WebSocket attach protocol types.	Package ptyio provides shared utilities for PTY I/O operations and WebSocket attach protocol types.
recorder
scaletozero
statefile Package statefile writes the small JSON files that hold state the control plane hands the VM, so it survives a restart of the API process.	Package statefile writes the small JSON files that hold state the control plane hands the VM, so it survives a restart of the API process.
sysmon kmsg.go parses the kernel OOM-dump text inside /dev/kmsg messages.	kmsg.go parses the kernel OOM-dump text inside /dev/kmsg messages.
telemetry
typinghumanizer
webauthnhook Package webauthnhook answers pages' navigator.credentials.get/create publicKey requests with passkeys held outside the VM.	Package webauthnhook answers pages' navigator.credentials.get/create publicKey requests with passkeys held outside the VM.
webmcpclient
wsdrain Package wsdrain tracks live WebSocket connections so they can be closed with a single status code when the server shuts down.	Package wsdrain tracks live WebSocket connections so they can be closed with a single status code when the server shuts down.
wsproxy
x11 Package x11 provides helpers for talking to a local X server.	Package x11 provides helpers for talking to a local X server.
ziputil
zstdutil Package zstdutil provides utilities for creating and extracting tar.zst archives.	Package zstdutil provides utilities for creating and extracting tar.zst archives.
scripts
categorygen command Command categorygen derives the authoritative category lookups from openapi.yaml.	Command categorygen derives the authoritative category lookups from openapi.yaml.
cdpmanifest command Command cdpmanifest regenerates the pinned CDP argument snapshot that TestEveryCanonicalArgumentHasADecision checks the sanitizers against.	Command cdpmanifest regenerates the pinned CDP argument snapshot that TestEveryCanonicalArgumentHasADecision checks the sanitizers against.
concurrent_stop_test command Tool to reproduce Stop concurrency behavior: start a recording, trigger concurrent stops, then download and validate the resulting video with ffprobe.	Tool to reproduce Stop concurrency behavior: start a recording, trigger concurrent stops, then download and validate the resulting video with ffprobe.
oapi/patch_sse_methods command

?	: This menu
/	: Search site
f or F	: Jump to
y or Y	: Canonical URL