diff --git a/images/chromium-headful/Dockerfile b/images/chromium-headful/Dockerfile
index 4be552d4..7319c8c0 100644
--- a/images/chromium-headful/Dockerfile
+++ b/images/chromium-headful/Dockerfile
@@ -1,96 +1,114 @@
-# webrtc client
+###############################################################################
+# Stage 1 ─────────────────────────────────────────────────────────────────────
+# Build WebRTC client frontend
+###############################################################################
 FROM node:22-bullseye-slim AS client
+
 WORKDIR /src
 COPY client/package*.json ./
 RUN npm install
 COPY client/ .
 RUN npm run build
 
-# xorg dependencies
-FROM docker.io/ubuntu:22.04 AS xorg-deps
+
+###############################################################################
+# Stage 2 ─────────────────────────────────────────────────────────────────────
+# Build custom Xorg dummy video driver (xf86-video-dummy v0.3.8 + RandR patch)
+# and the custom input driver (xf86-input-neko)
+###############################################################################
+FROM ubuntu:22.04 AS xorg-deps
 WORKDIR /xorg
 ENV DEBIAN_FRONTEND=noninteractive
+
+
+# Build-time dependencies for Xorg modules
 RUN set -eux; \
     apt-get update; \
     apt-get install -y \
     git gcc pkgconf autoconf automake libtool make xorg-dev xutils-dev \
     && rm -rf /var/lib/apt/lists/*;
+
 COPY xorg-deps/ /xorg/
-# build xf86-video-dummy v0.3.8 with RandR support
-RUN set -eux; \
-    cd xf86-video-dummy/v0.3.8; \
-    patch -p1 < ../01_v0.3.8_xdummy-randr.patch; \
-    autoreconf -v --install; \
-    ./configure; \
-    make -j$(nproc); \
-    make install;
-# build custom input driver
-RUN set -eux; \
-    cd xf86-input-neko; \
-    ./autogen.sh --prefix=/usr; \
-    ./configure; \
-    make -j$(nproc); \
-    make install;
 
+# Build xf86-video-dummy v0.3.8 with RandR support
+RUN cd xf86-video-dummy/v0.3.8 && \
+    patch -p1 < ../01_v0.3.8_xdummy-randr.patch && \
+    autoreconf -v --install && \
+    ./configure && \
+    make -j"$(nproc)" && \
+    make install
+
+# Build custom input driver
+RUN cd xf86-input-neko && \
+    ./autogen.sh --prefix=/usr && \
+    ./configure && \
+    make -j"$(nproc)" && \
+    make install
+
+
+###############################################################################
+# Stage 3 ─────────────────────────────────────────────────────────────────────
+# Extract neko executable from upstream image
+###############################################################################
 FROM ghcr.io/onkernel/neko/base:3.0.6-v1.0.1 AS neko
-# ^--- now has event.SYSTEM_PONG with legacy support to keepalive
+
+
+###############################################################################
+# Stage 4 ─────────────────────────────────────────────────────────────────────
+# Final runtime image
+###############################################################################
 FROM docker.io/ubuntu:22.04
 
 ENV DEBIAN_FRONTEND=noninteractive
 ENV DEBIAN_PRIORITY=high
 
-RUN apt-get update && \
-    apt-get -y upgrade && \
+###############################################################################
+# Base OS & core toolchain & apps
+###############################################################################
+RUN set -eux; \
+    apt-get update; \
+    apt-get -y upgrade; \
     apt-get -y install \
-    # UI Requirements
-    xvfb \
-    xterm \
-    xdotool \
-    scrot \
-    imagemagick \
-    sudo \
-    mutter \
-    x11vnc \
-    # Python/pyenv reqs
-    build-essential \
-    libssl-dev  \
-    zlib1g-dev \
-    libbz2-dev \
-    libreadline-dev \
-    libsqlite3-dev \
-    curl \
-    git \
-    libncursesw5-dev \
-    xz-utils \
-    tk-dev \
-    libxml2-dev \
-    libxmlsec1-dev \
-    libffi-dev \
-    liblzma-dev \
-    # Network tools
-    net-tools \
-    netcat \
-    # PPA req
-    software-properties-common && \
-    # Userland apps
-    sudo add-apt-repository ppa:mozillateam/ppa && \
+        xvfb xterm xdotool scrot imagemagick sudo mutter x11vnc upower \
+        build-essential libssl-dev zlib1g-dev libbz2-dev libreadline-dev libsqlite3-dev \
+        curl git libncursesw5-dev xz-utils tk-dev libxml2-dev libxmlsec1-dev libffi-dev liblzma-dev \
+        net-tools netcat software-properties-common; \
+    \
+    sudo add-apt-repository ppa:mozillateam/ppa; \
     sudo apt-get install -y --no-install-recommends \
-    chromium-browser \
-    libreoffice \
-    x11-apps \
-    xpdf \
-    gedit \
-    xpaint \
-    tint2 \
-    galculator \
-    pcmanfm \
-    wget \
-    xdg-utils \
-    libvulkan1 \
-    fonts-liberation \
-    unzip && \
+        chromium-browser libreoffice x11-apps xpdf gedit xpaint tint2 galculator pcmanfm \
+        wget xdg-utils libvulkan1 fonts-liberation unzip; \
     apt-get clean
 
+
+###############################################################################
+# Locales & fonts
+###############################################################################
+RUN apt-get update && \
+    apt-get install -y --no-install-recommends locales && \
+    printf "%s\n" \
+        "en_US.UTF-8 UTF-8" "en_GB.UTF-8 UTF-8" "es_ES.UTF-8 UTF-8" \
+        "es_MX.UTF-8 UTF-8" "fr_FR.UTF-8 UTF-8" "de_DE.UTF-8 UTF-8" \
+        "it_IT.UTF-8 UTF-8" "pt_PT.UTF-8 UTF-8" "pt_BR.UTF-8 UTF-8" \
+        "nl_NL.UTF-8 UTF-8" "sv_SE.UTF-8 UTF-8" "no_NO.UTF-8 UTF-8" \
+        "da_DK.UTF-8 UTF-8" "fi_FI.UTF-8 UTF-8" "tr_TR.UTF-8 UTF-8" \
+        "vi_VN.UTF-8 UTF-8" "id_ID.UTF-8 UTF-8" "bn_IN.UTF-8 UTF-8" \
+        "pa_IN.UTF-8 UTF-8" "zh_CN.UTF-8 UTF-8" "zh_TW.UTF-8 UTF-8" \
+        "ja_JP.UTF-8 UTF-8" "ko_KR.UTF-8 UTF-8" "ar_SA.UTF-8 UTF-8" \
+        "hi_IN.UTF-8 UTF-8" "ru_RU.UTF-8 UTF-8" "th_TH.UTF-8 UTF-8" \
+        "el_GR.UTF-8 UTF-8" "he_IL.UTF-8 UTF-8" \
+        > /etc/locale.gen && \
+    locale-gen && \
+    update-locale LANG=en_US.UTF-8 && \
+    apt-get install -y --no-install-recommends \
+        fonts-noto-core fonts-noto-ui-core fonts-noto-cjk fonts-noto-cjk-extra && \
+    apt-get clean && \
+    rm -rf /var/lib/apt/lists/*
+
+
+###############################################################################
+# FFmpeg (static build, latest 7.x)
+###############################################################################
 # install ffmpeg manually since the version available in apt is from the 4.x branch due to #drama.
 # as of writing these static builds will be the latest 7.0.x release.
 RUN set -eux; \
@@ -102,72 +120,160 @@ RUN set -eux; \
     install -m755 /tmp/ffmpeg-*/ffprobe /usr/local/bin/ffprobe; \
     rm -rf /tmp/ffmpeg*
 
-# runtime
-ENV USERNAME=root
-RUN set -eux; \
-    apt-get update; \
+
+###############################################################################
+# Runtime dependencies, libxcvt, user creation, directory setup
+###############################################################################
+ARG KERNEL_USER=kernel
+ARG KERNEL_UID=1000
+ARG KERNEL_GID=$KERNEL_UID
+
+RUN apt-get update && \
     apt-get install -y --no-install-recommends \
-    wget ca-certificates python2 supervisor xclip xdotool \
-    pulseaudio dbus-x11 xserver-xorg-video-dummy \
-    libcairo2 libxcb1 libxrandr2 libxv1 libopus0 libvpx7 \
-    gstreamer1.0-plugins-base gstreamer1.0-plugins-good \
-    gstreamer1.0-plugins-bad gstreamer1.0-plugins-ugly \
-    gstreamer1.0-pulseaudio gstreamer1.0-omx; \
-    #
-    # install libxcvt0 (not available in debian:bullseye)
-    ARCH=$(dpkg --print-architecture); \
-    wget http://ftp.de.debian.org/debian/pool/main/libx/libxcvt/libxcvt0_0.1.2-1_${ARCH}.deb; \
-    apt-get install --no-install-recommends ./libxcvt0_0.1.2-1_${ARCH}.deb; \
-    rm ./libxcvt0_0.1.2-1_${ARCH}.deb; \
-    #
+        wget ca-certificates python2 supervisor xclip xdotool \
+        pulseaudio dbus-x11 xserver-xorg-video-dummy rtkit \
+        libcairo2 libxcb1 libxrandr2 libxv1 libopus0 libvpx7 \
+        gstreamer1.0-plugins-base gstreamer1.0-plugins-good \
+        gstreamer1.0-plugins-bad gstreamer1.0-plugins-ugly \
+        gstreamer1.0-pulseaudio gstreamer1.0-omx && \
+    \
+    # libxcvt0 (Debian package, not in Ubuntu repo)
+    ARCH=$(dpkg --print-architecture) && \
+    curl -fsSL http://ftp.de.debian.org/debian/pool/main/libx/libxcvt/libxcvt0_0.1.2-1_${ARCH}.deb \
+        -o /tmp/libxcvt.deb && \
+    apt-get install -y --no-install-recommends /tmp/libxcvt.deb && \
+    rm /tmp/libxcvt.deb && \
+    \
+    # Non-root user with audio/video privileges
+    groupadd --gid "$KERNEL_GID" "$KERNEL_USER" && \
+    useradd  --uid "$KERNEL_UID" --gid "$KERNEL_GID" \
+             --shell /bin/bash --create-home "$KERNEL_USER" && \
+    for g in audio video pulse pulse-access; do adduser "$KERNEL_USER" "$g"; done && \
+    \
     # workaround for an X11 problem: http://blog.tigerteufel.de/?p=476
-    mkdir /tmp/.X11-unix; \
-    chmod 1777 /tmp/.X11-unix; \
-    chown $USERNAME /tmp/.X11-unix/; \
-    #
-    # make directories for neko
+    mkdir -p /tmp/.X11-unix && \
+    chmod 1777 /tmp/.X11-unix && \
+    chown "$KERNEL_USER:$KERNEL_USER" /tmp/.X11-unix && \
+    \
+    # Make directories for neko
     mkdir -p /etc/neko /var/www /var/log/neko \
-    /tmp/runtime-$USERNAME \
-    /home/$USERNAME/.config/pulse  \
-    /home/$USERNAME/.local/share/xorg; \
-    chmod 1777 /var/log/neko; \
-    chown $USERNAME /var/log/neko/ /tmp/runtime-$USERNAME; \
-    chown -R $USERNAME:$USERNAME /home/$USERNAME; \
-    # clean up
-    apt-get clean -y; \
+             /tmp/runtime-"$KERNEL_USER" \
+             /home/"$KERNEL_USER"/.config \
+             /home/"$KERNEL_USER"/.local/share/xorg && \
+    chmod 1777 /var/log/neko && \
+    chown -R "$KERNEL_USER:$KERNEL_USER" \
+           /var/log/neko /tmp/runtime-"$KERNEL_USER" /home/"$KERNEL_USER" && \
+    chmod 777 /etc/pulse || true && \
+    apt-get clean && \
     rm -rf /var/lib/apt/lists/* /var/cache/apt/
 
-# install chromium & ncat for proxying the remote debugging port
-RUN add-apt-repository -y ppa:xtradeb/apps
-RUN apt update -y && apt install -y chromium ncat
 
-# Install noVNC
+###############################################################################
+# Chromium (via xtradeb) & ncat
+###############################################################################
+RUN add-apt-repository -y ppa:xtradeb/apps && \
+    apt-get update && \
+    apt-get install -y --no-install-recommends chromium ncat && \
+    apt-get clean && \
+    rm -rf /var/lib/apt/lists/*
+
+
+###############################################################################
+# noVNC (v1.5.0) + Websockify (v0.12.0)
+###############################################################################
 RUN git clone --branch v1.5.0 https://github.com/novnc/noVNC.git /opt/noVNC && \
     git clone --branch v0.12.0 https://github.com/novnc/websockify /opt/noVNC/utils/websockify && \
     ln -s /opt/noVNC/vnc.html /opt/noVNC/index.html
 
-# setup desktop env & app
-ENV DISPLAY_NUM=1
-ENV HEIGHT=768
-ENV WIDTH=1024
-ENV WITHDOCKER=true
 
-COPY xorg.conf /etc/neko/xorg.conf
-COPY neko.yaml /etc/neko/neko.yaml
-COPY --from=neko /usr/bin/neko /usr/bin/neko
-COPY --from=client /src/dist/ /var/www
-COPY --from=xorg-deps /usr/local/lib/xorg/modules/drivers/dummy_drv.so /usr/lib/xorg/modules/drivers/dummy_drv.so
-COPY --from=xorg-deps /usr/local/lib/xorg/modules/input/neko_drv.so /usr/lib/xorg/modules/input/neko_drv.so
+###############################################################################
+# Environment
+###############################################################################
+ENV DISPLAY_NUM=1 \
+    HEIGHT=768 \
+    WIDTH=1024 \
+    WITHDOCKER=true
+
+
+###############################################################################
+# Copy build artefacts & configurations
+###############################################################################
+COPY xorg.conf            /etc/neko/xorg.conf
+COPY default.pa           /etc/pulse/default.pa
+COPY daemon.conf          /etc/pulse/daemon.conf
+COPY dbus-pulseaudio.conf /etc/dbus-1/system.d/pulseaudio.conf
+COPY dbus-mpris.conf      /etc/dbus-1/system.d/mpris.conf
+COPY neko.yaml            /etc/neko/neko.yaml
+
+# Executables & drivers from previous stages
+COPY --from=neko   /usr/bin/neko /usr/bin/neko
+COPY --from=client /src/dist/    /var/www
+COPY --from=xorg-deps /usr/local/lib/xorg/modules/drivers/dummy_drv.so \
+                      /usr/lib/xorg/modules/drivers/dummy_drv.so
+COPY --from=xorg-deps /usr/local/lib/xorg/modules/input/neko_drv.so  \
+                      /usr/lib/xorg/modules/input/neko_drv.so
+
+RUN chown -R "$KERNEL_USER:$KERNEL_USER" /var/www /etc/neko
 
+
+###############################################################################
+# Additional assets & wrapper
+###############################################################################
 COPY image-chromium/ /
-COPY ./wrapper.sh /wrapper.sh
+COPY wrapper.sh      /wrapper.sh
+
 
-# copy the kernel-images API binary built externally
+###############################################################################
+# Copy the kernel-images API binary built externally
+###############################################################################
 COPY bin/kernel-images-api /usr/local/bin/kernel-images-api
 ENV WITH_KERNEL_IMAGES_API=false
 
-RUN useradd -m -s /bin/bash kernel
+###############################################################################
+# Copy the kernel-operator artifacts built externally
+###############################################################################
+RUN mkdir -p /tmp/kernel-operator
+
+COPY bin/kernel-operator-api /usr/local/bin/kernel-operator-api
+COPY bin/kernel-operator-test /usr/local/bin/kernel-operator-test
+COPY bin/.kernel-operator.env /tmp/kernel-operator/.kernel-operator.env
+
+RUN chmod +x /usr/local/bin/kernel-images-api \
+             /usr/local/bin/kernel-operator-api \
+             /usr/local/bin/kernel-operator-test
+
+ENV WITH_KERNEL_OPERATOR_API=false
+ENV DEBUG_OPERATOR_TEST=false
+
+###############################################################################
+# Grant kernel user + kernel operator api a lot of freedom
+###############################################################################
+# Passwordless sudo for "kernel" to execute arbitrary root commands when needed
+RUN echo 'kernel ALL=(ALL) NOPASSWD:ALL' >/etc/sudoers.d/010-kernel-nopw && chmod 0440 /etc/sudoers.d/010-kernel-nopw
+# Grant broad Linux capabilities to the operator API and tests while running as "kernel"
+# This preserves the "kernel" user identity but lifts FS/NET/NS limits typical for root tasks
+# To be adjusted for required capabilities range.
+RUN setcap 'cap_chown,cap_fowner,cap_fsetid,cap_dac_override,cap_dac_read_search,cap_mknod,cap_sys_admin,cap_sys_resource,cap_sys_ptrace,cap_sys_time,cap_sys_tty_config,cap_net_admin,cap_net_raw,cap_setuid,cap_setgid=ep' /usr/local/bin/kernel-operator-api || true && \
+    setcap 'cap_chown,cap_fowner,cap_fsetid,cap_dac_override,cap_dac_read_search,cap_mknod,cap_sys_admin,cap_sys_resource,cap_sys_ptrace,cap_net_admin,cap_net_raw=ep' /usr/local/bin/kernel-operator-test || true
+
+
+###############################################################################
+# Set user data
+###############################################################################
 RUN cp -r ./user-data /home/kernel/user-data
 
-ENTRYPOINT [ "/wrapper.sh" ]
 
+###############################################################################
+# Runtime environment variables
+###############################################################################
+ENV USER=kernel \
+    XDG_RUNTIME_DIR=/tmp/runtime-kernel \
+    PULSE_SERVER=unix:${XDG_RUNTIME_DIR}/pulse/native \
+    XDG_CONFIG_HOME=/tmp/.chromium \
+    XDG_CACHE_HOME=/tmp/.chromium
+
+
+###############################################################################
+# Entrypoint
+###############################################################################
+ENTRYPOINT ["/wrapper.sh"]
\ No newline at end of file
diff --git a/images/chromium-headful/Kraftfile.erofs b/images/chromium-headful/Kraftfile.erofs
new file mode 100644
index 00000000..18af1a0b
--- /dev/null
+++ b/images/chromium-headful/Kraftfile.erofs
@@ -0,0 +1,12 @@
+spec: v0.6
+
+runtime: index.unikraft.io/official/base-compat:latest
+
+labels:
+  cloud.unikraft.v1.instances/scale_to_zero.policy: "idle"
+  cloud.unikraft.v1.instances/scale_to_zero.stateful: "true"
+  cloud.unikraft.v1.instances/scale_to_zero.cooldown_time_ms: 5000
+
+rootfs: ./initrd
+
+cmd: ["/wrapper.sh"]
diff --git a/images/chromium-headful/Kraftfile.no-erofs b/images/chromium-headful/Kraftfile.no-erofs
new file mode 100644
index 00000000..9364e423
--- /dev/null
+++ b/images/chromium-headful/Kraftfile.no-erofs
@@ -0,0 +1,12 @@
+spec: v0.6
+
+runtime: index.unikraft.io/official/base-compat:latest
+
+labels:
+  cloud.unikraft.v1.instances/scale_to_zero.policy: "on"
+  cloud.unikraft.v1.instances/scale_to_zero.stateful: "true"
+  cloud.unikraft.v1.instances/scale_to_zero.cooldown_time_ms: 4000
+
+rootfs: ./Dockerfile
+
+cmd: ["/wrapper.sh"]
\ No newline at end of file
diff --git a/images/chromium-headful/build-docker.sh b/images/chromium-headful/build-docker.sh
index 5f1db257..04693845 100755
--- a/images/chromium-headful/build-docker.sh
+++ b/images/chromium-headful/build-docker.sh
@@ -11,5 +11,8 @@ source ../../shared/start-buildkit.sh
 # Build the kernel-images API binary and place it into ./bin for Docker build context
 source ../../shared/build-server.sh "$(pwd)/bin"
 
+# Build operator api + test + .env → ./bin
+source ../../shared/build-operator-api.sh "$(pwd)/bin"
+
 # Build (and optionally push) the Docker image.
 docker build -t "$IMAGE" .
diff --git a/images/chromium-headful/build-unikernel.sh b/images/chromium-headful/build-unikernel.sh
index 0b16bf99..c01ad14a 100755
--- a/images/chromium-headful/build-unikernel.sh
+++ b/images/chromium-headful/build-unikernel.sh
@@ -1,37 +1,75 @@
 #!/usr/bin/env bash
 
+# Flag to control whether to use EROFS or not
+EROFS_DISABLE=${EROFS_DISABLE:-false}
+
 # Move to the script's directory so relative paths work regardless of the caller CWD
 SCRIPT_DIR=$(cd "$(dirname "$0")" && pwd)
 cd "$SCRIPT_DIR"
 source "$SCRIPT_DIR/../../shared/ensure-common-build-run-vars.sh" chromium-headful
-source "$SCRIPT_DIR/../../shared/erofs-utils.sh"
 
-# Ensure the mkfs.erofs tool is available
-if ! check_mkfs_erofs; then
-    echo "mkfs.erofs is not installed. Installing erofs-utils..."
-    install_erofs_utils
-fi
+# Copy the appropriate Kraftfile based on EROFS_DISABLE flag
+if [ "$EROFS_DISABLE" = "false" ]; then
+  echo "Using EROFS configuration (default)..."
+  cp Kraftfile.erofs Kraftfile
+  source "$SCRIPT_DIR/../../shared/erofs-utils.sh"
+
+  # Ensure the mkfs.erofs tool is available
+  if ! check_mkfs_erofs; then
+      echo "mkfs.erofs is not installed. Installing erofs-utils..."
+      install_erofs_utils
+  fi
+
+  set -euo pipefail  
+
+  # Build the root file system
+  source ../../shared/start-buildkit.sh
+
+  rm -rf ./.rootfs || true
+
+  # Build the API binary
+  source ../../shared/build-server.sh "$(pwd)/bin"
 
-set -euo pipefail  
-
-# Build the root file system
-source ../../shared/start-buildkit.sh
-rm -rf ./.rootfs || true
-# Build the API binary
-source ../../shared/build-server.sh "$(pwd)/bin"
-app_name=chromium-headful-build
-docker build --platform linux/amd64 -t "$IMAGE" .
-docker rm cnt-"$app_name" || true
-docker create --platform linux/amd64 --name cnt-"$app_name" "$IMAGE" /bin/sh
-docker cp cnt-"$app_name":/ ./.rootfs
-rm -f initrd || true
-sudo mkfs.erofs --all-root -d2 -E noinline_data -b 4096 initrd ./.rootfs
-
-# Package the unikernel (and the new initrd) to KraftCloud
-kraft pkg \
-  --name $UKC_INDEX/$IMAGE \
-  --plat kraftcloud \
-  --arch x86_64 \
-  --strategy overwrite \
-  --push \
-  .
+  # Build operator api + test + .env → ./bin
+  source ../../shared/build-operator-api.sh "$(pwd)/bin"
+
+  app_name=chromium-headful-build
+  docker build --platform linux/amd64 -t "$IMAGE" .
+  docker rm cnt-"$app_name" || true
+  docker create --platform linux/amd64 --name cnt-"$app_name" "$IMAGE" /bin/sh
+  docker cp cnt-"$app_name":/ ./.rootfs
+  rm -f initrd || true
+  # sudo mkfs.erofs --all-root -d2 -E noinline_data -b 4096 initrd ./.rootfs
+  # default block size is 4096 and -b fails for some reason, removed it
+  sudo mkfs.erofs --all-root -d2 -E noinline_data initrd ./.rootfs
+  
+  # Package the unikernel (and the new initrd) to KraftCloud
+  kraft pkg \
+    --name $UKC_INDEX/$IMAGE \
+    --plat kraftcloud \
+    --arch x86_64 \
+    --strategy overwrite \
+    --push \
+    .
+else
+  echo "Using non-EROFS configuration..."
+  cp Kraftfile.no-erofs Kraftfile
+  
+  set -euo pipefail  
+
+  source ../../shared/start-buildkit.sh
+
+  # Build the API binary
+  source ../../shared/build-server.sh "$(pwd)/bin"
+
+  # Build operator api + test + .env → ./bin
+  source ../../shared/build-operator-api.sh "$(pwd)/bin"
+
+  # Package the unikernel to KraftCloud
+  kraft pkg \
+    --name $UKC_INDEX/$IMAGE \
+    --plat kraftcloud --arch x86_64 \
+    --strategy overwrite \
+    --push \
+    .
+fi
diff --git a/images/chromium-headful/client/public/browserconfig.xml b/images/chromium-headful/client/public/browserconfig.xml
index ededce1f..0fd3ece4 100644
--- a/images/chromium-headful/client/public/browserconfig.xml
+++ b/images/chromium-headful/client/public/browserconfig.xml
@@ -3,7 +3,7 @@
     <msapplication>
         <tile>
             <square150x150logo src="/mstile-150x150.png"/>
-            <TileColor>#19bd9c</TileColor>
+            <TileColor>#7B42F6</TileColor>
         </tile>
     </msapplication>
 </browserconfig>
diff --git a/images/chromium-headful/client/public/index.html b/images/chromium-headful/client/public/index.html
index b9546790..9ffe2c34 100644
--- a/images/chromium-headful/client/public/index.html
+++ b/images/chromium-headful/client/public/index.html
@@ -9,9 +9,9 @@
     <link rel="icon" type="image/png" sizes="32x32" href="favicon-32x32.png">
     <link rel="icon" type="image/png" sizes="16x16" href="favicon-16x16.png">
     <link rel="manifest" href="site.webmanifest">
-    <link rel="mask-icon" href="safari-pinned-tab.svg" color="#19bd9c">
-    <meta name="msapplication-TileColor" content="#19bd9c">
-    <meta name="theme-color" content="#19bd9c">
+    <link rel="mask-icon" href="safari-pinned-tab.svg" color="#7B42F6">
+    <meta name="msapplication-TileColor" content="#7B42F6">
+    <meta name="theme-color" content="#7B42F6">
     <style> /* weird iOS bug, if this is not set right here, video just does not start */ .video-container { width: 100%; height: 100%; } </style>
   </head>
   <body>
diff --git a/images/chromium-headful/client/public/kernel.svg b/images/chromium-headful/client/public/kernel.svg
new file mode 100644
index 00000000..b9a86da4
--- /dev/null
+++ b/images/chromium-headful/client/public/kernel.svg
@@ -0,0 +1,4 @@
+<svg width="160" height="160" viewBox="0 0 160 160" fill="none" xmlns="http://www.w3.org/2000/svg">
+<path d="M84.7905 13.2211L74.9468 13.2435C64.1463 13.268 55.4105 22.0579 55.435 32.8763L55.4574 42.736C55.4617 44.6402 51.9834 47.1903 50.1741 46.606L40.8053 43.5805C30.5258 40.2608 19.5058 45.9165 16.1916 56.2129L13.171 65.5971C9.85673 75.8935 15.5032 86.9316 25.7827 90.2513L35.1515 93.2768C36.9612 93.8613 38.3148 97.954 37.2007 99.4974L31.4328 107.487C25.1042 116.254 27.069 128.499 35.8212 134.838L43.798 140.616C52.5503 146.955 64.7757 144.987 71.1043 136.22L76.8722 128.23C83.2008 119.464 81.236 107.218 72.4838 100.879L64.507 95.1018C61.7862 93.1312 58.7349 83.8452 59.7652 80.6443L62.7858 71.2602C63.8149 68.0632 71.7043 62.2875 75.0579 62.2799C75.0579 62.2799 81.1699 61.3326 84.9015 62.2575C90.661 63.6851 96.1677 67.9771 97.2129 71.1746L100.276 80.5449C103.637 90.8262 114.682 96.4318 124.947 93.0654L134.302 89.9973C144.566 86.6309 150.162 75.5673 146.802 65.286L143.739 55.9157C140.378 45.6345 129.332 40.0289 119.068 43.3953L109.713 46.4634C107.904 47.0566 104.418 44.5311 104.413 42.6248L104.391 32.765C104.367 21.9467 95.591 13.1966 84.7905 13.2211Z" fill="#AC86F9"/>
+<path d="M94.4445 115.668C94.4445 110.759 98.4241 106.779 103.333 106.779H125.556C130.465 106.779 134.444 110.759 134.444 115.668V137.89C134.444 142.799 130.465 146.779 125.556 146.779H103.333C98.4241 146.779 94.4445 142.799 94.4445 137.89V115.668Z" fill="#AC86F9"/>
+</svg>
diff --git a/images/chromium-headful/client/public/site.webmanifest b/images/chromium-headful/client/public/site.webmanifest
index 03c2b31f..4d1b7924 100644
--- a/images/chromium-headful/client/public/site.webmanifest
+++ b/images/chromium-headful/client/public/site.webmanifest
@@ -13,7 +13,7 @@
             "type": "image/png"
         }
     ],
-    "theme_color": "#19bd9c",
-    "background_color": "#19bd9c",
+    "theme_color": "#7B42F6",
+    "background_color": "#7B42F6",
     "display": "standalone"
 }
diff --git a/images/chromium-headful/client/src/assets/styles/_variables.scss b/images/chromium-headful/client/src/assets/styles/_variables.scss
index f74ac679..2f1fb4b4 100644
--- a/images/chromium-headful/client/src/assets/styles/_variables.scss
+++ b/images/chromium-headful/client/src/assets/styles/_variables.scss
@@ -21,10 +21,9 @@ $background-modifier-accent: hsla(0, 0%, 100%, 0.06);
 $elevation-low: 0 1px 0 rgba(4, 4, 5, 0.2), 0 1.5px 0 rgba(6, 6, 7, 0.05), 0 2px 0 rgba(4, 4, 5, 0.05);
 $elevation-high: 0 8px 16px rgba(0, 0, 0, 0.24);
 
-$style-primary: #19bd9c;
+$style-primary: #7B42F6;
 $style-error: #d32f2f;
 
 $menu-height: 40px;
 $controls-height: 125px;
 $side-width: 400px;
-
diff --git a/images/chromium-headful/client/src/components/connect.vue b/images/chromium-headful/client/src/components/connect.vue
index c850c642..2d175244 100644
--- a/images/chromium-headful/client/src/components/connect.vue
+++ b/images/chromium-headful/client/src/components/connect.vue
@@ -11,8 +11,7 @@
         </button>
       </form>
       <div class="loader" v-if="connecting">
-        <div class="bounce1"></div>
-        <div class="bounce2"></div>
+        <img src="/kernel.svg" class="spinning-logo" alt="Loading..." />
       </div>
     </div>
   </div>
@@ -103,40 +102,25 @@
       .loader {
         width: 90px;
         height: 90px;
-        position: relative;
         margin: 0 auto;
+        display: flex;
+        justify-content: center;
+        align-items: center;
 
-        .bounce1,
-        .bounce2 {
+        .spinning-logo {
           width: 100%;
           height: 100%;
-          border-radius: 50%;
-          background-color: $style-primary;
-          opacity: 0.6;
-          position: absolute;
-          top: 0;
-          left: 0;
-
-          -webkit-animation: bounce 2s infinite ease-in-out;
-          animation: bounce 2s infinite ease-in-out;
-        }
-
-        .bounce2 {
-          -webkit-animation-delay: -1s;
-          animation-delay: -1s;
+          animation: spin 2s linear infinite;
         }
       }
     }
 
-    @keyframes bounce {
-      0%,
-      100% {
-        transform: scale(0);
-        -webkit-transform: scale(0);
+    @keyframes spin {
+      from {
+        transform: rotate(0deg);
       }
-      50% {
-        transform: scale(1);
-        -webkit-transform: scale(1);
+      to {
+        transform: rotate(360deg);
       }
     }
   }
diff --git a/images/chromium-headful/client/src/components/video.vue b/images/chromium-headful/client/src/components/video.vue
index 4c4fe0f8..ecbcb263 100644
--- a/images/chromium-headful/client/src/components/video.vue
+++ b/images/chromium-headful/client/src/components/video.vue
@@ -1,6 +1,6 @@
 <template>
   <div ref="component" class="video">
-    <div ref="player" class="player">
+    <div ref="player" class="player" :class="{ 'is-muted': muted }">
       <div ref="container" class="player-container">
         <video ref="video" playsinline />
         <div class="emotes">
@@ -85,6 +85,19 @@
 </template>
 
 <style lang="scss" scoped>
+  /* KERNEL MODIFICATION: Keyframes for the mute indicator pulse effect */
+  @keyframes mute-pulse {
+    0% {
+      box-shadow: inset 0 0 0 2px rgba(255, 80, 80, 0.2);
+    }
+    50% {
+      box-shadow: inset 0 0 0 2px rgba(255, 80, 80, 0.4);
+    }
+    100% {
+      box-shadow: inset 0 0 0 2px rgba(255, 80, 80, 0.2);
+    }
+  }
+
   .video {
     width: 100%;
     height: 100%;
@@ -96,6 +109,11 @@
       align-items: center;
       background: #000;
 
+      /* KERNEL MODIFICATION: Style for the mute indicator */
+      &.is-muted {
+        animation: mute-pulse 2s infinite;
+      }
+
       .video-menu {
         position: absolute;
         right: 20px;
@@ -259,6 +277,10 @@
     private fullscreen = false
     private mutedOverlay = true
 
+    /* KERNEL MODIFICATION: State flag to ensure unmute happens only once. */
+    private hasInteracted = false
+    private unmuteHandler: (() => void) | null = null
+
     get admin() {
       return this.$accessor.user.admin
     }
@@ -470,6 +492,23 @@
       }
     }
 
+    /* KERNEL MODIFICATION: Centralized one-time unmute logic. */
+    _unmuteOnFirstInteraction() {
+      if (this.hasInteracted || !this.muted) {
+        return
+      }
+
+      this.hasInteracted = true
+      this.unmute()
+      this.$accessor.video.setVolume(100)
+
+      // Clean up global listeners if they were set
+      if (this.unmuteHandler) {
+        document.documentElement.removeEventListener('mousedown', this.unmuteHandler)
+        document.documentElement.removeEventListener('keydown', this.unmuteHandler)
+      }
+    }
+
     mounted() {
       this._container.addEventListener('resize', this.onResize)
       this.onVolumeChanged(this.volume)
@@ -533,12 +572,23 @@
         this.$client.sendData('keyup', { key: this.keyMap(key) })
       }
       this.keyboard.listenTo(this._overlay)
+
+      /* KERNEL MODIFICATION: Set up listeners for the first interaction. */
+      this.unmuteHandler = this._unmuteOnFirstInteraction.bind(this)
+      document.documentElement.addEventListener('mousedown', this.unmuteHandler, { once: true })
+      document.documentElement.addEventListener('keydown', this.unmuteHandler, { once: true })
     }
 
     beforeDestroy() {
       this.observer.disconnect()
       this.$accessor.video.setPlayable(false)
       /* Guacamole Keyboard does not provide destroy functions */
+
+      /* KERNEL MODIFICATION: Clean up listeners on component destruction. */
+      if (this.unmuteHandler) {
+        document.documentElement.removeEventListener('mousedown', this.unmuteHandler)
+        document.documentElement.removeEventListener('keydown', this.unmuteHandler)
+      }
     }
 
     get hasMacOSKbd() {
@@ -761,6 +811,9 @@
     }
 
     onMouseDown(e: MouseEvent) {
+      /* KERNEL MODIFICATION: Trigger unmute on first video click. */
+      this._unmuteOnFirstInteraction()
+
       if (!this.hosting) {
         this.$emit('control-attempt', e)
       }
@@ -846,4 +899,4 @@
       this._overlay.focus()
     }
   }
-</script>
+</script>
\ No newline at end of file
diff --git a/images/chromium-headful/daemon.conf b/images/chromium-headful/daemon.conf
new file mode 100644
index 00000000..efccf92f
--- /dev/null
+++ b/images/chromium-headful/daemon.conf
@@ -0,0 +1,43 @@
+# /etc/pulse/daemon.conf
+# OPTIMIZED FOR LOW-LATENCY WEBRTC
+
+# General settings
+daemonize = no
+fail = yes
+allow-module-loading = yes
+high-priority = no
+realtime-scheduling = no
+exit-idle-time = -1
+
+# Disable SHM which triggered errors in container
+enable-shm = no
+; enable-memfd = yes
+
+# Resource limits
+rlimit-fsize = -1
+rlimit-data = -1
+rlimit-stack = -1
+rlimit-core = -1
+rlimit-as = -1
+rlimit-rss = -1
+rlimit-nproc = -1
+rlimit-nofile = 256
+rlimit-memlock = -1
+rlimit-locks = -1
+rlimit-sigpending = -1
+rlimit-msgqueue = -1
+rlimit-nice = 31
+rlimit-rtprio = 9
+rlimit-rttime = 200000
+
+# Low-latency audio settings
+default-sample-format = s16le
+default-sample-rate = 48000
+alternate-sample-rate = 44100
+default-sample-channels = 2
+default-channel-map = front-left,front-right
+resample-method = speex-float-1
+
+# Critical changes for low-latency
+default-fragments = 5
+default-fragment-size-msec = 5
\ No newline at end of file
diff --git a/images/chromium-headful/dbus-mpris.conf b/images/chromium-headful/dbus-mpris.conf
new file mode 100644
index 00000000..2ed00b6d
--- /dev/null
+++ b/images/chromium-headful/dbus-mpris.conf
@@ -0,0 +1,27 @@
+<!DOCTYPE busconfig PUBLIC "-//freedesktop//DTD D-BUS Bus Configuration 1.0//EN"
+ "http://www.freedesktop.org/standards/dbus/1.0/busconfig.dtd">
+<busconfig>
+  <!-- Allow any user to own the MPRIS service for Chromium and all its media player variants -->
+  <policy context="default">
+    <!-- Standard Chromium MPRIS service -->
+    <allow own_prefix="org.mpris.MediaPlayer2.chromium"/>
+    <!-- Chromium Snap package variant -->
+    <allow own_prefix="org.mpris.MediaPlayer2.chromium_chromium"/>
+    <!-- Chromium Flatpak variant -->
+    <allow own_prefix="org.mpris.MediaPlayer2.org.chromium.Chromium"/>
+    <!-- Chromium-browser (Debian/Ubuntu) -->
+    <allow own_prefix="org.mpris.MediaPlayer2.chromium-browser"/>
+    <!-- Chromium (generic, fallback) -->
+    <allow own_prefix="org.mpris.MediaPlayer2.Chromium"/>
+    <!-- Chrome (in case of Chrome being used) -->
+    <allow own_prefix="org.mpris.MediaPlayer2.google-chrome"/>
+    <allow own_prefix="org.mpris.MediaPlayer2.Google-chrome"/>
+    <allow own_prefix="org.mpris.MediaPlayer2.chrome"/>
+    <!-- Chromium-based Edge (for completeness) -->
+    <allow own_prefix="org.mpris.MediaPlayer2.microsoft-edge"/>
+    <!-- Brave (another Chromium-based browser) -->
+    <allow own_prefix="org.mpris.MediaPlayer2.brave"/>
+    <!-- Vivaldi (another Chromium-based browser) -->
+    <allow own_prefix="org.mpris.MediaPlayer2.vivaldi"/>
+  </policy>
+</busconfig>
\ No newline at end of file
diff --git a/images/chromium-headful/dbus-pulseaudio.conf b/images/chromium-headful/dbus-pulseaudio.conf
new file mode 100644
index 00000000..ae378b25
--- /dev/null
+++ b/images/chromium-headful/dbus-pulseaudio.conf
@@ -0,0 +1,27 @@
+<!DOCTYPE busconfig PUBLIC "-//freedesktop//DTD D-BUS Bus Configuration 1.0//EN"
+ "http://www.freedesktop.org/standards/dbus/1.0/busconfig.dtd">
+<busconfig>
+  <!--
+    This file allows the user in the 'pulse', 'pulse-access', or 'audio'
+    groups to own the PulseAudio D-Bus services.
+  -->
+
+  <!-- Policy for 'pulse' group -->
+  <policy group="pulse">
+    <allow own="org.PulseAudio1"/>
+    <allow own="org.pulseaudio.Server"/>
+  </policy>
+
+  <!-- Policy for 'pulse-access' group -->
+  <policy group="pulse-access">
+    <allow own="org.PulseAudio1"/>
+    <allow own="org.pulseaudio.Server"/>
+  </policy>
+
+  <!-- Policy for 'audio' group -->
+  <policy group="audio">
+    <allow own="org.PulseAudio1"/>
+    <allow own="org.pulseaudio.Server"/>
+  </policy>
+
+</busconfig>
\ No newline at end of file
diff --git a/images/chromium-headful/default.pa b/images/chromium-headful/default.pa
new file mode 100644
index 00000000..518545d1
--- /dev/null
+++ b/images/chromium-headful/default.pa
@@ -0,0 +1,17 @@
+#!/usr/bin/pulseaudio -nF
+
+### Create virtual output device sink
+load-module module-null-sink sink_name=audio_output sink_properties=device.description="Virtual_Audio_Output"
+
+### Create virtual input device sink
+load-module module-null-sink sink_name=audio_input sink_properties=device.description="Virtual_Audio_Input"
+
+### Create a virtual audio source linked up to the virtual input device
+load-module module-virtual-source source_name=microphone master=audio_input.monitor source_properties=device.description="Virtual_Microphone"
+
+### Allow pulse audio to be accessed via a unix socket
+### Important to _not_ specify socket (socket=/tmp/runtime-kernel/pulse/native)
+load-module module-native-protocol-unix auth-anonymous=1
+
+### Make sure we always have a sink around, even if it is a null sink.
+load-module module-always-sink
\ No newline at end of file
diff --git a/images/chromium-headful/run-docker.sh b/images/chromium-headful/run-docker.sh
index 5adbd8a8..91401016 100755
--- a/images/chromium-headful/run-docker.sh
+++ b/images/chromium-headful/run-docker.sh
@@ -41,10 +41,12 @@ RUN_ARGS=(
   -e RUN_AS_ROOT="$RUN_AS_ROOT" \
   --mount type=bind,src="$FLAGS_FILE",dst=/chromium/flags,ro
 )
-
 if [[ "${WITH_KERNEL_IMAGES_API:-}" == "true" ]]; then
   RUN_ARGS+=( -p 444:10001 )
   RUN_ARGS+=( -e WITH_KERNEL_IMAGES_API=true )
+elif [[ "${WITH_KERNEL_OPERATOR_API:-}" == "true" ]]; then
+  RUN_ARGS+=( -p 444:10001 )
+  RUN_ARGS+=( -e WITH_KERNEL_OPERATOR_API=true )
 fi
 
 # noVNC vs WebRTC port mapping
@@ -64,5 +66,17 @@ else
   RUN_ARGS+=( -p 8080:6080 )
 fi
 
-docker rm -f "$NAME" 2>/dev/null || true
-docker run -it "${RUN_ARGS[@]}" "$IMAGE"
+if [[ "${DEBUG_BASH:-false}" == "true" ]]; then
+  # if DEBUG_BASH set to true, enters container bash
+  docker run -dit --name "$NAME" "${RUN_ARGS[@]}" "$IMAGE"
+  docker logs -f "$NAME" &
+  docker exec -it "$NAME" /bin/bash
+elif [[ "${DEBUG_OPERATOR_TEST:-false}" == "true" ]]; then
+  # if DEBUG_OPERATOR_TEST set to true, start in detached mode
+  docker rm -f "$NAME" 2>/dev/null || true
+  docker run -d "${RUN_ARGS[@]}" -e DEBUG_OPERATOR_TEST=true "$IMAGE"
+  echo "Container '$NAME' started in detached mode"
+else
+  docker rm -f "$NAME" 2>/dev/null || true
+  docker run -it "${RUN_ARGS[@]}" "$IMAGE"
+fi
diff --git a/images/chromium-headful/run-unikernel.sh b/images/chromium-headful/run-unikernel.sh
index 5911d653..16f7c6ac 100755
--- a/images/chromium-headful/run-unikernel.sh
+++ b/images/chromium-headful/run-unikernel.sh
@@ -34,12 +34,12 @@ echo "$CHROMIUM_FLAGS" > "$FLAGS_DIR/flags"
 kraft cloud volume rm "$volume_name" || true
 kraft cloud volume create -n "$volume_name" -s 16M
 # Import the flags directory into the freshly created volume
-kraft cloud volume import --image onkernel/utils/volimport:1.0 -s "$FLAGS_DIR" -v "$volume_name"
+# kraft cloud volume import --image onkernel/utils/volimport:1.0 -s "$FLAGS_DIR" -v "$volume_name"
+kraft cloud volume import -s "$FLAGS_DIR" -v "$volume_name"
 
 # Ensure the temp directory is cleaned up on exit
 trap 'rm -rf "$FLAGS_DIR"' EXIT
 
-
 deploy_args=(
   -M 8192
   -p 9222:9222/tls
@@ -55,6 +55,9 @@ deploy_args=(
 if [[ "${WITH_KERNEL_IMAGES_API:-}" == "true" ]]; then
   deploy_args+=( -p 444:10001/tls )
   deploy_args+=( -e WITH_KERNEL_IMAGES_API=true )
+elif [[ "${WITH_KERNEL_OPERATOR_API:-}" == "true" ]]; then
+  deploy_args+=( -p 444:10001/tls )
+  deploy_args+=( -e WITH_KERNEL_OPERATOR_API=true )
 fi
 
 if [[ "${ENABLE_WEBRTC:-}" == "true" ]]; then
@@ -70,4 +73,4 @@ else
     "${deploy_args[@]}" \
     -p 443:6080/http+tls \
     "$IMAGE"
-fi
+fi
\ No newline at end of file
diff --git a/images/chromium-headful/wrapper.sh b/images/chromium-headful/wrapper.sh
index 7da22c79..bd52458b 100755
--- a/images/chromium-headful/wrapper.sh
+++ b/images/chromium-headful/wrapper.sh
@@ -1,57 +1,144 @@
-#!/bin/bash
+#!/usr/bin/env bash
+# ------------------------------------------------------------------------------
+# wrapper.sh – container entrypoint
+# ------------------------------------------------------------------------------
 
-set -o pipefail -o errexit -o nounset
+set -o errexit -o nounset -o pipefail
 
+# ------------------------------------------------------------------------------
+# Environment ──────────────────────────────────────────────────────────────────
+# ------------------------------------------------------------------------------
+export PULSE_SERVER="/tmp/runtime-kernel/pulse/native"
+export XDG_CONFIG_HOME="/tmp/.chromium"
+export XDG_CACHE_HOME="/tmp/.chromium"
+export XDG_RUNTIME_DIR="/tmp/runtime-kernel"
+export DISPLAY=":1"
+
+# ------------------------------------------------------------------------------
+# /dev/shm (only outside Docker) ───────────────────────────────────────────────
 # If the WITHDOCKER environment variable is not set, it means we are not running inside a Docker container.
 # Docker manages /dev/shm itself, and attempting to mount or modify it can cause permission or device errors.
 # However, in a unikernel container environment (non-Docker), we need to manually create and mount /dev/shm as a tmpfs
 # to support shared memory operations.
-if [ -z "${WITHDOCKER:-}" ]; then
+# ------------------------------------------------------------------------------
+if [[ -z "${WITHDOCKER:-}" ]]; then
   mkdir -p /dev/shm
   chmod 777 /dev/shm
   mount -t tmpfs tmpfs /dev/shm
 fi
 
+# ------------------------------------------------------------------------------
+# Scale-to-zero control ────────────────────────────────────────────────────────
 # We disable scale-to-zero for the lifetime of this script and restore
 # the original setting on exit.
+# ------------------------------------------------------------------------------
 SCALE_TO_ZERO_FILE="/uk/libukp/scale_to_zero_disable"
+
 scale_to_zero_write() {
-  local char="$1"
   # Skip when not running inside Unikraft Cloud (control file absent)
-  if [[ -e "$SCALE_TO_ZERO_FILE" ]]; then
-    # Write the character, but do not fail the whole script if this errors out
-    echo -n "$char" > "$SCALE_TO_ZERO_FILE" 2>/dev/null || \
-      echo "Failed to write to scale-to-zero control file" >&2
-  fi
+  [[ -e "$SCALE_TO_ZERO_FILE" ]] || return 0
+  # Write the character, but do not fail the whole script if this errors out
+  echo -n "$1" >"$SCALE_TO_ZERO_FILE" 2>/dev/null || \
+    echo "[wrapper] WARN: cannot write scale-to-zero flag" >&2
 }
+
 disable_scale_to_zero() { scale_to_zero_write "+"; }
 enable_scale_to_zero()  { scale_to_zero_write "-"; }
 
 # Disable scale-to-zero for the duration of the script when not running under Docker
 if [[ -z "${WITHDOCKER:-}" ]]; then
-  echo "Disabling scale-to-zero"
+  echo "[wrapper] Disabling scale-to-zero"
   disable_scale_to_zero
 fi
 
-export DISPLAY=:1
-
+# ------------------------------------------------------------------------------
+# Xorg ─────────────────────────────────────────────────────────────────────────
+# ------------------------------------------------------------------------------
 /usr/bin/Xorg :1 -config /etc/neko/xorg.conf -noreset -nolisten tcp &
 
+# ------------------------------------------------------------------------------
+# Input-socket permission fix : Force-change after creation ────────────────────
+# ------------------------------------------------------------------------------
+echo "[wrapper] Waiting for xf86-input socket"
+for i in $(seq 1 10); do
+  if [[ -S /tmp/xf86-input-neko.sock ]]; then
+    chmod 666 /tmp/xf86-input-neko.sock
+    echo "[wrapper] Socket chmod 666 applied"
+    break
+  fi
+  sleep 0.5
+done
+[[ -S /tmp/xf86-input-neko.sock ]] || echo "[wrapper] WARN: socket not found" >&2
+
+# ------------------------------------------------------------------------------
+# Mutter ───────────────────────────────────────────────────────────────────────
+# ------------------------------------------------------------------------------
 ./mutter_startup.sh
 
+# ------------------------------------------------------------------------------
+# system D-Bus Setup ───────────────────────────────────────────────────────────
+# ------------------------------------------------------------------------------
+echo "[wrapper] Starting system D-Bus"
+mkdir -p /run/dbus
+dbus-uuidgen --ensure
+dbus-daemon --system \
+  --address="unix:path=/run/dbus/system_bus_socket" \
+  --nopidfile --nosyslog --nofork &
+dbus_pid=$!
+
+echo "[wrapper] Waiting for D-Bus socket"
+for i in $(seq 1 20); do
+  [[ -S /run/dbus/system_bus_socket ]] && break
+  sleep 0.5
+done
+export DBUS_SESSION_BUS_ADDRESS="unix:path=/run/dbus/system_bus_socket"
+
+# ------------------------------------------------------------------------------
+# PulseAudio Setup ─────────────────────────────────────────────────────────────
+# ------------------------------------------------------------------------------
+echo "[pulse] Setting up permissions"
+chown -R kernel:kernel /home/kernel/ /home/kernel/.config /etc/pulse
+chmod 777 /home/kernel/.config /etc/pulse
+chown -R kernel:kernel /tmp/runtime-kernel
+
+echo "[pulse] Starting daemon"
+runuser -u kernel -- env \
+  XDG_RUNTIME_DIR=/tmp/runtime-kernel \
+  XDG_CONFIG_HOME=/home/kernel/.config \
+  XDG_CACHE_HOME=/home/kernel/.cache \
+  pulseaudio --log-level=error \
+             --disallow-module-loading \
+             --disallow-exit \
+             --exit-idle-time=-1 &
+pulse_pid=$!
+
+echo "[pulse] Waiting for server"
+for i in $(seq 1 20); do
+  runuser -u kernel -- pactl info >/dev/null 2>&1 && break
+  if [ "$i" -eq 20 ]; then
+    echo "[pulse] ERROR: failed to start"
+    exit 1
+  fi
+  sleep 0.5
+done
+
+# ------------------------------------------------------------------------------
+# VNC / WebRTC ─────────────────────────────────────────────────────────────────
+# ------------------------------------------------------------------------------
 if [[ "${ENABLE_WEBRTC:-}" != "true" ]]; then
   ./x11vnc_startup.sh
 fi
 
-# -----------------------------------------------------------------------------
-# House-keeping for the unprivileged "kernel" user --------------------------------
+# ------------------------------------------------------------------------------
+# Filesystem housekeeping for kernel user ──────────────────────────────────────
 # Some Chromium subsystems want to create files under $HOME (NSS cert DB, dconf
 # cache).  If those directories are missing or owned by root Chromium emits
 # noisy error messages such as:
 #   [ERROR:crypto/nss_util.cc:48] Failed to create /home/kernel/.pki/nssdb ...
 #   dconf-CRITICAL **: unable to create directory '/home/kernel/.cache/dconf'
 # Pre-create them and hand ownership to the user so the messages disappear.
-
+# Also critical to avoid Permission Denied when running as kernel user
+# ------------------------------------------------------------------------------
 dirs=(
   /home/kernel/user-data
   /home/kernel/.config/chromium
@@ -59,113 +146,93 @@ dirs=(
   /home/kernel/.cache/dconf
   /tmp
   /var/log
+  /tmp/runtime-kernel/dconf
+  /tmp/.chromium
 )
-
-for dir in "${dirs[@]}"; do
-  if [ ! -d "$dir" ]; then
-    mkdir -p "$dir"
-  fi
+for d in "${dirs[@]}"; do
+  [[ -d "$d" ]] || mkdir -p "$d"
 done
+chown -R kernel:kernel /home/kernel/user-data /home/kernel/.config \
+  /home/kernel/.pki /home/kernel/.cache /tmp/runtime-kernel /tmp/.chromium 2>/dev/null || true
 
-# Ensure correct ownership (ignore errors if already correct)
-chown -R kernel:kernel /home/kernel/user-data /home/kernel/.config /home/kernel/.pki /home/kernel/.cache 2>/dev/null || true
-
-# -----------------------------------------------------------------------------
-# System-bus setup --------------------------------------------------------------
-# -----------------------------------------------------------------------------
-# Start a lightweight system D-Bus daemon if one is not already running.  We
-# will later use this very same bus as the *session* bus as well, avoiding the
-# autolaunch fallback that produced many "Connection refused" errors.
-# Start a lightweight system D-Bus daemon if one is not already running (Chromium complains otherwise)
-if [ ! -S /run/dbus/system_bus_socket ]; then
-  echo "Starting system D-Bus daemon"
-  mkdir -p /run/dbus
-  # Ensure a machine-id exists (required by dbus-daemon)
-  dbus-uuidgen --ensure
-  # Launch dbus-daemon in the background and remember its PID for cleanup
-  dbus-daemon --system \
-    --address=unix:path=/run/dbus/system_bus_socket \
-    --nopidfile --nosyslog --nofork >/dev/null 2>&1 &
-  dbus_pid=$!
-fi
-
-# We will point DBUS_SESSION_BUS_ADDRESS at the system bus socket to suppress
-# autolaunch attempts that failed and spammed logs.
-export DBUS_SESSION_BUS_ADDRESS="unix:path=/run/dbus/system_bus_socket"
-
-# Start Chromium with display :1 and remote debugging, loading our recorder extension.
-# Use ncat to listen on 0.0.0.0:9222 since chromium does not let you listen on 0.0.0.0 anymore: https://github.com/pyppeteer/pyppeteer/pull/379#issuecomment-217029626
-cleanup () {
-  echo "Cleaning up..."
-  # Re-enable scale-to-zero if the script terminates early
+# ------------------------------------------------------------------------------
+# Cleanup handler ──────────────────────────────────────────────────────────────
+# ------------------------------------------------------------------------------
+cleanup() {
+  echo "[wrapper] Cleaning up"
   enable_scale_to_zero
-  kill -TERM $pid
-  kill -TERM $pid2
-  # Kill the API server if it was started
-  if [[ -n "${pid3:-}" ]]; then
-    kill -TERM $pid3 || true
-  fi
-  if [ -n "${dbus_pid:-}" ]; then
-    kill -TERM $dbus_pid 2>/dev/null || true
-  fi
+  kill -TERM "$pid" "$pid2"
+  [[ -n "${pid3:-}" ]] && kill -TERM "$pid3" || true
+  [[ -n "${dbus_pid:-}" ]] && kill -TERM "$dbus_pid" || true
 }
 trap cleanup TERM INT
 pid=
 pid2=
 pid3=
-INTERNAL_PORT=9223
-CHROME_PORT=9222  # External port mapped to host
-echo "Starting Chromium on internal port $INTERNAL_PORT"
+export INTERNAL_PORT=9223
+export CHROME_PORT=9222  
+
+# ------------------------------------------------------------------------------
+# Chromium ─────────────────────────────────────────────────────────────────────
+# Start Chromium with display :1 and remote debugging, loading our recorder extension.
+# Use ncat to listen on 0.0.0.0:9222
+# since chromium does not let you listen on 0.0.0.0 anymore :
+# https://github.com/pyppeteer/pyppeteer/pull/379#issuecomment-217029626
+# ------------------------------------------------------------------------------
 
 # Load additional Chromium flags from /chromium/flags if present
+echo "[chromium] Preparing flags"
 CHROMIUM_FLAGS="${CHROMIUM_FLAGS:-}"
-if [[ -f /chromium/flags ]]; then
-  CHROMIUM_FLAGS="$CHROMIUM_FLAGS $(cat /chromium/flags)"
-fi
-echo "CHROMIUM_FLAGS: $CHROMIUM_FLAGS"
+[[ -f /chromium/flags ]] && CHROMIUM_FLAGS+=" $(< /chromium/flags)"
+echo "[chromium] Flags: $CHROMIUM_FLAGS"
+
+INTERNAL_PORT="${INTERNAL_PORT:-9223}"
+CHROME_PORT="${CHROME_PORT:-9222}" # External port mapped to host
+RUN_AS_ROOT="${RUN_AS_ROOT:-false}"
 
-RUN_AS_ROOT=${RUN_AS_ROOT:-false}
+echo "[chromium] Launching on display ${DISPLAY}"
 if [[ "$RUN_AS_ROOT" == "true" ]]; then
-  DISPLAY=:1 DBUS_SESSION_BUS_ADDRESS="$DBUS_SESSION_BUS_ADDRESS" chromium \
-    --remote-debugging-port=$INTERNAL_PORT \
-    ${CHROMIUM_FLAGS:-} >&2 & pid=$!
+  DISPLAY="$DISPLAY" DBUS_SESSION_BUS_ADDRESS="$DBUS_SESSION_BUS_ADDRESS" chromium \
+    --remote-debugging-port="$INTERNAL_PORT" \
+    $CHROMIUM_FLAGS >&2 & pid=$!
 else
+  # required environment variables (DISPLAY, DBUS_SESSION_BUS_ADDRESS) are already exported
+  # in this script's environment, so runuser will pass them to the child process.
   runuser -u kernel -- env \
-    DISPLAY=:1 \
-    DBUS_SESSION_BUS_ADDRESS="$DBUS_SESSION_BUS_ADDRESS" \
-    XDG_CONFIG_HOME=/home/kernel/.config \
-    XDG_CACHE_HOME=/home/kernel/.cache \
+    XDG_CONFIG_HOME=/tmp/.chromium \
+    XDG_CACHE_HOME=/tmp/.chromium \
     HOME=/home/kernel \
-    chromium \
-    --remote-debugging-port=$INTERNAL_PORT \
-    ${CHROMIUM_FLAGS:-} >&2 & pid=$!
+    chromium --remote-debugging-port="$INTERNAL_PORT" $CHROMIUM_FLAGS \
+    > /tmp/chromium.log 2>&1 & pid=$!
 fi
 
-echo "Setting up ncat proxy on port $CHROME_PORT"
-ncat \
-  --sh-exec "ncat 0.0.0.0 $INTERNAL_PORT" \
-  -l "$CHROME_PORT" \
-  --keep-open & pid2=$!
+# ncat proxy → expose INTERNAL_PORT as CHROME_PORT
+echo "[chromium] Starting ncat proxy :$CHROME_PORT → :$INTERNAL_PORT"
+ncat --sh-exec "ncat 0.0.0.0 $INTERNAL_PORT" \
+     -l "$CHROME_PORT" --keep-open & pid2=$!
 
+# ------------------------------------------------------------------------------
+# Start Neko WebRTC / noVNC ────────────────────────────────────────────────────
+# ------------------------------------------------------------------------------
 if [[ "${ENABLE_WEBRTC:-}" == "true" ]]; then
-  # use webrtc
-  echo "✨ Starting neko (webrtc server)."
-  /usr/bin/neko serve --server.static /var/www --server.bind 0.0.0.0:8080 >&2 &
-
-  # Wait for neko to be ready.
-  echo "Waiting for neko port 0.0.0.0:8080..."
-  while ! nc -z 127.0.0.1 8080 2>/dev/null; do
-    sleep 0.5
-  done
-  echo "Port 8080 is open"
+  echo "[neko] Starting WebRTC server"
+  runuser -u kernel -- /usr/bin/neko serve \
+    --server.static /var/www \
+    --server.bind 0.0.0.0:8080 >/dev/null 2>&1 &
+  neko_pid=$!
+
+  echo "[neko] Waiting on port 8080"
+  until nc -z 127.0.0.1 8080; do sleep 0.5; done
 else
-  # use novnc
   ./novnc_startup.sh
-  echo "✨ noVNC demo is ready to use!"
+  echo "[novnc] Ready"
 fi
 
+# ------------------------------------------------------------------------------
+# Start kernel-images API ──────────────────────────────────────────────────────
+# ------------------------------------------------------------------------------
 if [[ "${WITH_KERNEL_IMAGES_API:-}" == "true" ]]; then
-  echo "✨ Starting kernel-images API."
+  echo "[kernel-images:api] Starting service"
 
   API_PORT="${KERNEL_IMAGES_API_PORT:-10001}"
   API_FRAME_RATE="${KERNEL_IMAGES_API_FRAME_RATE:-10}"
@@ -181,9 +248,12 @@ if [[ "${WITH_KERNEL_IMAGES_API:-}" == "true" ]]; then
   MAX_SIZE_MB="$API_MAX_SIZE_MB" \
   OUTPUT_DIR="$API_OUTPUT_DIR" \
   /usr/local/bin/kernel-images-api & pid3=$!
+
   # close the "--no-sandbox unsupported flag" warning when running as root
-  # in the unikernel runtime we haven't been able to get chromium to launch as non-root without cryptic crashpad errors
-  # and when running as root you must use the --no-sandbox flag, which generates a warning
+  # in the unikernel runtime we haven't been able to get chromium to launch as non-root
+  # without cryptic crashpad errors
+  # and when running as root you must use the --no-sandbox flag,
+  # which generates a warning
   if [[ "${RUN_AS_ROOT:-}" == "true" ]]; then
     echo "Running as root, attempting to dismiss the --no-sandbox unsupported flag warning"
     if read -r WIDTH HEIGHT <<< "$(xdotool getdisplaygeometry 2>/dev/null)"; then
@@ -233,11 +303,109 @@ if [[ "${WITH_KERNEL_IMAGES_API:-}" == "true" ]]; then
       echo "xdotool failed to obtain display geometry; skipping sandbox warning dismissal." >&2
     fi
   fi
+elif [[ "${WITH_KERNEL_OPERATOR_API:-}" == "true" ]]; then
+# ------------------------------------------------------------------------------
+# Start kernel-operator API (runs as user: kernel, with elevated caps; sudo available)
+# ------------------------------------------------------------------------------
+  echo "[kernel-operator:api] Starting service"
+
+  # Start the kernel-operator API in the background
+  (
+    OP_ENV_FILE="/tmp/kernel-operator/.kernel-operator.env"
+    [[ -f "$OP_ENV_FILE" ]] && { set -a; source "$OP_ENV_FILE"; set +a; }
+
+    # Maximize file descriptor and process limits for heavy FS/exec workloads
+    ulimit -n "${KERNEL_OPERATOR_ULIMIT_NOFILE:-1048576}" || true
+    ulimit -u "${KERNEL_OPERATOR_ULIMIT_NPROC:-65535}"   || true
+    umask "${KERNEL_OPERATOR_UMASK:-0002}"
+    # When the binary shells out to privileged commands, it can use:
+    #   sudo -n <cmd>        (passwordless per Dockerfile sudoers)
+    # Capabilities on the binary already cover many privileged syscalls.
+    
+    # Debug log to print parsed .env content
+    echo "[wrapper:kernel-operator:api] parsed operator .env content:"
+    grep -v "^#" /tmp/kernel-operator/.kernel-operator.env | while read -r line; do
+      echo "  $line"
+    done
+    
+    # Run the operator API with the parsed environment variables
+    grep -v "^#" /tmp/kernel-operator/.kernel-operator.env | xargs -I{} /usr/local/bin/kernel-operator-api {} & pid4=$!
+
+    # close the "--no-sandbox unsupported flag" warning when running as root
+    # in the unikernel runtime we haven't been able to get chromium to launch as non-root
+    # without cryptic crashpad errors
+    # and when running as root you must use the --no-sandbox flag,
+    # which generates a warning
+    if [[ "${RUN_AS_ROOT:-}" == "true" ]]; then
+      echo "Running as root, attempting to dismiss the --no-sandbox unsupported flag warning"
+      if read -r WIDTH HEIGHT <<< "$(xdotool getdisplaygeometry 2>/dev/null)"; then
+        # Work out an x-coordinate slightly inside the right-hand edge of the
+        OFFSET_X=$(( WIDTH - 30 ))
+        if (( OFFSET_X < 0 )); then
+          OFFSET_X=0
+        fi
+
+        # Wait for kernel-images API port 10001 to be ready.
+        echo "Waiting for kernel-images API port 127.0.0.1:10001..."
+        while ! nc -z 127.0.0.1 10001 2>/dev/null; do
+          sleep 0.5
+        done
+        echo "Port 10001 is open"
+
+        # Wait for Chromium window to open before dismissing the --no-sandbox warning.
+        target='New Tab - Chromium'
+        echo "Waiting for Chromium window \"${target}\" to appear and become active..."
+        while :; do
+          win_id=$(xwininfo -root -tree 2>/dev/null | awk -v t="$target" '$0 ~ t {print $1; exit}')
+          if [[ -n $win_id ]]; then
+            win_id=${win_id%:}
+            if xdotool windowactivate --sync "$win_id"; then
+              echo "Focused window $win_id ($target) on $DISPLAY"
+              break
+            fi
+          fi
+          sleep 0.5
+        done
+
+        # wait... not sure but this just increases the likelihood of success
+        # without the sleep you often open the live view and see the mouse hovering over the "X" to dismiss the warning, suggesting that it clicked before the warning or chromium appeared
+        sleep 5
+
+        # Attempt to click the warning's close button
+        echo "Clicking the warning's close button at x=$OFFSET_X y=115"
+        if curl -s -o /dev/null -X POST \
+          http://localhost:10001/computer/click_mouse \
+          -H "Content-Type: application/json" \
+          -d "{\"x\":${OFFSET_X},\"y\":115}"; then
+            echo "Successfully clicked the warning's close button"
+        else
+          echo "Failed to click the warning's close button" >&2
+        fi
+      else
+        echo "xdotool failed to obtain display geometry; skipping sandbox warning dismissal." >&2
+      fi
+    fi
+
+
+    if [[ "${DEBUG_OPERATOR_TEST:-}" == "true" ]]; then
+      echo "[kernel-operator:test] sleep 10 then Running tests once"
+      sleep 10
+      /usr/local/bin/kernel-operator-test --all > /tmp/kernel-operator/tests.log 2>&1 || echo "[kernel-operator:tests] Non-zero exit code"
+    fi
+    
+    wait $pid4
+  ) &
 fi
 
+
+# ------------------------------------------------------------------------------
+# Scale-to-zero flag ───────────────────────────────────────────────────────────
+# ------------------------------------------------------------------------------
 if [[ -z "${WITHDOCKER:-}" ]]; then
   enable_scale_to_zero
 fi
 
-# Keep the container running
+# ------------------------------------------------------------------------------
+# Keep the container running ───────────────────────────────────────────────────
+# ------------------------------------------------------------------------------
 tail -f /dev/null
diff --git a/images/chromium-headful/xorg.conf b/images/chromium-headful/xorg.conf
index ed0e8488..05744578 100644
--- a/images/chromium-headful/xorg.conf
+++ b/images/chromium-headful/xorg.conf
@@ -27,6 +27,8 @@ Section "InputDevice"
   Identifier "dummy_touchscreen"
   Option "SendCoreEvents" "On"
   Option "SocketName" "/tmp/xf86-input-neko.sock"
+  # allow user kernel to connect to root-owned socket
+  Option "SocketMode" "0666"
   Driver "neko"
 EndSection
 
@@ -115,4 +117,4 @@ Section "ServerLayout"
   InputDevice  "dummy_mouse"
   InputDevice  "dummy_keyboard"
   InputDevice  "dummy_touchscreen" "CorePointer"
-EndSection
+EndSection
\ No newline at end of file
diff --git a/operator-api/.gitignore b/operator-api/.gitignore
new file mode 100644
index 00000000..8abb0dec
--- /dev/null
+++ b/operator-api/.gitignore
@@ -0,0 +1,6 @@
+dist/
+node_modules/
+_bak/
+_wip/
+_dev/
+bun.lock
\ No newline at end of file
diff --git a/operator-api/.kernel-operator.env b/operator-api/.kernel-operator.env
new file mode 100644
index 00000000..1364e37d
--- /dev/null
+++ b/operator-api/.kernel-operator.env
@@ -0,0 +1,20 @@
+# This is the env configuration used by the build in the kernel container for operator api
+# If to replace the Go server, adjust the PORT
+
+PORT=10001
+DATA_DIR=/tmp/kernel-operator/data
+DISPLAY=:1
+PULSE_SOURCE=default
+XDG_RUNTIME_DIR=/tmp
+
+FFMPEG_BIN=/usr/local/bin/ffmpeg
+XDOTOOL_BIN=xdotool
+
+WIDTH=1024
+HEIGHT=768
+
+HTTP_PROXY_PORT=8082
+SOCKS5_BIND_HOST=127.0.0.1
+SOCKS5_BIND_PORT=1080
+
+DEBUG_LOGS=true
\ No newline at end of file
diff --git a/operator-api/.wipdev.example.env b/operator-api/.wipdev.example.env
new file mode 100644
index 00000000..11eff6eb
--- /dev/null
+++ b/operator-api/.wipdev.example.env
@@ -0,0 +1,15 @@
+PORT=9999
+DATA_DIR=/tmp/kernel-operator/data
+DISPLAY=:20
+PULSE_SOURCE=default
+XDG_RUNTIME_DIR=/tmp
+
+FFMPEG_BIN=/usr/bin/ffmpeg
+XDOTOOL_BIN=/usr/bin/xdotool
+WIDTH=1280
+HEIGHT=720
+HTTP_PROXY_PORT=8082
+SOCKS5_BIND_HOST=127.0.0.1
+SOCKS5_BIND_PORT=1080
+
+DEBUG_LOGS=true
\ No newline at end of file
diff --git a/operator-api/README.md b/operator-api/README.md
new file mode 100644
index 00000000..ab5e752f
--- /dev/null
+++ b/operator-api/README.md
@@ -0,0 +1,234 @@
+# Kernel Computer Operator API.
+
+- New operator API to replace current Go server API, with added functionalities (supports previous endpoints & schema)
+- To use on PORT=10001
+- Packed with + deployment-test with `kernel-images`, on Docker & Unikraft
+
+---
+
+# Todo
+
+```
+- test ffmpeg capture with audio (implemented, not tested)
+- screen display resolution <> ffmpeg in case of resize (double check)
+- add more tools that are useful for agents
+- document api
+```
+
+---
+
+# Build & Run
+
+
+- Using bun builder
+
+```bash
+bun build # binaries : dist/kernel-operator-api , dist/kernel-operator-test
+```
+
+- Run tests from inside the kernel-images container :
+  - Run tests manually
+
+  ```bash
+  # build the container ...
+  # start container with DEBUG_BASH=true for interactive mode (optional)
+
+  WITH_KERNEL_OPERATOR_API=true DEBUG_BASH=true IMAGE=kernel-docker ENABLE_WEBRTC=true  ./run-docker.sh
+
+  # when container launches, run tests from inside it
+
+  /usr/local/bin/kernel-operator-test # lists available tests
+  /usr/local/bin/kernel-operator-test --all # run all tests
+  /usr/local/bin/kernel-operator-test fs screenshot # specify test suites
+  ```
+
+  - Autorun tests
+
+  ```bash
+  # build the container ...
+  # you can set DEBUG_OPERATOR_TEST=true to auto run all tests
+
+  WITH_KERNEL_OPERATOR_API=true DEBUG_OPERATOR_TEST=true IMAGE=kernel-docker  ENABLE_WEBRTC=true  ./run-docker.sh
+
+  # after tests complete (some tests have ~30s timeout)
+  # you should be able to fetch the gradually generated tests logs file
+  # using the operator api itself, from outside the container (provided /fs/read_file works)
+  # (use `localhost:10001` if you want to try from inside the container's chromium)
+  curl "http://localhost:444/health" # health check
+  curl -o kernel_operator_tests.log "http://localhost:444/fs/read_file?path=%2Ftmp%2Fkernel-operator%2Ftests.log"
+  cat kernel_operator_tests.log
+  ```
+---
+
+# Checklist
+
+`[✅ : Works , 〰️ : Yet to be tested , ❌ : Doesn't work]`
+
+## /browser-ext
+Endpoint/service | API Build | Kernel:Docker | Kernel:Unikraft | Notes
+--- | --- | --- | --- | --- 
+/browser/extension/add/unpacked | ✅ | ✅ | ✅ | Supports GitHub URL or zip file upload
+
+## /bus
+Endpoint/service | API Build | Kernel:Docker | Kernel:Unikraft | Notes
+--- | --- | --- | --- | --- 
+/bus/publish | ✅ | ✅ | ✅ | N/A
+/bus/subscribe | ✅ | ✅ | ✅ | N/A
+
+## /clipboard
+Endpoint/service | API Build | Kernel:Docker | Kernel:Unikraft | Notes
+--- | --- | --- | --- | --- 
+/clipboard | ✅ | ✅ | ✅ | N/A
+/clipboard/stream | 〰️ | ❌ | ❌ | timeout after 30000ms
+
+## /computer
+Endpoint/service | API Build | Kernel:Docker | Kernel:Unikraft | Notes
+--- | --- | --- | --- | --- 
+/computer/click_mouse | 〰️ | 〰️ | 〰️ | N/A
+/computer/move_mouse | 〰️ | 〰️ | 〰️ | N/A
+
+## /fs
+Endpoint/service | API Build | Kernel:Docker | Kernel:Unikraft | Notes
+--- | --- | --- | --- | --- 
+/fs/create_directory | ✅ | ✅ | ✅ | N/A
+/fs/delete_directory | ✅ | ✅ | ✅ | N/A
+/fs/delete_file | ✅ | ✅ | ✅ | N/A
+/fs/download | ✅ | ✅ | ✅ | N/A
+/fs/file_info | ✅ | ✅ | ✅ | N/A
+/fs/list_files | ✅ | ✅ | ✅ | N/A
+/fs/move | ✅ | ✅ | ✅ | N/A
+/fs/read_file | ✅ | ✅ | ✅ | N/A
+/fs/set_file_permissions | ✅ | ✅ | ✅ | N/A
+/fs/tail/stream | 〰️ | ✅ | ✅ | N/A
+/fs/upload | ✅ | ✅ | ✅ | N/A
+/fs/watch | 〰️ | ❌ | ❌ | watch start failed
+/fs/watch/{watch_id} | 〰️ | ❌ | ❌ | watch start failed
+/fs/watch/{watch_id}/events | 〰️ | ❌ | ❌ | watch start failed
+/fs/write_file | ✅ | ✅ | ✅ | N/A
+
+## /health
+Endpoint/service | API Build | Kernel:Docker | Kernel:Unikraft | Notes
+--- | --- | --- | --- | --- 
+/health | ✅ | ✅ | ✅ | N/A
+
+## /input/desktop
+Endpoint/service | API Build | Kernel:Docker | Kernel:Unikraft | Notes
+--- | --- | --- | --- | --- 
+/input/combo/activate_and_type | ✅ | ✅ | ✅ | N/A
+/input/combo/activate_and_keys | ✅ | ✅ | ✅ | N/A
+/input/combo/window/center | ✅ | ✅ | ✅ | N/A
+/input/combo/window/snap | ✅ | ✅ | ✅ | N/A
+/input/desktop/count | ✅ | ✅ | ✅ | N/A
+/input/desktop/current | ✅ | ✅ | ✅ | N/A
+/input/desktop/viewport | ✅ | ✅ | ✅ | N/A
+/input/desktop/window_desktop | ✅ | ✅ | ✅ | N/A
+/input/display/geometry | ✅ | ✅ | ✅ | N/A
+/input/keyboard/key | ✅ | ✅ | ✅ | N/A
+/input/keyboard/key_down | ✅ | ✅ | ✅ | N/A
+/input/keyboard/key_up | ✅ | ✅ | ✅ | N/A
+/input/keyboard/type | ✅ | ✅ | ✅ | N/A
+/input/mouse/click | ✅ | ✅ | ✅ | N/A
+/input/mouse/down | ✅ | ✅ | ✅ | N/A
+/input/mouse/location | ✅ | ✅ | ✅ | N/A
+/input/mouse/move | ✅ | ✅ | ✅ | N/A
+/input/mouse/move_relative | ✅ | ✅ | ✅ | N/A
+/input/mouse/scroll | ✅ | ✅ | ✅ | N/A
+/input/mouse/up | ✅ | ✅ | ✅ | N/A
+/input/system/exec | ✅ | ✅ | ✅ | N/A
+/input/system/sleep | ✅ | ✅ | ✅ | N/A
+/input/window/activate | ✅ | ✅ | ✅ | N/A
+/input/window/active | ✅ | ✅ | ✅ | N/A
+/input/window/close | ✅ | ✅ | ✅ | N/A
+/input/window/focus | ✅ | ✅ | ✅ | N/A
+/input/window/focused | ✅ | ✅ | ✅ | N/A
+/input/window/geometry | ✅ | ✅ | ✅ | N/A
+/input/window/kill | ✅ | ✅ | ✅ | N/A
+/input/window/map | ✅ | ✅ | ✅ | N/A
+/input/window/minimize | ✅ | ✅ | ✅ | N/A
+/input/window/move_resize | ✅ | ✅ | ✅ | N/A
+/input/window/name | ✅ | ✅ | ✅ | N/A
+/input/window/pid | ✅ | ✅ | ✅ | N/A
+/input/window/raise | ✅ | ✅ | ✅ | N/A
+/input/window/unmap | ✅ | ✅ | ✅ | N/A
+
+## /logs
+Endpoint/service | API Build | Kernel:Docker | Kernel:Unikraft | Notes
+--- | --- | --- | --- | --- 
+/logs/stream | ✅ | ✅ | ✅ | N/A
+
+## /macros
+Endpoint/service | API Build | Kernel:Docker | Kernel:Unikraft | Notes
+--- | --- | --- | --- | --- 
+/macros/create | ✅ | ✅ | ✅ | N/A
+/macros/list | ✅ | ✅ | ✅ | N/A
+/macros/run | ✅ | ✅ | ✅ | N/A
+/macros/{macro_id} | ✅ | ✅ | ✅ | N/A
+
+## /metrics
+Endpoint/service | API Build | Kernel:Docker | Kernel:Unikraft | Notes
+--- | --- | --- | --- | --- 
+/metrics/snapshot | ✅ | ✅ | ✅ | N/A
+/metrics/stream | ✅ | ✅ | ✅ | N/A
+
+## /network/forward
+Endpoint/service | API Build | Kernel:Docker | Kernel:Unikraft | Notes
+--- | --- | --- | --- | --- 
+/network/forward | 〰️ | 〰️ | 〰️ | N/A
+/network/forward/{forward_id} | 〰️ | 〰️ | 〰️ | N/A
+/network/har/stream | 〰️ | ✅ | ✅ | N/A
+/network/intercept/rules | 〰️ | ✅ | ✅ | N/A
+/network/intercept/rules/{rule_set_id} | 〰️ | ✅ | ✅ | N/A
+/network/proxy/socks5/start | 〰️ | 〰️ | 〰️ | N/A
+/network/proxy/socks5/stop | 〰️ | 〰️ | 〰️ | N/A
+
+## /os
+Endpoint/service | API Build | Kernel:Docker | Kernel:Unikraft | Notes
+--- | --- | --- | --- | --- 
+/os/locale | ✅ | ✅ | ✅ | N/A
+
+## /pipe
+Endpoint/service | API Build | Kernel:Docker | Kernel:Unikraft | Notes
+--- | --- | --- | --- | --- 
+/pipe/recv/stream | ✅ | ✅ | ✅ | N/A
+/pipe/send | ✅ | ✅ | ✅ | N/A
+
+## /process
+Endpoint/service | API Build | Kernel:Docker | Kernel:Unikraft | Notes
+--- | --- | --- | --- | --- 
+/process/exec | ✅ | ✅ | ✅ | N/A
+/process/spawn | ✅ | ✅ | ✅ | N/A
+/process/{process_id}/kill | ✅ | ✅ | ✅ | N/A
+/process/{process_id}/status | ✅ | ✅ | ✅ | N/A
+/process/{process_id}/stdin | ✅ | ✅ | ✅ | N/A
+/process/{process_id}/stdout/stream | ✅ | ✅ | ✅ | N/A
+
+## /recording
+Endpoint/service | API Build | Kernel:Docker | Kernel:Unikraft | Notes
+--- | --- | --- | --- | --- 
+/recording/delete | ✅ | ✅ | ✅ | N/A
+/recording/download | ✅ | ✅ | ✅ | N/A
+/recording/list | ✅ | ✅ | ✅ | N/A
+/recording/start | ✅ | ✅ | ✅ | N/A
+/recording/stop | ✅ | ✅ | ✅ | N/A
+
+## /screenshot
+Endpoint/service | API Build | Kernel:Docker | Kernel:Unikraft | Notes
+--- | --- | --- | --- | --- 
+/screenshot/capture | ✅ | ✅ | ✅ | N/A
+/screenshot/{screenshot_id} | ✅ | ✅ | ✅ | N/A
+
+## /scripts
+Endpoint/service | API Build | Kernel:Docker | Kernel:Unikraft | Notes
+--- | --- | --- | --- | --- 
+/scripts/delete | 〰️ | ✅ | ✅ | N/A
+/scripts/list | 〰️ | ✅ | ✅ | N/A
+/scripts/run | 〰️ | ✅ | ✅ | N/A
+/scripts/run/{run_id}/logs/stream | 〰️ | 〰️ | 〰️ | N/A
+/scripts/upload | 〰️ | ✅ | ✅ | N/A
+
+## /stream
+Endpoint/service | API Build | Kernel:Docker | Kernel:Unikraft | Notes
+--- | --- | --- | --- | --- 
+/stream/start | ✅ | ✅ | ✅ | N/A
+/stream/stop | ✅ | ✅ | ✅ | N/A
+/stream/{stream_id}/metrics/stream | ✅ | ✅ | ✅ | N/A
diff --git a/operator-api/bun.lock b/operator-api/bun.lock
new file mode 100644
index 00000000..f9844c70
--- /dev/null
+++ b/operator-api/bun.lock
@@ -0,0 +1,355 @@
+{
+  "lockfileVersion": 1,
+  "workspaces": {
+    "": {
+      "name": "kernel-operator-api",
+      "dependencies": {
+        "@hono/node-server": "^1.13.8",
+        "busboy": "^1.6.0",
+        "chalk": "^5.3.0",
+        "chokidar": "^3.6.0",
+        "dotenv": "^16.4.5",
+        "extract-zip": "^2.0.1",
+        "formdata-node": "^6.0.3",
+        "hono": "^4.5.10",
+        "http-proxy": "^1.18.1",
+        "httpolyglot": "^0.1.2",
+        "mime-types": "^2.1.35",
+        "morgan": "^1.10.0",
+        "nanoid": "^5.0.7",
+        "pidusage": "^3.0.2",
+        "uuid": "^11.1.0",
+        "ws": "^8.18.3",
+      },
+      "devDependencies": {
+        "cross-env": "^7.0.3",
+        "nodemon": "^3.1.7",
+        "undici": "^7.13.0",
+        "vitest": "^2.0.5",
+      },
+    },
+  },
+  "packages": {
+    "@esbuild/aix-ppc64": ["@esbuild/aix-ppc64@0.21.5", "", { "os": "aix", "cpu": "ppc64" }, "sha512-1SDgH6ZSPTlggy1yI6+Dbkiz8xzpHJEVAlF/AM1tHPLsf5STom9rwtjE4hKAF20FfXXNTFqEYXyJNWh1GiZedQ=="],
+
+    "@esbuild/android-arm": ["@esbuild/android-arm@0.21.5", "", { "os": "android", "cpu": "arm" }, "sha512-vCPvzSjpPHEi1siZdlvAlsPxXl7WbOVUBBAowWug4rJHb68Ox8KualB+1ocNvT5fjv6wpkX6o/iEpbDrf68zcg=="],
+
+    "@esbuild/android-arm64": ["@esbuild/android-arm64@0.21.5", "", { "os": "android", "cpu": "arm64" }, "sha512-c0uX9VAUBQ7dTDCjq+wdyGLowMdtR/GoC2U5IYk/7D1H1JYC0qseD7+11iMP2mRLN9RcCMRcjC4YMclCzGwS/A=="],
+
+    "@esbuild/android-x64": ["@esbuild/android-x64@0.21.5", "", { "os": "android", "cpu": "x64" }, "sha512-D7aPRUUNHRBwHxzxRvp856rjUHRFW1SdQATKXH2hqA0kAZb1hKmi02OpYRacl0TxIGz/ZmXWlbZgjwWYaCakTA=="],
+
+    "@esbuild/darwin-arm64": ["@esbuild/darwin-arm64@0.21.5", "", { "os": "darwin", "cpu": "arm64" }, "sha512-DwqXqZyuk5AiWWf3UfLiRDJ5EDd49zg6O9wclZ7kUMv2WRFr4HKjXp/5t8JZ11QbQfUS6/cRCKGwYhtNAY88kQ=="],
+
+    "@esbuild/darwin-x64": ["@esbuild/darwin-x64@0.21.5", "", { "os": "darwin", "cpu": "x64" }, "sha512-se/JjF8NlmKVG4kNIuyWMV/22ZaerB+qaSi5MdrXtd6R08kvs2qCN4C09miupktDitvh8jRFflwGFBQcxZRjbw=="],
+
+    "@esbuild/freebsd-arm64": ["@esbuild/freebsd-arm64@0.21.5", "", { "os": "freebsd", "cpu": "arm64" }, "sha512-5JcRxxRDUJLX8JXp/wcBCy3pENnCgBR9bN6JsY4OmhfUtIHe3ZW0mawA7+RDAcMLrMIZaf03NlQiX9DGyB8h4g=="],
+
+    "@esbuild/freebsd-x64": ["@esbuild/freebsd-x64@0.21.5", "", { "os": "freebsd", "cpu": "x64" }, "sha512-J95kNBj1zkbMXtHVH29bBriQygMXqoVQOQYA+ISs0/2l3T9/kj42ow2mpqerRBxDJnmkUDCaQT/dfNXWX/ZZCQ=="],
+
+    "@esbuild/linux-arm": ["@esbuild/linux-arm@0.21.5", "", { "os": "linux", "cpu": "arm" }, "sha512-bPb5AHZtbeNGjCKVZ9UGqGwo8EUu4cLq68E95A53KlxAPRmUyYv2D6F0uUI65XisGOL1hBP5mTronbgo+0bFcA=="],
+
+    "@esbuild/linux-arm64": ["@esbuild/linux-arm64@0.21.5", "", { "os": "linux", "cpu": "arm64" }, "sha512-ibKvmyYzKsBeX8d8I7MH/TMfWDXBF3db4qM6sy+7re0YXya+K1cem3on9XgdT2EQGMu4hQyZhan7TeQ8XkGp4Q=="],
+
+    "@esbuild/linux-ia32": ["@esbuild/linux-ia32@0.21.5", "", { "os": "linux", "cpu": "ia32" }, "sha512-YvjXDqLRqPDl2dvRODYmmhz4rPeVKYvppfGYKSNGdyZkA01046pLWyRKKI3ax8fbJoK5QbxblURkwK/MWY18Tg=="],
+
+    "@esbuild/linux-loong64": ["@esbuild/linux-loong64@0.21.5", "", { "os": "linux", "cpu": "none" }, "sha512-uHf1BmMG8qEvzdrzAqg2SIG/02+4/DHB6a9Kbya0XDvwDEKCoC8ZRWI5JJvNdUjtciBGFQ5PuBlpEOXQj+JQSg=="],
+
+    "@esbuild/linux-mips64el": ["@esbuild/linux-mips64el@0.21.5", "", { "os": "linux", "cpu": "none" }, "sha512-IajOmO+KJK23bj52dFSNCMsz1QP1DqM6cwLUv3W1QwyxkyIWecfafnI555fvSGqEKwjMXVLokcV5ygHW5b3Jbg=="],
+
+    "@esbuild/linux-ppc64": ["@esbuild/linux-ppc64@0.21.5", "", { "os": "linux", "cpu": "ppc64" }, "sha512-1hHV/Z4OEfMwpLO8rp7CvlhBDnjsC3CttJXIhBi+5Aj5r+MBvy4egg7wCbe//hSsT+RvDAG7s81tAvpL2XAE4w=="],
+
+    "@esbuild/linux-riscv64": ["@esbuild/linux-riscv64@0.21.5", "", { "os": "linux", "cpu": "none" }, "sha512-2HdXDMd9GMgTGrPWnJzP2ALSokE/0O5HhTUvWIbD3YdjME8JwvSCnNGBnTThKGEB91OZhzrJ4qIIxk/SBmyDDA=="],
+
+    "@esbuild/linux-s390x": ["@esbuild/linux-s390x@0.21.5", "", { "os": "linux", "cpu": "s390x" }, "sha512-zus5sxzqBJD3eXxwvjN1yQkRepANgxE9lgOW2qLnmr8ikMTphkjgXu1HR01K4FJg8h1kEEDAqDcZQtbrRnB41A=="],
+
+    "@esbuild/linux-x64": ["@esbuild/linux-x64@0.21.5", "", { "os": "linux", "cpu": "x64" }, "sha512-1rYdTpyv03iycF1+BhzrzQJCdOuAOtaqHTWJZCWvijKD2N5Xu0TtVC8/+1faWqcP9iBCWOmjmhoH94dH82BxPQ=="],
+
+    "@esbuild/netbsd-x64": ["@esbuild/netbsd-x64@0.21.5", "", { "os": "none", "cpu": "x64" }, "sha512-Woi2MXzXjMULccIwMnLciyZH4nCIMpWQAs049KEeMvOcNADVxo0UBIQPfSmxB3CWKedngg7sWZdLvLczpe0tLg=="],
+
+    "@esbuild/openbsd-x64": ["@esbuild/openbsd-x64@0.21.5", "", { "os": "openbsd", "cpu": "x64" }, "sha512-HLNNw99xsvx12lFBUwoT8EVCsSvRNDVxNpjZ7bPn947b8gJPzeHWyNVhFsaerc0n3TsbOINvRP2byTZ5LKezow=="],
+
+    "@esbuild/sunos-x64": ["@esbuild/sunos-x64@0.21.5", "", { "os": "sunos", "cpu": "x64" }, "sha512-6+gjmFpfy0BHU5Tpptkuh8+uw3mnrvgs+dSPQXQOv3ekbordwnzTVEb4qnIvQcYXq6gzkyTnoZ9dZG+D4garKg=="],
+
+    "@esbuild/win32-arm64": ["@esbuild/win32-arm64@0.21.5", "", { "os": "win32", "cpu": "arm64" }, "sha512-Z0gOTd75VvXqyq7nsl93zwahcTROgqvuAcYDUr+vOv8uHhNSKROyU961kgtCD1e95IqPKSQKH7tBTslnS3tA8A=="],
+
+    "@esbuild/win32-ia32": ["@esbuild/win32-ia32@0.21.5", "", { "os": "win32", "cpu": "ia32" }, "sha512-SWXFF1CL2RVNMaVs+BBClwtfZSvDgtL//G/smwAc5oVK/UPu2Gu9tIaRgFmYFFKrmg3SyAjSrElf0TiJ1v8fYA=="],
+
+    "@esbuild/win32-x64": ["@esbuild/win32-x64@0.21.5", "", { "os": "win32", "cpu": "x64" }, "sha512-tQd/1efJuzPC6rCFwEvLtci/xNFcTZknmXs98FYDfGE4wP9ClFV98nyKrzJKVPMhdDnjzLhdUyMX4PsQAPjwIw=="],
+
+    "@hono/node-server": ["@hono/node-server@1.18.1", "", { "peerDependencies": { "hono": "^4" } }, "sha512-O3puG/b7owYYmoQ2XPBf3SxBz6Dhk5VmWFhbaBU8/5wcUaXUPS0goxaI2Zfyg+Cu14ILJHEU7IFRw7miFxuXxg=="],
+
+    "@jridgewell/sourcemap-codec": ["@jridgewell/sourcemap-codec@1.5.4", "", {}, "sha512-VT2+G1VQs/9oz078bLrYbecdZKs912zQlkelYpuf+SXF+QvZDYJlbx/LSx+meSAwdDFnF8FVXW92AVjjkVmgFw=="],
+
+    "@rollup/rollup-android-arm-eabi": ["@rollup/rollup-android-arm-eabi@4.46.2", "", { "os": "android", "cpu": "arm" }, "sha512-Zj3Hl6sN34xJtMv7Anwb5Gu01yujyE/cLBDB2gnHTAHaWS1Z38L7kuSG+oAh0giZMqG060f/YBStXtMH6FvPMA=="],
+
+    "@rollup/rollup-android-arm64": ["@rollup/rollup-android-arm64@4.46.2", "", { "os": "android", "cpu": "arm64" }, "sha512-nTeCWY83kN64oQ5MGz3CgtPx8NSOhC5lWtsjTs+8JAJNLcP3QbLCtDDgUKQc/Ro/frpMq4SHUaHN6AMltcEoLQ=="],
+
+    "@rollup/rollup-darwin-arm64": ["@rollup/rollup-darwin-arm64@4.46.2", "", { "os": "darwin", "cpu": "arm64" }, "sha512-HV7bW2Fb/F5KPdM/9bApunQh68YVDU8sO8BvcW9OngQVN3HHHkw99wFupuUJfGR9pYLLAjcAOA6iO+evsbBaPQ=="],
+
+    "@rollup/rollup-darwin-x64": ["@rollup/rollup-darwin-x64@4.46.2", "", { "os": "darwin", "cpu": "x64" }, "sha512-SSj8TlYV5nJixSsm/y3QXfhspSiLYP11zpfwp6G/YDXctf3Xkdnk4woJIF5VQe0of2OjzTt8EsxnJDCdHd2xMA=="],
+
+    "@rollup/rollup-freebsd-arm64": ["@rollup/rollup-freebsd-arm64@4.46.2", "", { "os": "freebsd", "cpu": "arm64" }, "sha512-ZyrsG4TIT9xnOlLsSSi9w/X29tCbK1yegE49RYm3tu3wF1L/B6LVMqnEWyDB26d9Ecx9zrmXCiPmIabVuLmNSg=="],
+
+    "@rollup/rollup-freebsd-x64": ["@rollup/rollup-freebsd-x64@4.46.2", "", { "os": "freebsd", "cpu": "x64" }, "sha512-pCgHFoOECwVCJ5GFq8+gR8SBKnMO+xe5UEqbemxBpCKYQddRQMgomv1104RnLSg7nNvgKy05sLsY51+OVRyiVw=="],
+
+    "@rollup/rollup-linux-arm-gnueabihf": ["@rollup/rollup-linux-arm-gnueabihf@4.46.2", "", { "os": "linux", "cpu": "arm" }, "sha512-EtP8aquZ0xQg0ETFcxUbU71MZlHaw9MChwrQzatiE8U/bvi5uv/oChExXC4mWhjiqK7azGJBqU0tt5H123SzVA=="],
+
+    "@rollup/rollup-linux-arm-musleabihf": ["@rollup/rollup-linux-arm-musleabihf@4.46.2", "", { "os": "linux", "cpu": "arm" }, "sha512-qO7F7U3u1nfxYRPM8HqFtLd+raev2K137dsV08q/LRKRLEc7RsiDWihUnrINdsWQxPR9jqZ8DIIZ1zJJAm5PjQ=="],
+
+    "@rollup/rollup-linux-arm64-gnu": ["@rollup/rollup-linux-arm64-gnu@4.46.2", "", { "os": "linux", "cpu": "arm64" }, "sha512-3dRaqLfcOXYsfvw5xMrxAk9Lb1f395gkoBYzSFcc/scgRFptRXL9DOaDpMiehf9CO8ZDRJW2z45b6fpU5nwjng=="],
+
+    "@rollup/rollup-linux-arm64-musl": ["@rollup/rollup-linux-arm64-musl@4.46.2", "", { "os": "linux", "cpu": "arm64" }, "sha512-fhHFTutA7SM+IrR6lIfiHskxmpmPTJUXpWIsBXpeEwNgZzZZSg/q4i6FU4J8qOGyJ0TR+wXBwx/L7Ho9z0+uDg=="],
+
+    "@rollup/rollup-linux-loongarch64-gnu": ["@rollup/rollup-linux-loongarch64-gnu@4.46.2", "", { "os": "linux", "cpu": "none" }, "sha512-i7wfGFXu8x4+FRqPymzjD+Hyav8l95UIZ773j7J7zRYc3Xsxy2wIn4x+llpunexXe6laaO72iEjeeGyUFmjKeA=="],
+
+    "@rollup/rollup-linux-ppc64-gnu": ["@rollup/rollup-linux-ppc64-gnu@4.46.2", "", { "os": "linux", "cpu": "ppc64" }, "sha512-B/l0dFcHVUnqcGZWKcWBSV2PF01YUt0Rvlurci5P+neqY/yMKchGU8ullZvIv5e8Y1C6wOn+U03mrDylP5q9Yw=="],
+
+    "@rollup/rollup-linux-riscv64-gnu": ["@rollup/rollup-linux-riscv64-gnu@4.46.2", "", { "os": "linux", "cpu": "none" }, "sha512-32k4ENb5ygtkMwPMucAb8MtV8olkPT03oiTxJbgkJa7lJ7dZMr0GCFJlyvy+K8iq7F/iuOr41ZdUHaOiqyR3iQ=="],
+
+    "@rollup/rollup-linux-riscv64-musl": ["@rollup/rollup-linux-riscv64-musl@4.46.2", "", { "os": "linux", "cpu": "none" }, "sha512-t5B2loThlFEauloaQkZg9gxV05BYeITLvLkWOkRXogP4qHXLkWSbSHKM9S6H1schf/0YGP/qNKtiISlxvfmmZw=="],
+
+    "@rollup/rollup-linux-s390x-gnu": ["@rollup/rollup-linux-s390x-gnu@4.46.2", "", { "os": "linux", "cpu": "s390x" }, "sha512-YKjekwTEKgbB7n17gmODSmJVUIvj8CX7q5442/CK80L8nqOUbMtf8b01QkG3jOqyr1rotrAnW6B/qiHwfcuWQA=="],
+
+    "@rollup/rollup-linux-x64-gnu": ["@rollup/rollup-linux-x64-gnu@4.46.2", "", { "os": "linux", "cpu": "x64" }, "sha512-Jj5a9RUoe5ra+MEyERkDKLwTXVu6s3aACP51nkfnK9wJTraCC8IMe3snOfALkrjTYd2G1ViE1hICj0fZ7ALBPA=="],
+
+    "@rollup/rollup-linux-x64-musl": ["@rollup/rollup-linux-x64-musl@4.46.2", "", { "os": "linux", "cpu": "x64" }, "sha512-7kX69DIrBeD7yNp4A5b81izs8BqoZkCIaxQaOpumcJ1S/kmqNFjPhDu1LHeVXv0SexfHQv5cqHsxLOjETuqDuA=="],
+
+    "@rollup/rollup-win32-arm64-msvc": ["@rollup/rollup-win32-arm64-msvc@4.46.2", "", { "os": "win32", "cpu": "arm64" }, "sha512-wiJWMIpeaak/jsbaq2HMh/rzZxHVW1rU6coyeNNpMwk5isiPjSTx0a4YLSlYDwBH/WBvLz+EtsNqQScZTLJy3g=="],
+
+    "@rollup/rollup-win32-ia32-msvc": ["@rollup/rollup-win32-ia32-msvc@4.46.2", "", { "os": "win32", "cpu": "ia32" }, "sha512-gBgaUDESVzMgWZhcyjfs9QFK16D8K6QZpwAaVNJxYDLHWayOta4ZMjGm/vsAEy3hvlS2GosVFlBlP9/Wb85DqQ=="],
+
+    "@rollup/rollup-win32-x64-msvc": ["@rollup/rollup-win32-x64-msvc@4.46.2", "", { "os": "win32", "cpu": "x64" }, "sha512-CvUo2ixeIQGtF6WvuB87XWqPQkoFAFqW+HUo/WzHwuHDvIwZCtjdWXoYCcr06iKGydiqTclC4jU/TNObC/xKZg=="],
+
+    "@types/estree": ["@types/estree@1.0.8", "", {}, "sha512-dWHzHa2WqEXI/O1E9OjrocMTKJl2mSrEolh1Iomrv6U+JuNwaHXsXx9bLu5gG7BUWFIN0skIQJQ/L1rIex4X6w=="],
+
+    "@types/node": ["@types/node@24.2.1", "", { "dependencies": { "undici-types": "~7.10.0" } }, "sha512-DRh5K+ka5eJic8CjH7td8QpYEV6Zo10gfRkjHCO3weqZHWDtAaSTFtl4+VMqOJ4N5jcuhZ9/l+yy8rVgw7BQeQ=="],
+
+    "@types/yauzl": ["@types/yauzl@2.10.3", "", { "dependencies": { "@types/node": "*" } }, "sha512-oJoftv0LSuaDZE3Le4DbKX+KS9G36NzOeSap90UIK0yMA/NhKJhqlSGtNDORNRaIbQfzjXDrQa0ytJ6mNRGz/Q=="],
+
+    "@vitest/expect": ["@vitest/expect@2.1.9", "", { "dependencies": { "@vitest/spy": "2.1.9", "@vitest/utils": "2.1.9", "chai": "^5.1.2", "tinyrainbow": "^1.2.0" } }, "sha512-UJCIkTBenHeKT1TTlKMJWy1laZewsRIzYighyYiJKZreqtdxSos/S1t+ktRMQWu2CKqaarrkeszJx1cgC5tGZw=="],
+
+    "@vitest/mocker": ["@vitest/mocker@2.1.9", "", { "dependencies": { "@vitest/spy": "2.1.9", "estree-walker": "^3.0.3", "magic-string": "^0.30.12" }, "peerDependencies": { "msw": "^2.4.9", "vite": "^5.0.0" }, "optionalPeers": ["msw", "vite"] }, "sha512-tVL6uJgoUdi6icpxmdrn5YNo3g3Dxv+IHJBr0GXHaEdTcw3F+cPKnsXFhli6nO+f/6SDKPHEK1UN+k+TQv0Ehg=="],
+
+    "@vitest/pretty-format": ["@vitest/pretty-format@2.1.9", "", { "dependencies": { "tinyrainbow": "^1.2.0" } }, "sha512-KhRIdGV2U9HOUzxfiHmY8IFHTdqtOhIzCpd8WRdJiE7D/HUcZVD0EgQCVjm+Q9gkUXWgBvMmTtZgIG48wq7sOQ=="],
+
+    "@vitest/runner": ["@vitest/runner@2.1.9", "", { "dependencies": { "@vitest/utils": "2.1.9", "pathe": "^1.1.2" } }, "sha512-ZXSSqTFIrzduD63btIfEyOmNcBmQvgOVsPNPe0jYtESiXkhd8u2erDLnMxmGrDCwHCCHE7hxwRDCT3pt0esT4g=="],
+
+    "@vitest/snapshot": ["@vitest/snapshot@2.1.9", "", { "dependencies": { "@vitest/pretty-format": "2.1.9", "magic-string": "^0.30.12", "pathe": "^1.1.2" } }, "sha512-oBO82rEjsxLNJincVhLhaxxZdEtV0EFHMK5Kmx5sJ6H9L183dHECjiefOAdnqpIgT5eZwT04PoggUnW88vOBNQ=="],
+
+    "@vitest/spy": ["@vitest/spy@2.1.9", "", { "dependencies": { "tinyspy": "^3.0.2" } }, "sha512-E1B35FwzXXTs9FHNK6bDszs7mtydNi5MIfUWpceJ8Xbfb1gBMscAnwLbEu+B44ed6W3XjL9/ehLPHR1fkf1KLQ=="],
+
+    "@vitest/utils": ["@vitest/utils@2.1.9", "", { "dependencies": { "@vitest/pretty-format": "2.1.9", "loupe": "^3.1.2", "tinyrainbow": "^1.2.0" } }, "sha512-v0psaMSkNJ3A2NMrUEHFRzJtDPFn+/VWZ5WxImB21T9fjucJRmS7xCS3ppEnARb9y11OAzaD+P2Ps+b+BGX5iQ=="],
+
+    "anymatch": ["anymatch@3.1.3", "", { "dependencies": { "normalize-path": "^3.0.0", "picomatch": "^2.0.4" } }, "sha512-KMReFUr0B4t+D+OBkjR3KYqvocp2XaSzO55UcB6mgQMd3KbcE+mWTyvVV7D/zsdEbNnV6acZUutkiHQXvTr1Rw=="],
+
+    "assertion-error": ["assertion-error@2.0.1", "", {}, "sha512-Izi8RQcffqCeNVgFigKli1ssklIbpHnCYc6AknXGYoB6grJqyeby7jv12JUQgmTAnIDnbck1uxksT4dzN3PWBA=="],
+
+    "balanced-match": ["balanced-match@1.0.2", "", {}, "sha512-3oSeUO0TMV67hN1AmbXsK4yaqU7tjiHlbxRDZOpH0KW9+CeX4bRAaX0Anxt0tx2MrpRpWwQaPwIlISEJhYU5Pw=="],
+
+    "basic-auth": ["basic-auth@2.0.1", "", { "dependencies": { "safe-buffer": "5.1.2" } }, "sha512-NF+epuEdnUYVlGuhaxbbq+dvJttwLnGY+YixlXlME5KpQ5W3CnXA5cVTneY3SPbPDRkcjMbifrwmFYcClgOZeg=="],
+
+    "binary-extensions": ["binary-extensions@2.3.0", "", {}, "sha512-Ceh+7ox5qe7LJuLHoY0feh3pHuUDHAcRUeyL2VYghZwfpkNIy/+8Ocg0a3UuSoYzavmylwuLWQOf3hl0jjMMIw=="],
+
+    "brace-expansion": ["brace-expansion@1.1.12", "", { "dependencies": { "balanced-match": "^1.0.0", "concat-map": "0.0.1" } }, "sha512-9T9UjW3r0UW5c1Q7GTwllptXwhvYmEzFhzMfZ9H7FQWt+uZePjZPjBP/W1ZEyZ1twGWom5/56TF4lPcqjnDHcg=="],
+
+    "braces": ["braces@3.0.3", "", { "dependencies": { "fill-range": "^7.1.1" } }, "sha512-yQbXgO/OSZVD2IsiLlro+7Hf6Q18EJrKSEsdoMzKePKXct3gvD8oLcOQdIzGupr5Fj+EDe8gO/lxc1BzfMpxvA=="],
+
+    "buffer-crc32": ["buffer-crc32@0.2.13", "", {}, "sha512-VO9Ht/+p3SN7SKWqcrgEzjGbRSJYTx+Q1pTQC0wrWqHx0vpJraQ6GtHx8tvcg1rlK1byhU5gccxgOgj7B0TDkQ=="],
+
+    "busboy": ["busboy@1.6.0", "", { "dependencies": { "streamsearch": "^1.1.0" } }, "sha512-8SFQbg/0hQ9xy3UNTB0YEnsNBbWfhf7RtnzpL7TkBiTBRfrQ9Fxcnz7VJsleJpyp6rVLvXiuORqjlHi5q+PYuA=="],
+
+    "cac": ["cac@6.7.14", "", {}, "sha512-b6Ilus+c3RrdDk+JhLKUAQfzzgLEPy6wcXqS7f/xe1EETvsDP6GORG7SFuOs6cID5YkqchW/LXZbX5bc8j7ZcQ=="],
+
+    "chai": ["chai@5.2.1", "", { "dependencies": { "assertion-error": "^2.0.1", "check-error": "^2.1.1", "deep-eql": "^5.0.1", "loupe": "^3.1.0", "pathval": "^2.0.0" } }, "sha512-5nFxhUrX0PqtyogoYOA8IPswy5sZFTOsBFl/9bNsmDLgsxYTzSZQJDPppDnZPTQbzSEm0hqGjWPzRemQCYbD6A=="],
+
+    "chalk": ["chalk@5.5.0", "", {}, "sha512-1tm8DTaJhPBG3bIkVeZt1iZM9GfSX2lzOeDVZH9R9ffRHpmHvxZ/QhgQH/aDTkswQVt+YHdXAdS/In/30OjCbg=="],
+
+    "check-error": ["check-error@2.1.1", "", {}, "sha512-OAlb+T7V4Op9OwdkjmguYRqncdlx5JiofwOAUkmTF+jNdHwzTaTs4sRAGpzLF3oOz5xAyDGrPgeIDFQmDOTiJw=="],
+
+    "chokidar": ["chokidar@3.6.0", "", { "dependencies": { "anymatch": "~3.1.2", "braces": "~3.0.2", "glob-parent": "~5.1.2", "is-binary-path": "~2.1.0", "is-glob": "~4.0.1", "normalize-path": "~3.0.0", "readdirp": "~3.6.0" }, "optionalDependencies": { "fsevents": "~2.3.2" } }, "sha512-7VT13fmjotKpGipCW9JEQAusEPE+Ei8nl6/g4FBAmIm0GOOLMua9NDDo/DWp0ZAxCr3cPq5ZpBqmPAQgDda2Pw=="],
+
+    "concat-map": ["concat-map@0.0.1", "", {}, "sha512-/Srv4dswyQNBfohGpz9o6Yb3Gz3SrUDqBH5rTuhGR7ahtlbYKnVxw2bCFMRljaA7EXHaXZ8wsHdodFvbkhKmqg=="],
+
+    "cross-env": ["cross-env@7.0.3", "", { "dependencies": { "cross-spawn": "^7.0.1" }, "bin": { "cross-env": "src/bin/cross-env.js", "cross-env-shell": "src/bin/cross-env-shell.js" } }, "sha512-+/HKd6EgcQCJGh2PSjZuUitQBQynKor4wrFbRg4DtAgS1aWO+gU52xpH7M9ScGgXSYmAVS9bIJ8EzuaGw0oNAw=="],
+
+    "cross-spawn": ["cross-spawn@7.0.6", "", { "dependencies": { "path-key": "^3.1.0", "shebang-command": "^2.0.0", "which": "^2.0.1" } }, "sha512-uV2QOWP2nWzsy2aMp8aRibhi9dlzF5Hgh5SHaB9OiTGEyDTiJJyx0uy51QXdyWbtAHNua4XJzUKca3OzKUd3vA=="],
+
+    "debug": ["debug@4.4.1", "", { "dependencies": { "ms": "^2.1.3" } }, "sha512-KcKCqiftBJcZr++7ykoDIEwSa3XWowTfNPo92BYxjXiyYEVrUQh2aLyhxBCwww+heortUFxEJYcRzosstTEBYQ=="],
+
+    "deep-eql": ["deep-eql@5.0.2", "", {}, "sha512-h5k/5U50IJJFpzfL6nO9jaaumfjO/f2NjK/oYB2Djzm4p9L+3T9qWpZqZ2hAbLPuuYq9wrU08WQyBTL5GbPk5Q=="],
+
+    "depd": ["depd@2.0.0", "", {}, "sha512-g7nH6P6dyDioJogAAGprGpCtVImJhpPk/roCzdb3fIh61/s/nPsfR6onyMwkCAR/OlC3yBC0lESvUoQEAssIrw=="],
+
+    "dotenv": ["dotenv@16.6.1", "", {}, "sha512-uBq4egWHTcTt33a72vpSG0z3HnPuIl6NqYcTrKEg2azoEyl2hpW0zqlxysq2pK9HlDIHyHyakeYaYnSAwd8bow=="],
+
+    "ee-first": ["ee-first@1.1.1", "", {}, "sha512-WMwm9LhRUo+WUaRN+vRuETqG89IgZphVSNkdFgeb6sS/E4OrDIN7t48CAewSHXc6C8lefD8KKfr5vY61brQlow=="],
+
+    "end-of-stream": ["end-of-stream@1.4.5", "", { "dependencies": { "once": "^1.4.0" } }, "sha512-ooEGc6HP26xXq/N+GCGOT0JKCLDGrq2bQUZrQ7gyrJiZANJ/8YDTxTpQBXGMn+WbIQXNVpyWymm7KYVICQnyOg=="],
+
+    "es-module-lexer": ["es-module-lexer@1.7.0", "", {}, "sha512-jEQoCwk8hyb2AZziIOLhDqpm5+2ww5uIE6lkO/6jcOCusfk6LhMHpXXfBLXTZ7Ydyt0j4VoUQv6uGNYbdW+kBA=="],
+
+    "esbuild": ["esbuild@0.21.5", "", { "optionalDependencies": { "@esbuild/aix-ppc64": "0.21.5", "@esbuild/android-arm": "0.21.5", "@esbuild/android-arm64": "0.21.5", "@esbuild/android-x64": "0.21.5", "@esbuild/darwin-arm64": "0.21.5", "@esbuild/darwin-x64": "0.21.5", "@esbuild/freebsd-arm64": "0.21.5", "@esbuild/freebsd-x64": "0.21.5", "@esbuild/linux-arm": "0.21.5", "@esbuild/linux-arm64": "0.21.5", "@esbuild/linux-ia32": "0.21.5", "@esbuild/linux-loong64": "0.21.5", "@esbuild/linux-mips64el": "0.21.5", "@esbuild/linux-ppc64": "0.21.5", "@esbuild/linux-riscv64": "0.21.5", "@esbuild/linux-s390x": "0.21.5", "@esbuild/linux-x64": "0.21.5", "@esbuild/netbsd-x64": "0.21.5", "@esbuild/openbsd-x64": "0.21.5", "@esbuild/sunos-x64": "0.21.5", "@esbuild/win32-arm64": "0.21.5", "@esbuild/win32-ia32": "0.21.5", "@esbuild/win32-x64": "0.21.5" }, "bin": { "esbuild": "bin/esbuild" } }, "sha512-mg3OPMV4hXywwpoDxu3Qda5xCKQi+vCTZq8S9J/EpkhB2HzKXq4SNFZE3+NK93JYxc8VMSep+lOUSC/RVKaBqw=="],
+
+    "estree-walker": ["estree-walker@3.0.3", "", { "dependencies": { "@types/estree": "^1.0.0" } }, "sha512-7RUKfXgSMMkzt6ZuXmqapOurLGPPfgj6l9uRZ7lRGolvk0y2yocc35LdcxKC5PQZdn2DMqioAQ2NoWcrTKmm6g=="],
+
+    "eventemitter3": ["eventemitter3@4.0.7", "", {}, "sha512-8guHBZCwKnFhYdHr2ysuRWErTwhoN2X8XELRlrRwpmfeY2jjuUN4taQMsULKUVo1K4DvZl+0pgfyoysHxvmvEw=="],
+
+    "expect-type": ["expect-type@1.2.2", "", {}, "sha512-JhFGDVJ7tmDJItKhYgJCGLOWjuK9vPxiXoUFLwLDc99NlmklilbiQJwoctZtt13+xMw91MCk/REan6MWHqDjyA=="],
+
+    "extract-zip": ["extract-zip@2.0.1", "", { "dependencies": { "debug": "^4.1.1", "get-stream": "^5.1.0", "yauzl": "^2.10.0" }, "optionalDependencies": { "@types/yauzl": "^2.9.1" }, "bin": { "extract-zip": "cli.js" } }, "sha512-GDhU9ntwuKyGXdZBUgTIe+vXnWj0fppUEtMDL0+idd5Sta8TGpHssn/eusA9mrPr9qNDym6SxAYZjNvCn/9RBg=="],
+
+    "fd-slicer": ["fd-slicer@1.1.0", "", { "dependencies": { "pend": "~1.2.0" } }, "sha512-cE1qsB/VwyQozZ+q1dGxR8LBYNZeofhEdUNGSMbQD3Gw2lAzX9Zb3uIU6Ebc/Fmyjo9AWWfnn0AUCHqtevs/8g=="],
+
+    "fill-range": ["fill-range@7.1.1", "", { "dependencies": { "to-regex-range": "^5.0.1" } }, "sha512-YsGpe3WHLK8ZYi4tWDg2Jy3ebRz2rXowDxnld4bkQB00cc/1Zw9AWnC0i9ztDJitivtQvaI9KaLyKrc+hBW0yg=="],
+
+    "follow-redirects": ["follow-redirects@1.15.11", "", {}, "sha512-deG2P0JfjrTxl50XGCDyfI97ZGVCxIpfKYmfyrQ54n5FO/0gfIES8C/Psl6kWVDolizcaaxZJnTS0QSMxvnsBQ=="],
+
+    "formdata-node": ["formdata-node@6.0.3", "", {}, "sha512-8e1++BCiTzUno9v5IZ2J6bv4RU+3UKDmqWUQD0MIMVCd9AdhWkO1gw57oo1mNEX1dMq2EGI+FbWz4B92pscSQg=="],
+
+    "fsevents": ["fsevents@2.3.3", "", { "os": "darwin" }, "sha512-5xoDfX+fL7faATnagmWPpbFtwh/R77WmMMqqHGS65C3vvB0YHrgF+B1YmZ3441tMj5n63k0212XNoJwzlhffQw=="],
+
+    "get-stream": ["get-stream@5.2.0", "", { "dependencies": { "pump": "^3.0.0" } }, "sha512-nBF+F1rAZVCu/p7rjzgA+Yb4lfYXrpl7a6VmJrU8wF9I1CKvP/QwPNZHnOlwbTkY6dvtFIzFMSyQXbLoTQPRpA=="],
+
+    "glob-parent": ["glob-parent@5.1.2", "", { "dependencies": { "is-glob": "^4.0.1" } }, "sha512-AOIgSQCepiJYwP3ARnGx+5VnTu2HBYdzbGP45eLw1vr3zB3vZLeyed1sC9hnbcOc9/SrMyM5RPQrkGz4aS9Zow=="],
+
+    "has-flag": ["has-flag@3.0.0", "", {}, "sha512-sKJf1+ceQBr4SMkvQnBDNDtf4TXpVhVGateu0t918bl30FnbE2m4vNLX+VWe/dpjlb+HugGYzW7uQXH98HPEYw=="],
+
+    "hono": ["hono@4.9.0", "", {}, "sha512-JAUc4Sqi3lhby2imRL/67LMcJFKiCu7ZKghM7iwvltVZzxEC5bVJCsAa4NTnSfmWGb+N2eOVtFE586R+K3fejA=="],
+
+    "http-proxy": ["http-proxy@1.18.1", "", { "dependencies": { "eventemitter3": "^4.0.0", "follow-redirects": "^1.0.0", "requires-port": "^1.0.0" } }, "sha512-7mz/721AbnJwIVbnaSv1Cz3Am0ZLT/UBwkC92VlxhXv/k/BBQfM2fXElQNC27BVGr0uwUpplYPQM9LnaBMR5NQ=="],
+
+    "httpolyglot": ["httpolyglot@0.1.2", "", {}, "sha512-ouHI1AaQMLgn4L224527S5+vq6hgvqPteurVfbm7ChViM3He2Wa8KP1Ny7pTYd7QKnDSPKcN8JYfC8r/lmsE3A=="],
+
+    "ignore-by-default": ["ignore-by-default@1.0.1", "", {}, "sha512-Ius2VYcGNk7T90CppJqcIkS5ooHUZyIQK+ClZfMfMNFEF9VSE73Fq+906u/CWu92x4gzZMWOwfFYckPObzdEbA=="],
+
+    "is-binary-path": ["is-binary-path@2.1.0", "", { "dependencies": { "binary-extensions": "^2.0.0" } }, "sha512-ZMERYes6pDydyuGidse7OsHxtbI7WVeUEozgR/g7rd0xUimYNlvZRE/K2MgZTjWy725IfelLeVcEM97mmtRGXw=="],
+
+    "is-extglob": ["is-extglob@2.1.1", "", {}, "sha512-SbKbANkN603Vi4jEZv49LeVJMn4yGwsbzZworEoyEiutsN3nJYdbO36zfhGJ6QEDpOZIFkDtnq5JRxmvl3jsoQ=="],
+
+    "is-glob": ["is-glob@4.0.3", "", { "dependencies": { "is-extglob": "^2.1.1" } }, "sha512-xelSayHH36ZgE7ZWhli7pW34hNbNl8Ojv5KVmkJD4hBdD3th8Tfk9vYasLM+mXWOZhFkgZfxhLSnrwRr4elSSg=="],
+
+    "is-number": ["is-number@7.0.0", "", {}, "sha512-41Cifkg6e8TylSpdtTpeLVMqvSBEVzTttHvERD741+pnZ8ANv0004MRL43QKPDlK9cGvNp6NZWZUBlbGXYxxng=="],
+
+    "isexe": ["isexe@2.0.0", "", {}, "sha512-RHxMLp9lnKHGHRng9QFhRCMbYAcVpn69smSGcq3f36xjgVVWThj4qqLbTLlq7Ssj8B+fIQ1EuCEGI2lKsyQeIw=="],
+
+    "loupe": ["loupe@3.2.0", "", {}, "sha512-2NCfZcT5VGVNX9mSZIxLRkEAegDGBpuQZBy13desuHeVORmBDyAET4TkJr4SjqQy3A8JDofMN6LpkK8Xcm/dlw=="],
+
+    "magic-string": ["magic-string@0.30.17", "", { "dependencies": { "@jridgewell/sourcemap-codec": "^1.5.0" } }, "sha512-sNPKHvyjVf7gyjwS4xGTaW/mCnF8wnjtifKBEhxfZ7E/S8tQ0rssrwGNn6q8JH/ohItJfSQp9mBtQYuTlH5QnA=="],
+
+    "mime-db": ["mime-db@1.52.0", "", {}, "sha512-sPU4uV7dYlvtWJxwwxHD0PuihVNiE7TyAbQ5SWxDCB9mUYvOgroQOwYQQOKPJ8CIbE+1ETVlOoK1UC2nU3gYvg=="],
+
+    "mime-types": ["mime-types@2.1.35", "", { "dependencies": { "mime-db": "1.52.0" } }, "sha512-ZDY+bPm5zTTF+YpCrAU9nK0UgICYPT0QtT1NZWFv4s++TNkcgVaT0g6+4R2uI4MjQjzysHB1zxuWL50hzaeXiw=="],
+
+    "minimatch": ["minimatch@3.1.2", "", { "dependencies": { "brace-expansion": "^1.1.7" } }, "sha512-J7p63hRiAjw1NDEww1W7i37+ByIrOWO5XQQAzZ3VOcL0PNybwpfmV/N05zFAzwQ9USyEcX6t3UO+K5aqBQOIHw=="],
+
+    "morgan": ["morgan@1.10.1", "", { "dependencies": { "basic-auth": "~2.0.1", "debug": "2.6.9", "depd": "~2.0.0", "on-finished": "~2.3.0", "on-headers": "~1.1.0" } }, "sha512-223dMRJtI/l25dJKWpgij2cMtywuG/WiUKXdvwfbhGKBhy1puASqXwFzmWZ7+K73vUPoR7SS2Qz2cI/g9MKw0A=="],
+
+    "ms": ["ms@2.1.3", "", {}, "sha512-6FlzubTLZG3J2a/NVCAleEhjzq5oxgHyaCU9yYXvcLsvoVaHJq/s5xXI6/XXP6tz7R9xAOtHnSO/tXtF3WRTlA=="],
+
+    "nanoid": ["nanoid@5.1.5", "", { "bin": { "nanoid": "bin/nanoid.js" } }, "sha512-Ir/+ZpE9fDsNH0hQ3C68uyThDXzYcim2EqcZ8zn8Chtt1iylPT9xXJB0kPCnqzgcEGikO9RxSrh63MsmVCU7Fw=="],
+
+    "nodemon": ["nodemon@3.1.10", "", { "dependencies": { "chokidar": "^3.5.2", "debug": "^4", "ignore-by-default": "^1.0.1", "minimatch": "^3.1.2", "pstree.remy": "^1.1.8", "semver": "^7.5.3", "simple-update-notifier": "^2.0.0", "supports-color": "^5.5.0", "touch": "^3.1.0", "undefsafe": "^2.0.5" }, "bin": { "nodemon": "bin/nodemon.js" } }, "sha512-WDjw3pJ0/0jMFmyNDp3gvY2YizjLmmOUQo6DEBY+JgdvW/yQ9mEeSw6H5ythl5Ny2ytb7f9C2nIbjSxMNzbJXw=="],
+
+    "normalize-path": ["normalize-path@3.0.0", "", {}, "sha512-6eZs5Ls3WtCisHWp9S2GUy8dqkpGi4BVSz3GaqiE6ezub0512ESztXUwUB6C6IKbQkY2Pnb/mD4WYojCRwcwLA=="],
+
+    "on-finished": ["on-finished@2.3.0", "", { "dependencies": { "ee-first": "1.1.1" } }, "sha512-ikqdkGAAyf/X/gPhXGvfgAytDZtDbr+bkNUJ0N9h5MI/dmdgCs3l6hoHrcUv41sRKew3jIwrp4qQDXiK99Utww=="],
+
+    "on-headers": ["on-headers@1.1.0", "", {}, "sha512-737ZY3yNnXy37FHkQxPzt4UZ2UWPWiCZWLvFZ4fu5cueciegX0zGPnrlY6bwRg4FdQOe9YU8MkmJwGhoMybl8A=="],
+
+    "once": ["once@1.4.0", "", { "dependencies": { "wrappy": "1" } }, "sha512-lNaJgI+2Q5URQBkccEKHTQOPaXdUxnZZElQTZY0MFUAuaEqe1E+Nyvgdz/aIyNi6Z9MzO5dv1H8n58/GELp3+w=="],
+
+    "path-key": ["path-key@3.1.1", "", {}, "sha512-ojmeN0qd+y0jszEtoY48r0Peq5dwMEkIlCOu6Q5f41lfkswXuKtYrhgoTpLnyIcHm24Uhqx+5Tqm2InSwLhE6Q=="],
+
+    "pathe": ["pathe@1.1.2", "", {}, "sha512-whLdWMYL2TwI08hn8/ZqAbrVemu0LNaNNJZX73O6qaIdCTfXutsLhMkjdENX0qhsQ9uIimo4/aQOmXkoon2nDQ=="],
+
+    "pathval": ["pathval@2.0.1", "", {}, "sha512-//nshmD55c46FuFw26xV/xFAaB5HF9Xdap7HJBBnrKdAd6/GxDBaNA1870O79+9ueg61cZLSVc+OaFlfmObYVQ=="],
+
+    "pend": ["pend@1.2.0", "", {}, "sha512-F3asv42UuXchdzt+xXqfW1OGlVBe+mxa2mqI0pg5yAHZPvFmY3Y6drSf/GQ1A86WgWEN9Kzh/WrgKa6iGcHXLg=="],
+
+    "picocolors": ["picocolors@1.1.1", "", {}, "sha512-xceH2snhtb5M9liqDsmEw56le376mTZkEX/jEb/RxNFyegNul7eNslCXP9FDj/Lcu0X8KEyMceP2ntpaHrDEVA=="],
+
+    "picomatch": ["picomatch@2.3.1", "", {}, "sha512-JU3teHTNjmE2VCGFzuY8EXzCDVwEqB2a8fsIvwaStHhAWJEeVd1o1QD80CU6+ZdEXXSLbSsuLwJjkCBWqRQUVA=="],
+
+    "pidusage": ["pidusage@3.0.2", "", { "dependencies": { "safe-buffer": "^5.2.1" } }, "sha512-g0VU+y08pKw5M8EZ2rIGiEBaB8wrQMjYGFfW2QVIfyT8V+fq8YFLkvlz4bz5ljvFDJYNFCWT3PWqcRr2FKO81w=="],
+
+    "postcss": ["postcss@8.5.6", "", { "dependencies": { "nanoid": "^3.3.11", "picocolors": "^1.1.1", "source-map-js": "^1.2.1" } }, "sha512-3Ybi1tAuwAP9s0r1UQ2J4n5Y0G05bJkpUIO0/bI9MhwmD70S5aTWbXGBwxHrelT+XM1k6dM0pk+SwNkpTRN7Pg=="],
+
+    "pstree.remy": ["pstree.remy@1.1.8", "", {}, "sha512-77DZwxQmxKnu3aR542U+X8FypNzbfJ+C5XQDk3uWjWxn6151aIMGthWYRXTqT1E5oJvg+ljaa2OJi+VfvCOQ8w=="],
+
+    "pump": ["pump@3.0.3", "", { "dependencies": { "end-of-stream": "^1.1.0", "once": "^1.3.1" } }, "sha512-todwxLMY7/heScKmntwQG8CXVkWUOdYxIvY2s0VWAAMh/nd8SoYiRaKjlr7+iCs984f2P8zvrfWcDDYVb73NfA=="],
+
+    "readdirp": ["readdirp@3.6.0", "", { "dependencies": { "picomatch": "^2.2.1" } }, "sha512-hOS089on8RduqdbhvQ5Z37A0ESjsqz6qnRcffsMU3495FuTdqSm+7bhJ29JvIOsBDEEnan5DPu9t3To9VRlMzA=="],
+
+    "requires-port": ["requires-port@1.0.0", "", {}, "sha512-KigOCHcocU3XODJxsu8i/j8T9tzT4adHiecwORRQ0ZZFcp7ahwXuRU1m+yuO90C5ZUyGeGfocHDI14M3L3yDAQ=="],
+
+    "rollup": ["rollup@4.46.2", "", { "dependencies": { "@types/estree": "1.0.8" }, "optionalDependencies": { "@rollup/rollup-android-arm-eabi": "4.46.2", "@rollup/rollup-android-arm64": "4.46.2", "@rollup/rollup-darwin-arm64": "4.46.2", "@rollup/rollup-darwin-x64": "4.46.2", "@rollup/rollup-freebsd-arm64": "4.46.2", "@rollup/rollup-freebsd-x64": "4.46.2", "@rollup/rollup-linux-arm-gnueabihf": "4.46.2", "@rollup/rollup-linux-arm-musleabihf": "4.46.2", "@rollup/rollup-linux-arm64-gnu": "4.46.2", "@rollup/rollup-linux-arm64-musl": "4.46.2", "@rollup/rollup-linux-loongarch64-gnu": "4.46.2", "@rollup/rollup-linux-ppc64-gnu": "4.46.2", "@rollup/rollup-linux-riscv64-gnu": "4.46.2", "@rollup/rollup-linux-riscv64-musl": "4.46.2", "@rollup/rollup-linux-s390x-gnu": "4.46.2", "@rollup/rollup-linux-x64-gnu": "4.46.2", "@rollup/rollup-linux-x64-musl": "4.46.2", "@rollup/rollup-win32-arm64-msvc": "4.46.2", "@rollup/rollup-win32-ia32-msvc": "4.46.2", "@rollup/rollup-win32-x64-msvc": "4.46.2", "fsevents": "~2.3.2" }, "bin": { "rollup": "dist/bin/rollup" } }, "sha512-WMmLFI+Boh6xbop+OAGo9cQ3OgX9MIg7xOQjn+pTCwOkk+FNDAeAemXkJ3HzDJrVXleLOFVa1ipuc1AmEx1Dwg=="],
+
+    "safe-buffer": ["safe-buffer@5.2.1", "", {}, "sha512-rp3So07KcdmmKbGvgaNxQSJr7bGVSVk5S9Eq1F+ppbRo70+YeaDxkw5Dd8NPN+GD6bjnYm2VuPuCXmpuYvmCXQ=="],
+
+    "semver": ["semver@7.7.2", "", { "bin": { "semver": "bin/semver.js" } }, "sha512-RF0Fw+rO5AMf9MAyaRXI4AV0Ulj5lMHqVxxdSgiVbixSCXoEmmX/jk0CuJw4+3SqroYO9VoUh+HcuJivvtJemA=="],
+
+    "shebang-command": ["shebang-command@2.0.0", "", { "dependencies": { "shebang-regex": "^3.0.0" } }, "sha512-kHxr2zZpYtdmrN1qDjrrX/Z1rR1kG8Dx+gkpK1G4eXmvXswmcE1hTWBWYUzlraYw1/yZp6YuDY77YtvbN0dmDA=="],
+
+    "shebang-regex": ["shebang-regex@3.0.0", "", {}, "sha512-7++dFhtcx3353uBaq8DDR4NuxBetBzC7ZQOhmTQInHEd6bSrXdiEyzCvG07Z44UYdLShWUyXt5M/yhz8ekcb1A=="],
+
+    "siginfo": ["siginfo@2.0.0", "", {}, "sha512-ybx0WO1/8bSBLEWXZvEd7gMW3Sn3JFlW3TvX1nREbDLRNQNaeNN8WK0meBwPdAaOI7TtRRRJn/Es1zhrrCHu7g=="],
+
+    "simple-update-notifier": ["simple-update-notifier@2.0.0", "", { "dependencies": { "semver": "^7.5.3" } }, "sha512-a2B9Y0KlNXl9u/vsW6sTIu9vGEpfKu2wRV6l1H3XEas/0gUIzGzBoP/IouTcUQbm9JWZLH3COxyn03TYlFax6w=="],
+
+    "source-map-js": ["source-map-js@1.2.1", "", {}, "sha512-UXWMKhLOwVKb728IUtQPXxfYU+usdybtUrK/8uGE8CQMvrhOpwvzDBwj0QhSL7MQc7vIsISBG8VQ8+IDQxpfQA=="],
+
+    "stackback": ["stackback@0.0.2", "", {}, "sha512-1XMJE5fQo1jGH6Y/7ebnwPOBEkIEnT4QF32d5R1+VXdXveM0IBMJt8zfaxX1P3QhVwrYe+576+jkANtSS2mBbw=="],
+
+    "std-env": ["std-env@3.9.0", "", {}, "sha512-UGvjygr6F6tpH7o2qyqR6QYpwraIjKSdtzyBdyytFOHmPZY917kwdwLG0RbOjWOnKmnm3PeHjaoLLMie7kPLQw=="],
+
+    "streamsearch": ["streamsearch@1.1.0", "", {}, "sha512-Mcc5wHehp9aXz1ax6bZUyY5afg9u2rv5cqQI3mRrYkGC8rW2hM02jWuwjtL++LS5qinSyhj2QfLyNsuc+VsExg=="],
+
+    "supports-color": ["supports-color@5.5.0", "", { "dependencies": { "has-flag": "^3.0.0" } }, "sha512-QjVjwdXIt408MIiAqCX4oUKsgU2EqAGzs2Ppkm4aQYbjm+ZEWEcW4SfFNTr4uMNZma0ey4f5lgLrkB0aX0QMow=="],
+
+    "tinybench": ["tinybench@2.9.0", "", {}, "sha512-0+DUvqWMValLmha6lr4kD8iAMK1HzV0/aKnCtWb9v9641TnP/MFb7Pc2bxoxQjTXAErryXVgUOfv2YqNllqGeg=="],
+
+    "tinyexec": ["tinyexec@0.3.2", "", {}, "sha512-KQQR9yN7R5+OSwaK0XQoj22pwHoTlgYqmUscPYoknOoWCWfj/5/ABTMRi69FrKU5ffPVh5QcFikpWJI/P1ocHA=="],
+
+    "tinypool": ["tinypool@1.1.1", "", {}, "sha512-Zba82s87IFq9A9XmjiX5uZA/ARWDrB03OHlq+Vw1fSdt0I+4/Kutwy8BP4Y/y/aORMo61FQ0vIb5j44vSo5Pkg=="],
+
+    "tinyrainbow": ["tinyrainbow@1.2.0", "", {}, "sha512-weEDEq7Z5eTHPDh4xjX789+fHfF+P8boiFB+0vbWzpbnbsEr/GRaohi/uMKxg8RZMXnl1ItAi/IUHWMsjDV7kQ=="],
+
+    "tinyspy": ["tinyspy@3.0.2", "", {}, "sha512-n1cw8k1k0x4pgA2+9XrOkFydTerNcJ1zWCO5Nn9scWHTD+5tp8dghT2x1uduQePZTZgd3Tupf+x9BxJjeJi77Q=="],
+
+    "to-regex-range": ["to-regex-range@5.0.1", "", { "dependencies": { "is-number": "^7.0.0" } }, "sha512-65P7iz6X5yEr1cwcgvQxbbIw7Uk3gOy5dIdtZ4rDveLqhrdJP+Li/Hx6tyK0NEb+2GCyneCMJiGqrADCSNk8sQ=="],
+
+    "touch": ["touch@3.1.1", "", { "bin": { "nodetouch": "bin/nodetouch.js" } }, "sha512-r0eojU4bI8MnHr8c5bNo7lJDdI2qXlWWJk6a9EAFG7vbhTjElYhBVS3/miuE0uOuoLdb8Mc/rVfsmm6eo5o9GA=="],
+
+    "undefsafe": ["undefsafe@2.0.5", "", {}, "sha512-WxONCrssBM8TSPRqN5EmsjVrsv4A8X12J4ArBiiayv3DyyG3ZlIg6yysuuSYdZsVz3TKcTg2fd//Ujd4CHV1iA=="],
+
+    "undici": ["undici@7.13.0", "", {}, "sha512-l+zSMssRqrzDcb3fjMkjjLGmuiiK2pMIcV++mJaAc9vhjSGpvM7h43QgP+OAMb1GImHmbPyG2tBXeuyG5iY4gA=="],
+
+    "undici-types": ["undici-types@7.10.0", "", {}, "sha512-t5Fy/nfn+14LuOc2KNYg75vZqClpAiqscVvMygNnlsHBFpSXdJaYtXMcdNLpl/Qvc3P2cB3s6lOV51nqsFq4ag=="],
+
+    "uuid": ["uuid@11.1.0", "", { "bin": { "uuid": "dist/esm/bin/uuid" } }, "sha512-0/A9rDy9P7cJ+8w1c9WD9V//9Wj15Ce2MPz8Ri6032usz+NfePxx5AcN3bN+r6ZL6jEo066/yNYB3tn4pQEx+A=="],
+
+    "vite": ["vite@5.4.19", "", { "dependencies": { "esbuild": "^0.21.3", "postcss": "^8.4.43", "rollup": "^4.20.0" }, "optionalDependencies": { "fsevents": "~2.3.3" }, "peerDependencies": { "@types/node": "^18.0.0 || >=20.0.0", "less": "*", "lightningcss": "^1.21.0", "sass": "*", "sass-embedded": "*", "stylus": "*", "sugarss": "*", "terser": "^5.4.0" }, "optionalPeers": ["@types/node", "less", "lightningcss", "sass", "sass-embedded", "stylus", "sugarss", "terser"], "bin": { "vite": "bin/vite.js" } }, "sha512-qO3aKv3HoQC8QKiNSTuUM1l9o/XX3+c+VTgLHbJWHZGeTPVAg2XwazI9UWzoxjIJCGCV2zU60uqMzjeLZuULqA=="],
+
+    "vite-node": ["vite-node@2.1.9", "", { "dependencies": { "cac": "^6.7.14", "debug": "^4.3.7", "es-module-lexer": "^1.5.4", "pathe": "^1.1.2", "vite": "^5.0.0" }, "bin": { "vite-node": "vite-node.mjs" } }, "sha512-AM9aQ/IPrW/6ENLQg3AGY4K1N2TGZdR5e4gu/MmmR2xR3Ll1+dib+nook92g4TV3PXVyeyxdWwtaCAiUL0hMxA=="],
+
+    "vitest": ["vitest@2.1.9", "", { "dependencies": { "@vitest/expect": "2.1.9", "@vitest/mocker": "2.1.9", "@vitest/pretty-format": "^2.1.9", "@vitest/runner": "2.1.9", "@vitest/snapshot": "2.1.9", "@vitest/spy": "2.1.9", "@vitest/utils": "2.1.9", "chai": "^5.1.2", "debug": "^4.3.7", "expect-type": "^1.1.0", "magic-string": "^0.30.12", "pathe": "^1.1.2", "std-env": "^3.8.0", "tinybench": "^2.9.0", "tinyexec": "^0.3.1", "tinypool": "^1.0.1", "tinyrainbow": "^1.2.0", "vite": "^5.0.0", "vite-node": "2.1.9", "why-is-node-running": "^2.3.0" }, "peerDependencies": { "@edge-runtime/vm": "*", "@types/node": "^18.0.0 || >=20.0.0", "@vitest/browser": "2.1.9", "@vitest/ui": "2.1.9", "happy-dom": "*", "jsdom": "*" }, "optionalPeers": ["@edge-runtime/vm", "@types/node", "@vitest/browser", "@vitest/ui", "happy-dom", "jsdom"], "bin": { "vitest": "vitest.mjs" } }, "sha512-MSmPM9REYqDGBI8439mA4mWhV5sKmDlBKWIYbA3lRb2PTHACE0mgKwA8yQ2xq9vxDTuk4iPrECBAEW2aoFXY0Q=="],
+
+    "which": ["which@2.0.2", "", { "dependencies": { "isexe": "^2.0.0" }, "bin": { "node-which": "./bin/node-which" } }, "sha512-BLI3Tl1TW3Pvl70l3yq3Y64i+awpwXqsGBYWkkqMtnbXgrMD+yj7rhW0kuEDxzJaYXGjEW5ogapKNMEKNMjibA=="],
+
+    "why-is-node-running": ["why-is-node-running@2.3.0", "", { "dependencies": { "siginfo": "^2.0.0", "stackback": "0.0.2" }, "bin": { "why-is-node-running": "cli.js" } }, "sha512-hUrmaWBdVDcxvYqnyh09zunKzROWjbZTiNy8dBEjkS7ehEDQibXJ7XvlmtbwuTclUiIyN+CyXQD4Vmko8fNm8w=="],
+
+    "wrappy": ["wrappy@1.0.2", "", {}, "sha512-l4Sp/DRseor9wL6EvV2+TuQn63dMkPjZ/sp9XkghTEbV9KlPS1xUsZ3u7/IQO4wxtcFB4bgpQPRcR3QCvezPcQ=="],
+
+    "ws": ["ws@8.18.3", "", { "peerDependencies": { "bufferutil": "^4.0.1", "utf-8-validate": ">=5.0.2" }, "optionalPeers": ["bufferutil", "utf-8-validate"] }, "sha512-PEIGCY5tSlUt50cqyMXfCzX+oOPqN0vuGqWzbcJ2xvnkzkq46oOpz7dQaTDBdfICb4N14+GARUDw2XV2N4tvzg=="],
+
+    "yauzl": ["yauzl@2.10.0", "", { "dependencies": { "buffer-crc32": "~0.2.3", "fd-slicer": "~1.1.0" } }, "sha512-p4a9I6X6nu6IhoGmBqAcbJy1mlC4j27vEPZX9F4L4/vZT3Lyq1VkFHw/V/PUcB9Buo+DG3iHkT0x3Qya58zc3g=="],
+
+    "basic-auth/safe-buffer": ["safe-buffer@5.1.2", "", {}, "sha512-Gd2UZBJDkXlY7GbJxfsE8/nvKkUEU1G38c1siN6QP6a9PT9MmHB8GnpscSmMJSoF8LOIrt8ud/wPtojys4G6+g=="],
+
+    "morgan/debug": ["debug@2.6.9", "", { "dependencies": { "ms": "2.0.0" } }, "sha512-bC7ElrdJaJnPbAP+1EotYvqZsb3ecl5wi6Bfi6BJTUcNowp6cvspg0jXznRTKDjm/E7AdgFBVeAPVMNcKGsHMA=="],
+
+    "postcss/nanoid": ["nanoid@3.3.11", "", { "bin": { "nanoid": "bin/nanoid.cjs" } }, "sha512-N8SpfPUnUp1bK+PMYW8qSWdl9U+wwNWI4QKxOYDy9JAro3WMX7p2OeVRF9v+347pnakNevPmiHhNmZ2HbFA76w=="],
+
+    "morgan/debug/ms": ["ms@2.0.0", "", {}, "sha512-Tpp60P6IUJDTuOq/5Z8cdskzJujfwqfOTkrwIwj7IRISpnkJnT6SyJ4PCPnGMoFjC9ddhal5KVIYtAt97ix05A=="],
+  }
+}
diff --git a/operator-api/index.js b/operator-api/index.js
new file mode 100644
index 00000000..fb1ec730
--- /dev/null
+++ b/operator-api/index.js
@@ -0,0 +1,37 @@
+import 'dotenv/config'
+import { serve } from '@hono/node-server'
+import { Hono } from 'hono'
+import { cors } from 'hono/cors'
+import morgan from 'morgan'
+import { app as api } from './src/app.js'
+
+
+console.log('🔧 [kernel:operator-api:debug] process.env 🔧')
+console.log('┌─────────────────────────────────────────────────────')
+Object.keys(process.env)
+  .sort()
+  .forEach(key => {
+    console.log(`│ ${key.padEnd(25)} │ ${process.env[key]}`)
+  })
+console.log('└─────────────────────────────────────────────────────')
+
+const port = Number(process.env.PORT || 10001)
+
+const root = new Hono()
+root.use('*', cors())
+root.use('*', async (c, next) => {
+  // minimal morgan-like logging
+  const start = Date.now()
+  await next()
+  const ms = Date.now() - start
+  console.log(`${c.req.method} ${c.req.path} -> ${c.res.status} ${ms}ms`)
+})
+
+root.route('/', api)
+
+serve({
+  fetch: root.fetch,
+  port
+})
+
+console.log(`Kernel Computer Operator API listening on :${port}`)
diff --git a/operator-api/openapi.yaml b/operator-api/openapi.yaml
new file mode 100644
index 00000000..d8de4741
--- /dev/null
+++ b/operator-api/openapi.yaml
@@ -0,0 +1,2844 @@
+openapi: 3.1.0
+info:
+  title: Kernel Images API
+  version: 0.1.0
+paths:
+  # -------------------------
+  # PREVIOUS, UNCHANGED PATHS
+  # -------------------------
+  /recording/start:
+    post:
+      summary: Start a screen recording. Only one recording per ID can be registered at a time.
+      operationId: startRecording
+      requestBody:
+        required: false
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/StartRecordingRequest"
+      responses:
+        "201":
+          description: Recording started
+        "400":
+          $ref: "#/components/responses/BadRequestError"
+        "409":
+          description: A recording is already in progress
+          $ref: "#/components/responses/ConflictError"
+        "500":
+          $ref: "#/components/responses/InternalError"
+  /recording/stop:
+    post:
+      summary: Stop the recording
+      operationId: stopRecording
+      requestBody:
+        required: false
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/StopRecordingRequest"
+      responses:
+        "200":
+          description: Recording stopped
+        "400":
+          $ref: "#/components/responses/BadRequestError"
+        "500":
+          $ref: "#/components/responses/InternalError"
+  /recording/download:
+    get:
+      summary: Download the most recently recorded video file
+      parameters:
+        - name: id
+          in: query
+          description: Optional recorder identifier. When omitted, the server uses the default recorder.
+          schema:
+            type: string
+            pattern: "^[a-zA-Z0-9-]+$"
+      operationId: downloadRecording
+      responses:
+        "200":
+          description: Recording file
+          headers:
+            X-Recording-Started-At:
+              description: Timestamp of when the recording started. Guaranteed to be RFC3339.
+              schema:
+                type: string
+            X-Recording-Finished-At:
+              description: Timestamp of when the recording finished. Guaranteed to be RFC3339.
+              schema:
+                type: string
+          content:
+            video/mp4:
+              schema:
+                type: string
+                format: binary
+        "202":
+          description: Recording is still in progress, please try again later
+          headers:
+            Retry-After:
+              description: Suggested wait time in seconds before retrying
+              schema:
+                type: integer
+                minimum: 1
+        "400":
+          $ref: "#/components/responses/BadRequestError"
+        "404":
+          $ref: "#/components/responses/NotFoundError"
+        "500":
+          $ref: "#/components/responses/InternalError"
+  /recording/list:
+    get:
+      summary: List all recorders
+      operationId: listRecorders
+      responses:
+        "200":
+          description: List of recorders
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: "#/components/schemas/RecorderInfo"
+        "500":
+          $ref: "#/components/responses/InternalError"
+  /recording/delete:
+    post:
+      summary: Delete a previously recorded video file
+      operationId: deleteRecording
+      requestBody:
+        required: false
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/DeleteRecordingRequest"
+      responses:
+        "200":
+          description: Recording deleted
+        "400":
+          $ref: "#/components/responses/BadRequestError"
+        "404":
+          $ref: "#/components/responses/NotFoundError"
+        "500":
+          $ref: "#/components/responses/InternalError"
+  /fs/read_file:
+    get:
+      summary: Read file contents
+      operationId: readFile
+      parameters:
+        - name: path
+          in: query
+          required: true
+          schema:
+            type: string
+            pattern: "^/.*"
+          description: Absolute file path to read.
+      responses:
+        "200":
+          description: File read successfully
+          content:
+            application/octet-stream:
+              schema:
+                type: string
+                format: binary
+        "400":
+          $ref: "#/components/responses/BadRequestError"
+        "404":
+          $ref: "#/components/responses/NotFoundError"
+        "500":
+          $ref: "#/components/responses/InternalError"
+  /fs/write_file:
+    put:
+      summary: Write or create a file
+      operationId: writeFile
+      parameters:
+        - name: path
+          in: query
+          required: true
+          schema:
+            type: string
+            pattern: "^/.*"
+          description: Destination absolute file path.
+        - name: mode
+          in: query
+          required: false
+          schema:
+            type: string
+            pattern: "^[0-7]{3,4}$"
+          description: Optional file mode (octal string, e.g. 644). Defaults to 644.
+      requestBody:
+        required: true
+        content:
+          application/octet-stream:
+            schema:
+              type: string
+              format: binary
+      responses:
+        "201":
+          description: File written successfully
+        "400":
+          $ref: "#/components/responses/BadRequestError"
+        "404":
+          $ref: "#/components/responses/NotFoundError"
+        "500":
+          $ref: "#/components/responses/InternalError"
+  /fs/list_files:
+    get:
+      summary: List files in a directory
+      operationId: listFiles
+      parameters:
+        - name: path
+          in: query
+          required: true
+          schema:
+            type: string
+            pattern: "^/.*"
+          description: Absolute directory path.
+      responses:
+        "200":
+          description: Directory listing
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ListFiles"
+        "400":
+          $ref: "#/components/responses/BadRequestError"
+        "404":
+          $ref: "#/components/responses/NotFoundError"
+        "500":
+          $ref: "#/components/responses/InternalError"
+  /fs/create_directory:
+    put:
+      summary: Create a new directory
+      operationId: createDirectory
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/CreateDirectoryRequest"
+      responses:
+        "201":
+          description: Directory created successfully
+        "400":
+          $ref: "#/components/responses/BadRequestError"
+        "500":
+          $ref: "#/components/responses/InternalError"
+  /fs/delete_file:
+    put:
+      summary: Delete a file
+      operationId: deleteFile
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/DeletePathRequest"
+      responses:
+        "200":
+          description: File deleted
+        "400":
+          $ref: "#/components/responses/BadRequestError"
+        "404":
+          $ref: "#/components/responses/NotFoundError"
+        "500":
+          $ref: "#/components/responses/InternalError"
+  /fs/delete_directory:
+    put:
+      summary: Delete a directory
+      operationId: deleteDirectory
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/DeletePathRequest"
+      responses:
+        "200":
+          description: Directory deleted
+        "400":
+          $ref: "#/components/responses/BadRequestError"
+        "404":
+          $ref: "#/components/responses/NotFoundError"
+        "500":
+          $ref: "#/components/responses/InternalError"
+  /fs/set_file_permissions:
+    put:
+      summary: Set file or directory permissions/ownership
+      operationId: setFilePermissions
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/SetFilePermissionsRequest"
+      responses:
+        "200":
+          description: Permissions updated
+        "400":
+          $ref: "#/components/responses/BadRequestError"
+        "404":
+          $ref: "#/components/responses/NotFoundError"
+        "500":
+          $ref: "#/components/responses/InternalError"
+  /fs/file_info:
+    get:
+      summary: Get information about a file or directory
+      operationId: fileInfo
+      parameters:
+        - name: path
+          in: query
+          required: true
+          schema:
+            type: string
+            pattern: "^/.*"
+          description: Absolute path of the file or directory.
+      responses:
+        "200":
+          description: File information
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/FileInfo"
+        "400":
+          $ref: "#/components/responses/BadRequestError"
+        "404":
+          $ref: "#/components/responses/NotFoundError"
+        "500":
+          $ref: "#/components/responses/InternalError"
+  /fs/move:
+    put:
+      summary: Move or rename a file or directory
+      operationId: movePath
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/MovePathRequest"
+      responses:
+        "200":
+          description: Move successful
+        "400":
+          $ref: "#/components/responses/BadRequestError"
+        "404":
+          $ref: "#/components/responses/NotFoundError"
+        "500":
+          $ref: "#/components/responses/InternalError"
+  /fs/watch:
+    post:
+      summary: Watch a directory for changes
+      operationId: startFsWatch
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/StartFsWatchRequest"
+      responses:
+        "201":
+          description: Watch started successfully
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  watch_id:
+                    type: string
+                    description: Unique identifier for the directory watch
+        "400":
+          $ref: "#/components/responses/BadRequestError"
+        "404":
+          $ref: "#/components/responses/NotFoundError"
+        "500":
+          $ref: "#/components/responses/InternalError"
+  /fs/watch/{watch_id}/events:
+    get:
+      summary: Stream filesystem events for a watch
+      operationId: streamFsEvents
+      parameters:
+        - name: watch_id
+          in: path
+          required: true
+          schema:
+            type: string
+      responses:
+        "200":
+          description: SSE stream of filesystem events
+          headers:
+            X-SSE-Content-Type:
+              description: Media type of SSE data events (application/json)
+              schema:
+                type: string
+                const: application/json
+          content:
+            text/event-stream:
+              schema:
+                $ref: "#/components/schemas/FileSystemEvent"
+        "400":
+          $ref: "#/components/responses/BadRequestError"
+        "404":
+          $ref: "#/components/responses/NotFoundError"
+        "500":
+          $ref: "#/components/responses/InternalError"
+  /fs/watch/{watch_id}:
+    delete:
+      summary: Stop watching a directory
+      operationId: stopFsWatch
+      parameters:
+        - name: watch_id
+          in: path
+          required: true
+          schema:
+            type: string
+      responses:
+        "204":
+          description: Watch stopped successfully
+        "400":
+          $ref: "#/components/responses/BadRequestError"
+        "404":
+          $ref: "#/components/responses/NotFoundError"
+        "500":
+          $ref: "#/components/responses/InternalError"
+
+  # --------------------------------
+  # COMPAT ALIASES FOR XDOTool START
+  # --------------------------------
+  /computer/click_mouse:
+    post:
+      summary: Click mouse (compat)
+      operationId: computerClickMouse
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/ClickMouseRequest"
+            examples:
+              default:
+                value: { button: left, click_type: click, x: 640, y: 360, num_clicks: 1 }
+      responses:
+        "200":
+          description: Clicked
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/OkResponse"
+        "400":
+          $ref: "#/components/responses/BadRequestError"
+        "500":
+          $ref: "#/components/responses/InternalError"
+  /computer/move_mouse:
+    post:
+      summary: Move mouse (compat)
+      operationId: computerMoveMouse
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/MoveMouseRequest"
+            examples:
+              default:
+                value: { x: 800, y: 450 }
+      responses:
+        "200":
+          description: Moved
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/OkResponse"
+        "400":
+          $ref: "#/components/responses/BadRequestError"
+        "500":
+          $ref: "#/components/responses/InternalError"
+
+  # -------------------------
+  # NEW ENDPOINTS (ADDITIVE)
+  # -------------------------
+  /screenshot/capture:
+    post:
+      summary: Capture a still image of the desktop
+      operationId: captureScreenshot
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/ScreenshotCaptureRequest"
+            examples:
+              default:
+                value:
+                  region: { x: 0, y: 0, width: 1280, height: 720 }
+                  include_cursor: false
+                  display: 0
+                  format: png
+      responses:
+        "200":
+          description: Screenshot captured
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ScreenshotCaptureResponse"
+        "400":
+          $ref: "#/components/responses/BadRequestError"
+        "500":
+          $ref: "#/components/responses/InternalError"
+  /screenshot/{screenshot_id}:
+    get:
+      summary: Retrieve captured screenshot by ID
+      operationId: getScreenshot
+      parameters:
+        - in: path
+          name: screenshot_id
+          required: true
+          schema: { type: string, format: uuid }
+      responses:
+        "200":
+          description: Image bytes
+          content:
+            image/png:
+              schema: { type: string, format: binary }
+            image/jpeg:
+              schema: { type: string, format: binary }
+        "404":
+          $ref: "#/components/responses/NotFoundError"
+
+  /stream/start:
+    post:
+      summary: Start an RTMPS live stream from the desktop
+      operationId: startStream
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/StreamStartRequest"
+            examples:
+              default:
+                value:
+                  region: null
+                  display: 0
+                  fps: 30
+                  video_codec: h264
+                  video_bitrate_kbps: 3500
+                  audio: { capture_system: true, capture_mic: false }
+                  rtmps_url: "rtmps://live.example.com/app"
+                  stream_key: "secret_key"
+      responses:
+        "200":
+          description: Stream starting
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/StreamStartResponse"
+        "400":
+          $ref: "#/components/responses/BadRequestError"
+        "500":
+          $ref: "#/components/responses/InternalError"
+  /stream/stop:
+    post:
+      summary: Stop an RTMPS stream
+      operationId: stopStream
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/StreamStopRequest"
+      responses:
+        "200":
+          description: Stream stopped
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/StreamStopResponse"
+        "404":
+          $ref: "#/components/responses/NotFoundError"
+  /stream/{stream_id}/metrics/stream:
+    get:
+      summary: SSE of stream metrics
+      operationId: streamStreamMetrics
+      parameters:
+        - in: path
+          name: stream_id
+          required: true
+          schema: { type: string, format: uuid }
+      responses:
+        "200":
+          description: text/event-stream of metrics
+          headers:
+            X-SSE-Content-Type:
+              description: Media type of SSE data events (application/json)
+              schema:
+                type: string
+                const: application/json
+          content:
+            text/event-stream:
+              examples:
+                default:
+                  value: |
+                    event: data
+                    data: {"ts":"2025-08-09T10:00:00Z","fps":29.9,"bitrate_kbps":3400,"dropped_frames":2}
+              schema:
+                type: string
+        "404":
+          $ref: "#/components/responses/NotFoundError"
+
+  /input/mouse/move:
+    post:
+      summary: Move mouse cursor
+      operationId: inputMouseMove
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: { $ref: "#/components/schemas/MouseMoveRequest" }
+      responses:
+        "200":
+          description: OK
+          content:
+            application/json:
+              schema: { $ref: "#/components/schemas/OkResponse" }
+        "400":
+          $ref: "#/components/responses/BadRequestError"
+  /input/mouse/click:
+    post:
+      summary: Click mouse button
+      operationId: inputMouseClick
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: { $ref: "#/components/schemas/MouseClickRequest" }
+            examples:
+              default:
+                value: { button: left, count: 1 }
+      responses:
+        "200":
+          description: OK
+          content:
+            application/json:
+              schema: { $ref: "#/components/schemas/OkResponse" }
+        "400":
+          $ref: "#/components/responses/BadRequestError"
+  /input/mouse/scroll:
+    post:
+      summary: Scroll mouse wheel
+      operationId: inputMouseScroll
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: { $ref: "#/components/schemas/MouseScrollRequest" }
+      responses:
+        "200":
+          description: OK
+          content:
+            application/json:
+              schema: { $ref: "#/components/schemas/OkResponse" }
+        "400":
+          $ref: "#/components/responses/BadRequestError"
+
+  /input/keyboard/type:
+    post:
+      summary: Type text (IME-aware)
+      operationId: inputKeyboardType
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: { $ref: "#/components/schemas/KeyboardTypeRequest" }
+      responses:
+        "200":
+          description: OK
+          content:
+            application/json:
+              schema: { $ref: "#/components/schemas/OkResponse" }
+        "400":
+          $ref: "#/components/responses/BadRequestError"
+  /input/keyboard/key_down:
+    post:
+      summary: Key down
+      operationId: inputKeyDown
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: { $ref: "#/components/schemas/KeyRequest" }
+      responses:
+        "200":
+          description: OK
+          content:
+            application/json:
+              schema: { $ref: "#/components/schemas/OkResponse" }
+        "400":
+          $ref: "#/components/responses/BadRequestError"
+  /input/keyboard/key_up:
+    post:
+      summary: Key up
+      operationId: inputKeyUp
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: { $ref: "#/components/schemas/KeyRequest" }
+      responses:
+        "200":
+          description: OK
+          content:
+            application/json:
+              schema: { $ref: "#/components/schemas/OkResponse" }
+        "400":
+          $ref: "#/components/responses/BadRequestError"
+
+  /input/window/activate:
+    post:
+      summary: Activate window by match
+      operationId: inputWindowActivate
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: { $ref: "#/components/schemas/WindowActivateRequest" }
+      responses:
+        "200":
+          description: Activated
+          content:
+            application/json:
+              schema: { $ref: "#/components/schemas/WindowActivateResponse" }
+        "400":
+          $ref: "#/components/responses/BadRequestError"
+  /input/window/move_resize:
+    post:
+      summary: Move and resize window
+      operationId: inputWindowMoveResize
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: { $ref: "#/components/schemas/WindowMoveResizeRequest" }
+      responses:
+        "200":
+          description: OK
+          content:
+            application/json:
+              schema: { $ref: "#/components/schemas/OkResponse" }
+        "400":
+          $ref: "#/components/responses/BadRequestError"
+  /input/window/close:
+    post:
+      summary: Close window by match
+      operationId: inputWindowClose
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: { $ref: "#/components/schemas/WindowCloseRequest" }
+      responses:
+        "200":
+          description: OK
+          content:
+            application/json:
+              schema: { $ref: "#/components/schemas/OkResponse" }
+        "400":
+          $ref: "#/components/responses/BadRequestError"
+
+  /input/mouse/move_relative:
+    post:
+      summary: Move mouse cursor relative
+      operationId: inputMouseMoveRelative
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: { $ref: "#/components/schemas/MouseMoveRelativeRequest" }
+      responses:
+        "200":
+          description: OK
+          content:
+            application/json:
+              schema: { $ref: "#/components/schemas/OkResponse" }
+        "400":
+          $ref: "#/components/responses/BadRequestError"
+
+  /input/mouse/down:
+    post:
+      summary: Mouse button down
+      operationId: inputMouseDown
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: { $ref: "#/components/schemas/MouseButtonRequest" }
+      responses:
+        "200": { description: OK, content: { application/json: { schema: { $ref: "#/components/schemas/OkResponse" } } } }
+        "400": { $ref: "#/components/responses/BadRequestError" }
+
+  /input/mouse/up:
+    post:
+      summary: Mouse button up
+      operationId: inputMouseUp
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: { $ref: "#/components/schemas/MouseButtonRequest" }
+      responses:
+        "200": { description: OK, content: { application/json: { schema: { $ref: "#/components/schemas/OkResponse" } } } }
+        "400": { $ref: "#/components/responses/BadRequestError" }
+
+  /input/mouse/location:
+    get:
+      summary: Get mouse location
+      operationId: inputMouseLocation
+      responses:
+        "200":
+          description: Location
+          content:
+            application/json:
+              schema: { $ref: "#/components/schemas/MouseLocationResponse" }
+
+  /input/keyboard/key:
+    post:
+      summary: Send one or more key strokes
+      operationId: inputKeyboardKey
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: { $ref: "#/components/schemas/KeyboardKeysRequest" }
+      responses:
+        "200": { description: OK, content: { application/json: { schema: { $ref: "#/components/schemas/OkResponse" } } } }
+        "400": { $ref: "#/components/responses/BadRequestError" }
+
+  /input/window/focus:
+    post:
+      summary: Focus window by match
+      operationId: inputWindowFocus
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: { $ref: "#/components/schemas/WindowActivateRequest" }
+      responses:
+        "200":
+          description: Focused
+          content:
+            application/json:
+              schema: { $ref: "#/components/schemas/WindowFocusResponse" }
+        "400": { $ref: "#/components/responses/BadRequestError" }
+
+  /input/window/raise:
+    post:
+      summary: Raise window
+      operationId: inputWindowRaise
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: { $ref: "#/components/schemas/WindowActivateRequest" }
+      responses:
+        "200": { description: OK, content: { application/json: { schema: { $ref: "#/components/schemas/OkResponse" } } } }
+
+  /input/window/minimize:
+    post:
+      summary: Minimize window
+      operationId: inputWindowMinimize
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: { $ref: "#/components/schemas/WindowActivateRequest" }
+      responses:
+        "200": { description: OK, content: { application/json: { schema: { $ref: "#/components/schemas/OkResponse" } } } }
+
+  /input/window/map:
+    post:
+      summary: Map (show) window
+      operationId: inputWindowMap
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: { $ref: "#/components/schemas/WindowActivateRequest" }
+      responses:
+        "200": { description: OK, content: { application/json: { schema: { $ref: "#/components/schemas/OkResponse" } } } }
+
+  /input/window/unmap:
+    post:
+      summary: Unmap (hide) window
+      operationId: inputWindowUnmap
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: { $ref: "#/components/schemas/WindowActivateRequest" }
+      responses:
+        "200": { description: OK, content: { application/json: { schema: { $ref: "#/components/schemas/OkResponse" } } } }
+
+  /input/window/kill:
+    post:
+      summary: Kill window
+      operationId: inputWindowKill
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: { $ref: "#/components/schemas/WindowActivateRequest" }
+      responses:
+        "200": { description: OK, content: { application/json: { schema: { $ref: "#/components/schemas/OkResponse" } } } }
+
+  /input/window/active:
+    get:
+      summary: Get active window
+      operationId: inputWindowActive
+      responses:
+        "200": { description: Active, content: { application/json: { schema: { $ref: "#/components/schemas/ActiveWindowResponse" } } } }
+
+  /input/window/focused:
+    get:
+      summary: Get focused window
+      operationId: inputWindowFocused
+      responses:
+        "200": { description: Focused, content: { application/json: { schema: { $ref: "#/components/schemas/ActiveWindowResponse" } } } }
+
+  /input/window/name:
+    post:
+      summary: Get window name
+      operationId: inputWindowName
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: { $ref: "#/components/schemas/WindowIdRequest" }
+      responses:
+        "200": { description: Name, content: { application/json: { schema: { $ref: "#/components/schemas/WindowNameResponse" } } } }
+
+  /input/window/pid:
+    post:
+      summary: Get window pid
+      operationId: inputWindowPid
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: { $ref: "#/components/schemas/WindowIdRequest" }
+      responses:
+        "200": { description: PID, content: { application/json: { schema: { $ref: "#/components/schemas/WindowPidResponse" } } } }
+
+  /input/window/geometry:
+    post:
+      summary: Get window geometry
+      operationId: inputWindowGeometry
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: { $ref: "#/components/schemas/WindowIdRequest" }
+      responses:
+        "200": { description: Geometry, content: { application/json: { schema: { $ref: "#/components/schemas/WindowGeometryResponse" } } } }
+
+  /input/display/geometry:
+    get:
+      summary: Get display geometry
+      operationId: inputDisplayGeometry
+      responses:
+        "200": { description: Geometry, content: { application/json: { schema: { $ref: "#/components/schemas/DisplayGeometryResponse" } } } }
+
+  /input/desktop/count:
+    get:
+      summary: Get number of desktops
+      operationId: inputDesktopCountGet
+      responses:
+        "200": { description: Count, content: { application/json: { schema: { $ref: "#/components/schemas/DesktopCountResponse" } } } }
+    post:
+      summary: Set number of desktops
+      operationId: inputDesktopCountSet
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: { $ref: "#/components/schemas/DesktopCountRequest" }
+      responses:
+        "200": { description: OK, content: { application/json: { schema: { $ref: "#/components/schemas/OkResponse" } } } }
+
+  /input/desktop/current:
+    get:
+      summary: Get current desktop index
+      operationId: inputDesktopCurrentGet
+      responses:
+        "200": { description: Index, content: { application/json: { schema: { $ref: "#/components/schemas/DesktopIndexResponse" } } } }
+    post:
+      summary: Set current desktop index
+      operationId: inputDesktopCurrentSet
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: { $ref: "#/components/schemas/DesktopIndexRequest" }
+      responses:
+        "200": { description: OK, content: { application/json: { schema: { $ref: "#/components/schemas/OkResponse" } } } }
+
+  /input/desktop/window_desktop:
+    post:
+      summary: Move window to desktop
+      operationId: inputDesktopWindowDesktop
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: { $ref: "#/components/schemas/WindowDesktopRequest" }
+      responses:
+        "200": { description: OK, content: { application/json: { schema: { $ref: "#/components/schemas/OkResponse" } } } }
+
+  /input/desktop/viewport:
+    get:
+      summary: Get desktop viewport
+      operationId: inputDesktopViewportGet
+      responses:
+        "200": { description: Viewport, content: { application/json: { schema: { $ref: "#/components/schemas/DesktopViewportResponse" } } } }
+    post:
+      summary: Set desktop viewport
+      operationId: inputDesktopViewportSet
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: { $ref: "#/components/schemas/DesktopViewportRequest" }
+      responses:
+        "200": { description: OK, content: { application/json: { schema: { $ref: "#/components/schemas/OkResponse" } } } }
+
+  /input/combo/activate_and_type:
+    post:
+      summary: Activate a window then type
+      operationId: comboActivateAndType
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: { $ref: "#/components/schemas/ActivateAndTypeRequest" }
+      responses:
+        "200": { description: OK, content: { application/json: { schema: { $ref: "#/components/schemas/ComboWindowResponse" } } } }
+
+  /input/combo/activate_and_keys:
+    post:
+      summary: Activate a window then send key sequence
+      operationId: comboActivateAndKeys
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: { $ref: "#/components/schemas/ActivateAndKeysRequest" }
+      responses:
+        "200": { description: OK, content: { application/json: { schema: { $ref: "#/components/schemas/ComboWindowResponse" } } } }
+
+  /input/combo/window/center:
+    post:
+      summary: Center and optionally size a window
+      operationId: comboWindowCenter
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: { $ref: "#/components/schemas/WindowCenterRequest" }
+      responses:
+        "200": { description: OK, content: { application/json: { schema: { $ref: "#/components/schemas/WindowCenterResponse" } } } }
+
+  /input/combo/window/snap:
+    post:
+      summary: Snap window to position
+      operationId: comboWindowSnap
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: { $ref: "#/components/schemas/WindowSnapRequest" }
+      responses:
+        "200": { description: OK, content: { application/json: { schema: { $ref: "#/components/schemas/WindowSnapResponse" } } } }
+
+  /input/system/exec:
+    post:
+      summary: Run a system command via xdotool wrapper
+      operationId: inputSystemExec
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: { $ref: "#/components/schemas/SystemExecRequest" }
+      responses:
+        "200":
+          description: Result
+          content:
+            application/json:
+              schema: { $ref: "#/components/schemas/SystemExecResponse" }
+        "400": { $ref: "#/components/responses/BadRequestError" }
+
+  /input/system/sleep:
+    post:
+      summary: Sleep via xdotool
+      operationId: inputSystemSleep
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: { $ref: "#/components/schemas/SleepRequest" }
+      responses:
+        "200": { description: OK, content: { application/json: { schema: { $ref: "#/components/schemas/OkResponse" } } } }
+        "400": { $ref: "#/components/responses/BadRequestError" }
+
+
+
+  /fs/upload:
+    post:
+      summary: Upload a file into the VM
+      operationId: fsUpload
+      requestBody:
+        required: true
+        content:
+          multipart/form-data:
+            schema:
+              type: object
+              required: [path, file]
+              properties:
+                path: { type: string, description: Destination absolute path }
+                file: { type: string, format: binary }
+      responses:
+        "200":
+          description: Uploaded
+          content:
+            application/json:
+              schema: { $ref: "#/components/schemas/UploadResponse" }
+        "400":
+          $ref: "#/components/responses/BadRequestError"
+  /fs/download:
+    get:
+      summary: Download a file from the VM
+      operationId: fsDownload
+      parameters:
+        - in: query
+          name: path
+          required: true
+          schema: { type: string }
+      responses:
+        "200":
+          description: File bytes
+          content:
+            application/octet-stream:
+              schema: { type: string, format: binary }
+        "404":
+          $ref: "#/components/responses/NotFoundError"
+  /fs/tail/stream:
+    get:
+      summary: Tail-follow a file as SSE
+      operationId: fsTailStream
+      parameters:
+        - in: query
+          name: path
+          required: true
+          schema: { type: string }
+      responses:
+        "200":
+          description: text/event-stream of lines
+          headers:
+            X-SSE-Content-Type:
+              description: Media type of SSE data events (application/json)
+              schema:
+                type: string
+                const: application/json
+          content:
+            text/event-stream:
+              schema:
+                type: string
+                example: |
+                  event: data
+                  data: {"line":"hello","ts":"2025-08-09T10:00:00Z"}
+        "404":
+          $ref: "#/components/responses/NotFoundError"
+
+  /process/exec:
+    post:
+      summary: Execute a command synchronously (optional streaming)
+      operationId: processExec
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: { $ref: "#/components/schemas/ProcessExecRequest" }
+      responses:
+        "200":
+          description: Execution result
+          content:
+            application/json:
+              schema: { $ref: "#/components/schemas/ProcessExecResponse" }
+        "400":
+          $ref: "#/components/responses/BadRequestError"
+  /process/spawn:
+    post:
+      summary: Execute a command asynchronously
+      operationId: processSpawn
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: { $ref: "#/components/schemas/ProcessSpawnRequest" }
+      responses:
+        "200":
+          description: Spawned
+          content:
+            application/json:
+              schema: { $ref: "#/components/schemas/ProcessSpawnResponse" }
+        "400":
+          $ref: "#/components/responses/BadRequestError"
+  /process/{process_id}/status:
+    get:
+      summary: Get process status
+      operationId: processStatus
+      parameters:
+        - in: path
+          name: process_id
+          required: true
+          schema: { type: string, format: uuid }
+      responses:
+        "200":
+          description: Status
+          content:
+            application/json:
+              schema: { $ref: "#/components/schemas/ProcessStatusResponse" }
+        "404":
+          $ref: "#/components/responses/NotFoundError"
+  /process/{process_id}/stdout/stream:
+    get:
+      summary: Stream process stdout/stderr (SSE)
+      operationId: processStdoutStream
+      parameters:
+        - in: path
+          name: process_id
+          required: true
+          schema: { type: string, format: uuid }
+      responses:
+        "200":
+          description: text/event-stream of stdout/stderr
+          headers:
+            X-SSE-Content-Type:
+              description: Media type of SSE data events (application/json)
+              schema:
+                type: string
+                const: application/json
+          content:
+            text/event-stream:
+              schema:
+                type: string
+                example: |
+                  event: data
+                  data: {"stream":"stdout","data_b64":"SGVsbG8K"}
+                  event: data
+                  data: {"event":"exit","exit_code":0}
+        "404":
+          $ref: "#/components/responses/NotFoundError"
+  /process/{process_id}/stdin:
+    post:
+      summary: Write to process stdin
+      operationId: processStdin
+      parameters:
+        - in: path
+          name: process_id
+          required: true
+          schema: { type: string, format: uuid }
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: { $ref: "#/components/schemas/ProcessStdinRequest" }
+      responses:
+        "200":
+          description: Bytes written
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  written_bytes: { type: integer }
+        "404":
+          $ref: "#/components/responses/NotFoundError"
+  /process/{process_id}/kill:
+    post:
+      summary: Send signal to process
+      operationId: processKill
+      parameters:
+        - in: path
+          name: process_id
+          required: true
+          schema: { type: string, format: uuid }
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: { $ref: "#/components/schemas/ProcessKillRequest" }
+      responses:
+        "200":
+          description: OK
+          content:
+            application/json:
+              schema: { $ref: "#/components/schemas/OkResponse" }
+        "404":
+          $ref: "#/components/responses/NotFoundError"
+
+  /network/proxy/socks5/start:
+    post:
+      summary: Start a lightweight SOCKS5 proxy in the VM
+      operationId: networkSocksStart
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: { $ref: "#/components/schemas/Socks5StartRequest" }
+      responses:
+        "200":
+          description: Proxy started
+          content:
+            application/json:
+              schema: { $ref: "#/components/schemas/Socks5StartResponse" }
+        "400":
+          $ref: "#/components/responses/BadRequestError"
+  /network/proxy/socks5/stop:
+    post:
+      summary: Stop a SOCKS5 proxy
+      operationId: networkSocksStop
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: { $ref: "#/components/schemas/Socks5StopRequest" }
+      responses:
+        "200":
+          description: OK
+          content:
+            application/json:
+              schema: { $ref: "#/components/schemas/OkResponse" }
+        "404":
+          $ref: "#/components/responses/NotFoundError"
+
+  /network/intercept/rules:
+    post:
+      summary: Apply realtime network intercept rules
+      operationId: networkInterceptApply
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: { $ref: "#/components/schemas/NetworkInterceptRulesRequest" }
+      responses:
+        "200":
+          description: Rule set applied
+          content:
+            application/json:
+              schema: { $ref: "#/components/schemas/NetworkInterceptRulesResponse" }
+        "400":
+          $ref: "#/components/responses/BadRequestError"
+  /network/intercept/rules/{rule_set_id}:
+    delete:
+      summary: Remove intercept rule set
+      operationId: networkInterceptDelete
+      parameters:
+        - in: path
+          name: rule_set_id
+          required: true
+          schema: { type: string, format: uuid }
+      responses:
+        "200":
+          description: OK
+          content:
+            application/json:
+              schema: { $ref: "#/components/schemas/OkResponse" }
+        "404":
+          $ref: "#/components/responses/NotFoundError"
+
+  /network/har/stream:
+    get:
+      summary: Stream HAR entries from proxy/browser (SSE)
+      operationId: networkHarStream
+      responses:
+        "200":
+          description: text/event-stream of HAR entries
+          headers:
+            X-SSE-Content-Type:
+              description: Media type of SSE data events (application/json)
+              schema:
+                type: string
+                const: application/json
+          content:
+            text/event-stream:
+              schema:
+                type: string
+                example: |
+                  event: data
+                  data: {"ts":"2025-08-09T10:00:00Z","entry":{"request":{"method":"GET","url":"https://..."},"response":{"status":200}}}
+  /network/forward:
+    post:
+      summary: Configure port forwarding host↔VM
+      operationId: networkForward
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: { $ref: "#/components/schemas/ForwardRequest" }
+      responses:
+        "200":
+          description: Forward active
+          content:
+            application/json:
+              schema: { $ref: "#/components/schemas/ForwardResponse" }
+        "400":
+          $ref: "#/components/responses/BadRequestError"
+  /network/forward/{forward_id}:
+    delete:
+      summary: Remove a port forward
+      operationId: networkForwardDelete
+      parameters:
+        - in: path
+          name: forward_id
+          required: true
+          schema: { type: string, format: uuid }
+      responses:
+        "200":
+          description: OK
+          content:
+            application/json:
+              schema: { $ref: "#/components/schemas/OkResponse" }
+        "404":
+          $ref: "#/components/responses/NotFoundError"
+
+  /bus/publish:
+    post:
+      summary: Publish a message to in-VM agent subscribers
+      operationId: busPublish
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: { $ref: "#/components/schemas/BusPublishRequest" }
+      responses:
+        "200":
+          description: Delivered
+          content:
+            application/json:
+              schema: { $ref: "#/components/schemas/BusPublishResponse" }
+        "400":
+          $ref: "#/components/responses/BadRequestError"
+  /bus/subscribe:
+    get:
+      summary: Subscribe to agent-emitted messages (SSE)
+      operationId: busSubscribe
+      parameters:
+        - in: query
+          name: channel
+          required: true
+          schema: { type: string, example: "agent" }
+      responses:
+        "200":
+          description: text/event-stream of messages
+          headers:
+            X-SSE-Content-Type:
+              description: Media type of SSE data events (application/json)
+              schema:
+                type: string
+                const: application/json
+          content:
+            text/event-stream:
+              schema:
+                type: string
+                example: |
+                  event: data
+                  data: {"ts":"2025-08-09T10:00:00Z","type":"custom_event","payload":{"ok":true}}
+
+  /logs/stream:
+    get:
+      summary: Subscribe to logs via SSE
+      operationId: logsStream
+      parameters:
+        - in: query
+          name: source
+          required: true
+          schema:
+            type: string
+            enum: [kernel, syslog, application, path]
+        - in: query
+          name: path
+          required: false
+          schema: { type: string }
+        - in: query
+          name: follow
+          required: false
+          schema: { type: boolean, default: true }
+      responses:
+        "200":
+          description: text/event-stream of log lines
+          headers:
+            X-SSE-Content-Type:
+              description: Media type of SSE data events (application/json)
+              schema:
+                type: string
+                const: application/json
+          content:
+            text/event-stream:
+              schema:
+                type: string
+                example: |
+                  event: data
+                  data: {"source":"path","line":"started","ts":"2025-08-09T10:00:00Z"}
+
+  /clipboard:
+    get:
+      summary: Get clipboard
+      operationId: clipboardGet
+      responses:
+        "200":
+          description: Clipboard
+          content:
+            application/json:
+              schema: { $ref: "#/components/schemas/ClipboardData" }
+    post:
+      summary: Set clipboard
+      operationId: clipboardSet
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: { $ref: "#/components/schemas/ClipboardData" }
+      responses:
+        "200":
+          description: OK
+          content:
+            application/json:
+              schema: { $ref: "#/components/schemas/OkResponse" }
+        "400":
+          $ref: "#/components/responses/BadRequestError"
+  /clipboard/stream:
+    get:
+      summary: Subscribe to clipboard changes (SSE)
+      operationId: clipboardStream
+      responses:
+        "200":
+          description: text/event-stream of clipboard previews
+          headers:
+            X-SSE-Content-Type:
+              description: Media type of SSE data events (application/json)
+              schema:
+                type: string
+                const: application/json
+          content:
+            text/event-stream:
+              schema:
+                type: string
+                example: |
+                  event: data
+                  data: {"ts":"2025-08-09T10:00:00Z","type":"text","preview":"hello..."}
+
+  /metrics/snapshot:
+    get:
+      summary: One-shot system metrics snapshot
+      operationId: metricsSnapshot
+      responses:
+        "200":
+          description: Snapshot
+          content:
+            application/json:
+              schema: { $ref: "#/components/schemas/MetricsSnapshot" }
+  /metrics/stream:
+    get:
+      summary: Stream metrics (SSE)
+      operationId: metricsStream
+      responses:
+        "200":
+          description: text/event-stream of metrics
+          headers:
+            X-SSE-Content-Type:
+              description: Media type of SSE data events (application/json)
+              schema:
+                type: string
+                const: application/json
+          content:
+            text/event-stream:
+              schema:
+                type: string
+                example: |
+                  event: data
+                  data: {"ts":"2025-08-09T10:00:00Z","cpu_pct":12.3,"gpu_pct":34.5,"mem":{"used_bytes":123,"total_bytes":456}}
+
+  /macros/create:
+    post:
+      summary: Create a macro from steps
+      operationId: macrosCreate
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: { $ref: "#/components/schemas/MacroCreateRequest" }
+      responses:
+        "200":
+          description: Created
+          content:
+            application/json:
+              schema: { $ref: "#/components/schemas/MacroCreateResponse" }
+        "400":
+          $ref: "#/components/responses/BadRequestError"
+  /macros/run:
+    post:
+      summary: Run a macro
+      operationId: macrosRun
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: { $ref: "#/components/schemas/MacroRunRequest" }
+      responses:
+        "200":
+          description: Started
+          content:
+            application/json:
+              schema: { $ref: "#/components/schemas/MacroRunResponse" }
+        "404":
+          $ref: "#/components/responses/NotFoundError"
+  /macros/list:
+    get:
+      summary: List macros
+      operationId: macrosList
+      responses:
+        "200":
+          description: Macro list
+          content:
+            application/json:
+              schema: { $ref: "#/components/schemas/MacroListResponse" }
+  /macros/{macro_id}:
+    delete:
+      summary: Delete a macro
+      operationId: macrosDelete
+      parameters:
+        - in: path
+          name: macro_id
+          required: true
+          schema: { type: string, format: uuid }
+      responses:
+        "200":
+          description: OK
+          content:
+            application/json:
+              schema: { $ref: "#/components/schemas/OkResponse" }
+        "404":
+          $ref: "#/components/responses/NotFoundError"
+
+  /scripts/upload:
+    post:
+      summary: Upload a script file
+      operationId: scriptsUpload
+      requestBody:
+        required: true
+        content:
+          multipart/form-data:
+            schema:
+              type: object
+              required: [path, file]
+              properties:
+                path: { type: string }
+                file: { type: string, format: binary }
+                executable: { type: boolean, default: true }
+      responses:
+        "200":
+          description: Uploaded
+          content:
+            application/json:
+              schema: { $ref: "#/components/schemas/ScriptUploadResponse" }
+        "400":
+          $ref: "#/components/responses/BadRequestError"
+  /scripts/run:
+    post:
+      summary: Run an uploaded script (sync or async)
+      operationId: scriptsRun
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: { $ref: "#/components/schemas/ScriptRunRequest" }
+      responses:
+        "200":
+          description: Run result or handle
+          content:
+            application/json:
+              schema:
+                oneOf:
+                  - $ref: "#/components/schemas/ProcessExecResponse"
+                  - $ref: "#/components/schemas/ScriptRunAsyncResponse"
+        "404":
+          $ref: "#/components/responses/NotFoundError"
+  /scripts/run/{run_id}/logs/stream:
+    get:
+      summary: Stream logs for an async script run (SSE)
+      operationId: scriptsRunLogsStream
+      parameters:
+        - in: path
+          name: run_id
+          required: true
+          schema: { type: string, format: uuid }
+      responses:
+        "200":
+          description: text/event-stream of stdout/stderr
+          headers:
+            X-SSE-Content-Type:
+              description: Media type of SSE data events (application/json)
+              schema:
+                type: string
+                const: application/json
+          content:
+            text/event-stream:
+              schema:
+                type: string
+                example: |
+                  event: data
+                  data: {"stream":"stdout","data_b64":"SGVsbG8K"}
+        "404":
+          $ref: "#/components/responses/NotFoundError"
+  /scripts/list:
+    get:
+      summary: List uploaded scripts
+      operationId: scriptsList
+      responses:
+        "200":
+          description: Scripts
+          content:
+            application/json:
+              schema: { $ref: "#/components/schemas/ScriptListResponse" }
+  /scripts/delete:
+    delete:
+      summary: Delete an uploaded script
+      operationId: scriptsDelete
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: { $ref: "#/components/schemas/ScriptDeleteRequest" }
+      responses:
+        "200":
+          description: OK
+          content:
+            application/json:
+              schema: { $ref: "#/components/schemas/OkResponse" }
+        "404":
+          $ref: "#/components/responses/NotFoundError"
+
+  /os/locale:
+    get:
+      summary: Get OS locale, keyboard layout, timezone
+      operationId: osLocaleGet
+      responses:
+        "200":
+          description: Locale info
+          content:
+            application/json:
+              schema: { $ref: "#/components/schemas/LocaleInfo" }
+    post:
+      summary: Set OS locale, keyboard layout, timezone
+      operationId: osLocaleSet
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: { $ref: "#/components/schemas/LocaleUpdateRequest" }
+      responses:
+        "200":
+          description: Updated
+          content:
+            application/json:
+              schema: { $ref: "#/components/schemas/LocaleUpdateResponse" }
+        "400":
+          $ref: "#/components/responses/BadRequestError"
+
+  /browser/har/start:
+    post:
+      summary: Start capturing HAR from default browser profile
+      operationId: browserHarStart
+      requestBody:
+        required: false
+        content:
+          application/json:
+            schema: { $ref: "#/components/schemas/BrowserHarStartRequest" }
+      responses:
+        "200":
+          description: Started
+          content:
+            application/json:
+              schema: { $ref: "#/components/schemas/BrowserHarStartResponse" }
+        "400":
+          $ref: "#/components/responses/BadRequestError"
+  /browser/har/{har_session_id}/stream:
+    get:
+      summary: Stream HAR entries for a HAR session (SSE)
+      operationId: browserHarStream
+      parameters:
+        - in: path
+          name: har_session_id
+          required: true
+          schema: { type: string, format: uuid }
+      responses:
+        "200":
+          description: text/event-stream of HAR entries
+          headers:
+            X-SSE-Content-Type:
+              description: Media type of SSE data events (application/json)
+              schema:
+                type: string
+                const: application/json
+          content:
+            text/event-stream:
+              schema:
+                type: string
+                example: |
+                  event: data
+                  data: {"ts":"2025-08-09T10:00:00Z","entry":{"request":{"method":"GET","url":"https://..."}}}
+        "404":
+          $ref: "#/components/responses/NotFoundError"
+  /browser/har/stop:
+    post:
+      summary: Stop HAR capture
+      operationId: browserHarStop
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required: [har_session_id]
+              properties:
+                har_session_id: { type: string, format: uuid }
+      responses:
+        "200":
+          description: OK
+          content:
+            application/json:
+              schema: { $ref: "#/components/schemas/OkResponse" }
+        "404":
+          $ref: "#/components/responses/NotFoundError"
+
+  /browser/extension/add/unpacked:
+    post:
+      summary: Add an unpacked browser extension
+      operationId: browserExtensionAddUnpacked
+      requestBody:
+        required: true
+        content:
+          multipart/form-data:
+            schema:
+              type: object
+              properties:
+                github_url:
+                  type: string
+                  description: GitHub repository URL for the extension
+                archive_file:
+                  type: string
+                  format: binary
+                  description: ZIP archive containing the extension (manifest at root or in first-level dir)
+              oneOf:
+                - required: [github_url]
+                - required: [archive_file]
+      responses:
+        "201":
+          description: Extension added successfully
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  id:
+                    type: string
+                    description: Extension ID
+                  version:
+                    type: string
+                    description: Extension version
+                  crx_path:
+                    type: string
+                    description: Path to the CRX file
+                  update_xml_path:
+                    type: string
+                    description: Path to the update XML file
+                  update_url:
+                    type: string
+                    description: URL for extension updates
+                  policy_path:
+                    type: string
+                    description: Path to the policy file
+                  installed:
+                    type: boolean
+                    description: Whether the extension was installed
+                  profile_extensions_dir:
+                    type: string
+                    description: Directory where the extension is installed
+        "400":
+          $ref: "#/components/responses/BadRequestError"
+        "500":
+          description: Server error
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  error:
+                    type: string
+
+
+  /pipe/send:
+    post:
+      summary: Send a JSON object onto a named pipe channel
+      operationId: pipeSend
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: { $ref: "#/components/schemas/PipeSendRequest" }
+      responses:
+        "200":
+          description: Enqueued
+          content:
+            application/json:
+              schema: { $ref: "#/components/schemas/PipeSendResponse" }
+        "400":
+          $ref: "#/components/responses/BadRequestError"
+  /pipe/recv/stream:
+    get:
+      summary: Receive JSON objects from a named pipe channel (SSE)
+      operationId: pipeRecvStream
+      parameters:
+        - in: query
+          name: channel
+          required: true
+          schema: { type: string, default: "default" }
+      responses:
+        "200":
+          description: text/event-stream of objects
+          headers:
+            X-SSE-Content-Type:
+              description: Media type of SSE data events (application/json)
+              schema:
+                type: string
+                const: application/json
+          content:
+            text/event-stream:
+              schema:
+                type: string
+                example: |
+                  event: data
+                  data: {"ts":"2025-08-09T10:00:00Z","object":{"event":"ready"}}
+
+  /health:
+    get:
+      summary: Health status
+      operationId: health
+      responses:
+        "200":
+          description: OK
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  status: { type: string, example: ok }
+                  uptime_sec: { type: number, example: 12345 }
+
+components:
+  schemas:
+    # -------------------------
+    # PREVIOUS, UNCHANGED SCHEMAS
+    # -------------------------
+    StartRecordingRequest:
+      type: object
+      properties:
+        maxFileSizeInMB:
+          type: integer
+          description: Maximum file size in MB (overrides server default)
+          minimum: 10
+          maximum: 10000
+        framerate:
+          type: integer
+          description: Recording framerate in fps (overrides server default)
+          minimum: 1
+          maximum: 20
+        maxDurationInSeconds:
+          type: integer
+          description: Maximum recording duration in seconds (overrides server default)
+          minimum: 1
+        id:
+          type: string
+          description: Optional identifier for the recording session. Alphanumeric or hyphen.
+          pattern: "^[a-zA-Z0-9-]+$"
+      additionalProperties: false
+    StopRecordingRequest:
+      type: object
+      properties:
+        forceStop:
+          type: boolean
+          description: Immediately stop without graceful shutdown. This may result in a corrupted video file.
+          default: false
+        id:
+          type: string
+          description: Identifier of the recorder to stop. Alphanumeric or hyphen.
+          pattern: "^[a-zA-Z0-9-]+$"
+      additionalProperties: false
+    Error:
+      type: object
+      required: [message]
+      properties:
+        message:
+          type: string
+    RecorderInfo:
+      type: object
+      required: [id, isRecording]
+      properties:
+        id:
+          type: string
+        isRecording:
+          type: boolean
+        started_at:
+          type: string
+          format: date-time
+          nullable: true
+          description: Timestamp when recording started
+        finished_at:
+          type: string
+          format: date-time
+          nullable: true
+          description: Timestamp when recording finished
+    ClickMouseRequest:
+      type: object
+      properties:
+        button:
+          type: string
+          description: Mouse button to interact with
+          enum: [left, right, middle, back, forward]
+        click_type:
+          type: string
+          description: Type of click action
+          enum: [down, up, click]
+        x:
+          type: integer
+          description: X coordinate of the click position
+        y:
+          type: integer
+          description: Y coordinate of the click position
+        hold_keys:
+          type: array
+          description: Modifier keys to hold during the click
+          items:
+            type: string
+        num_clicks:
+          type: integer
+          description: Number of times to repeat the click
+          default: 1
+      additionalProperties: false
+    MoveMouseRequest:
+      type: object
+      required: [x, y]
+      properties:
+        x:
+          type: integer
+          description: X coordinate to move the cursor to
+        y:
+          type: integer
+          description: Y coordinate to move the cursor to
+        hold_keys:
+          type: array
+          description: Modifier keys to hold during the move
+          items:
+            type: string
+      additionalProperties: false
+    StartFsWatchRequest:
+      type: object
+      required: [path]
+      properties:
+        path:
+          type: string
+          description: Directory to watch.
+        recursive:
+          type: boolean
+          description: Whether to watch recursively.
+          default: false
+      additionalProperties: false
+    FileSystemEvent:
+      type: object
+      description: Filesystem change event.
+      required: [type, path]
+      properties:
+        type:
+          type: string
+          enum: [CREATE, WRITE, DELETE, RENAME]
+          description: Event type.
+        name:
+          type: string
+          description: Base name of the file or directory affected.
+        path:
+          type: string
+          description: Absolute path of the file or directory.
+        is_dir:
+          type: boolean
+          description: Whether the affected path is a directory.
+    DeleteRecordingRequest:
+      type: object
+      properties:
+        id:
+          type: string
+          description: Identifier of the recording to delete. Alphanumeric or hyphen.
+          pattern: "^[a-zA-Z0-9-]+$"
+      additionalProperties: false
+    FileInfo:
+      type: object
+      required: [name, path, size_bytes, is_dir, mod_time, mode]
+      properties:
+        name:
+          type: string
+          description: Base name of the file or directory.
+        path:
+          type: string
+          description: Absolute path.
+        size_bytes:
+          type: integer
+          description: Size in bytes. 0 for directories.
+        is_dir:
+          type: boolean
+          description: Whether the path is a directory.
+        mod_time:
+          type: string
+          format: date-time
+          description: Last modification time.
+        mode:
+          type: string
+          description: File mode bits (e.g., "drwxr-xr-x" or "-rw-r--r--").
+    ListFiles:
+      type: array
+      description: Array of file or directory information entries.
+      items:
+        $ref: "#/components/schemas/FileInfo"
+    CreateDirectoryRequest:
+      type: object
+      required: [path]
+      properties:
+        path:
+          type: string
+          description: Absolute directory path to create.
+          pattern: "^/.*"
+        mode:
+          type: string
+          description: Optional directory mode (octal string, e.g. 755). Defaults to 755.
+          pattern: "^[0-7]{3,4}$"
+      additionalProperties: false
+    DeletePathRequest:
+      type: object
+      required: [path]
+      properties:
+        path:
+          type: string
+          description: Absolute path to delete.
+          pattern: "^/.*"
+      additionalProperties: false
+    SetFilePermissionsRequest:
+      type: object
+      required: [path, mode]
+      properties:
+        path:
+          type: string
+          description: Absolute path whose permissions are to be changed.
+          pattern: "^/.*"
+        owner:
+          type: string
+          description: New owner username or UID.
+        group:
+          type: string
+          description: New group name or GID.
+        mode:
+          type: string
+          description: File mode bits (octal string, e.g. 644).
+          pattern: "^[0-7]{3,4}$"
+      additionalProperties: false
+    MovePathRequest:
+      type: object
+      required: [src_path, dest_path]
+      properties:
+        src_path:
+          type: string
+          description: Absolute source path.
+          pattern: "^/.*"
+        dest_path:
+          type: string
+          description: Absolute destination path.
+          pattern: "^/.*"
+      additionalProperties: false
+
+    # -------------------------
+    # NEW SCHEMAS (ADDITIVE)
+    # -------------------------
+    OkResponse:
+      type: object
+      properties:
+        ok: { type: boolean, example: true }
+
+    Region:
+      type: object
+      properties:
+        x: { type: integer, minimum: 0 }
+        y: { type: integer, minimum: 0 }
+        width: { type: integer, minimum: 1 }
+        height: { type: integer, minimum: 1 }
+      required: [x, y, width, height]
+
+    ScreenshotCaptureRequest:
+      type: object
+      properties:
+        region: { $ref: "#/components/schemas/Region", nullable: true }
+        include_cursor: { type: boolean, default: false }
+        display: { type: integer, default: 0 }
+        format: { type: string, enum: [png, jpeg], default: png }
+        quality: { type: integer, minimum: 1, maximum: 100, nullable: true, description: JPEG only }
+      required: [format]
+    ScreenshotCaptureResponse:
+      type: object
+      properties:
+        screenshot_id: { type: string, format: uuid }
+        content_type: { type: string, example: image/png }
+        bytes_b64: { type: string }
+
+    StreamStartRequest:
+      type: object
+      properties:
+        region: { $ref: "#/components/schemas/Region", nullable: true }
+        display: { type: integer, default: 0 }
+        fps: { type: integer, default: 30 }
+        video_codec: { type: string, enum: [h264, h265, av1], default: h264 }
+        video_bitrate_kbps: { type: integer, default: 3500 }
+        audio:
+          type: object
+          properties:
+            capture_system: { type: boolean, default: true }
+            capture_mic: { type: boolean, default: false }
+        rtmps_url: { type: string }
+        stream_key: { type: string }
+      required: [fps, video_codec, rtmps_url, stream_key]
+    StreamStartResponse:
+      type: object
+      properties:
+        stream_id: { type: string, format: uuid }
+        status: { type: string, example: starting }
+        metrics_endpoint: { type: string, example: "/stream/{stream_id}/metrics/stream" }
+    StreamStopRequest:
+      type: object
+      properties:
+        stream_id: { type: string, format: uuid }
+      required: [stream_id]
+    StreamStopResponse:
+      type: object
+      properties:
+        stream_id: { type: string, format: uuid }
+        status: { type: string, example: stopped }
+
+    MouseClickRequest:
+      type: object
+      properties:
+        button:
+          oneOf:
+            - type: string
+              enum: [left, middle, right, back, forward]
+            - type: integer
+        count: { type: integer, default: 1 }
+      required: [button]
+    MouseScrollRequest:
+      type: object
+      properties:
+        dx: { type: integer, default: 0 }
+        dy: { type: integer, default: -120 }
+      required: [dx, dy]
+
+    KeyboardTypeRequest:
+      type: object
+      properties:
+        text: { type: string }
+        wpm: { type: integer, default: 300 }
+        enter: { type: boolean, default: false }
+      required: [text]
+    KeyRequest:
+      type: object
+      properties:
+        key: { type: string }
+      required: [key]
+
+    WindowMatch:
+      type: object
+      properties:
+        title_contains: { type: string, nullable: true }
+        class: { type: string, nullable: true }
+        pid: { type: integer, nullable: true }
+    WindowActivateRequest:
+      type: object
+      properties:
+        match: { $ref: "#/components/schemas/WindowMatch" }
+      required: [match]
+    WindowActivateResponse:
+      type: object
+      properties:
+        activated: { type: boolean }
+        wid: { type: string }
+    WindowMoveResizeRequest:
+      type: object
+      properties:
+        match: { $ref: "#/components/schemas/WindowMatch" }
+        x: { type: integer }
+        y: { type: integer }
+        width: { type: integer }
+        height: { type: integer }
+      required: [match]
+
+    MouseMoveRelativeRequest:
+      type: object
+      properties:
+        dx: { type: integer, default: 0 }
+        dy: { type: integer, default: 0 }
+      required: [dx, dy]
+
+    MouseButtonRequest:
+      type: object
+      properties:
+        button:
+          oneOf:
+            - type: string
+              enum: [left, middle, right, back, forward]
+            - type: integer
+      required: [button]
+
+    MouseLocationResponse:
+      type: object
+      properties:
+        x: { type: integer }
+        y: { type: integer }
+        screen: { type: integer }
+        window: { type: string }
+
+    KeyboardKeysRequest:
+      type: object
+      properties:
+        keys:
+          type: array
+          items: { type: string }
+      required: [keys]
+
+    WindowIdRequest:
+      type: object
+      properties:
+        wid: { type: string }
+      required: [wid]
+
+    WindowFocusResponse:
+      type: object
+      properties:
+        focused: { type: boolean }
+        wid: { type: string }
+
+    ActiveWindowResponse:
+      type: object
+      properties:
+        wid: { type: string }
+
+    WindowNameResponse:
+      type: object
+      properties:
+        wid: { type: string }
+        name: { type: string }
+
+    WindowPidResponse:
+      type: object
+      properties:
+        wid: { type: string }
+        pid: { type: integer }
+
+    WindowGeometryResponse:
+      type: object
+      properties:
+        wid: { type: string }
+        x: { type: integer }
+        y: { type: integer }
+        width: { type: integer }
+        height: { type: integer }
+        screen: { type: integer }
+
+    DisplayGeometryResponse:
+      type: object
+      properties:
+        width: { type: integer }
+        height: { type: integer }
+
+    DesktopCountRequest:
+      type: object
+      properties:
+        count: { type: integer, minimum: 1 }
+      required: [count]
+
+    DesktopCountResponse:
+      type: object
+      properties:
+        count: { type: integer }
+
+    DesktopIndexRequest:
+      type: object
+      properties:
+        index: { type: integer, minimum: 0 }
+      required: [index]
+
+    DesktopIndexResponse:
+      type: object
+      properties:
+        index: { type: integer }
+
+    WindowDesktopRequest:
+      type: object
+      properties:
+        match: { $ref: "#/components/schemas/WindowMatch" }
+        index: { type: integer, minimum: 0 }
+      required: [match, index]
+
+    DesktopViewportRequest:
+      type: object
+      properties:
+        x: { type: integer }
+        y: { type: integer }
+      required: [x, y]
+
+    DesktopViewportResponse:
+      type: object
+      properties:
+        x: { type: integer }
+        y: { type: integer }
+
+    ActivateAndTypeRequest:
+      type: object
+      properties:
+        match: { $ref: "#/components/schemas/WindowMatch" }
+        text: { type: string, default: "" }
+        enter: { type: boolean, default: false }
+        wpm: { type: integer, default: 300 }
+      required: [match]
+
+    ActivateAndKeysRequest:
+      type: object
+      properties:
+        match: { $ref: "#/components/schemas/WindowMatch" }
+        keys:
+          type: array
+          items: { type: string }
+      required: [match, keys]
+
+    ComboWindowResponse:
+      type: object
+      properties:
+        ok: { type: boolean }
+        wid: { type: string }
+
+    WindowCenterRequest:
+      type: object
+      properties:
+        match: { $ref: "#/components/schemas/WindowMatch" }
+        width: { type: integer, nullable: true }
+        height: { type: integer, nullable: true }
+      required: [match]
+
+    WindowCenterResponse:
+      type: object
+      properties:
+        ok: { type: boolean }
+        wid: { type: string }
+        x: { type: integer }
+        y: { type: integer }
+        width: { type: integer }
+        height: { type: integer }
+
+    WindowSnapRequest:
+      type: object
+      properties:
+        match: { $ref: "#/components/schemas/WindowMatch" }
+        position:
+          type: string
+          enum: [left, right, top, bottom, topleft, topright, bottomleft, bottomright, maximize]
+      required: [match, position]
+
+    WindowSnapResponse:
+      type: object
+      properties:
+        ok: { type: boolean }
+        wid: { type: string }
+        x: { type: integer }
+        y: { type: integer }
+        width: { type: integer }
+        height: { type: integer }
+
+    SystemExecRequest:
+      type: object
+      properties:
+        command: { type: string }
+        args: { type: array, items: { type: string }, default: [] }
+      required: [command]
+
+    SystemExecResponse:
+      type: object
+      properties:
+        code: { type: integer }
+        stdout: { type: string }
+        stderr: { type: string }
+
+    SleepRequest:
+      type: object
+      properties:
+        seconds: { type: number, minimum: 0 }
+      required: [seconds]
+
+
+    UploadResponse:
+      type: object
+      properties:
+        path: { type: string }
+        size_bytes: { type: integer }
+
+    ProcessExecRequest:
+      type: object
+      properties:
+        command: { type: string }
+        args: { type: array, items: { type: string }, default: [] }
+        cwd: { type: string, nullable: true }
+        env: { type: object, additionalProperties: { type: string }, default: {} }
+        as_user: { type: string, nullable: true }
+        as_root: { type: boolean, default: false }
+        timeout_sec: { type: integer, nullable: true }
+        stream: { type: boolean, default: false }
+      required: [command]
+    ProcessExecResponse:
+      type: object
+      properties:
+        exit_code: { type: integer }
+        stdout_b64: { type: string }
+        stderr_b64: { type: string }
+        duration_ms: { type: integer }
+    ProcessSpawnRequest:
+      allOf:
+        - $ref: "#/components/schemas/ProcessExecRequest"
+      properties:
+        stream: { readOnly: true }
+    ProcessSpawnResponse:
+      type: object
+      properties:
+        process_id: { type: string, format: uuid }
+        pid: { type: integer }
+        started_at: { type: string, format: date-time }
+    ProcessStatusResponse:
+      type: object
+      properties:
+        state: { type: string, enum: [running, exited] }
+        exit_code: { type: integer, nullable: true }
+        cpu_pct: { type: number }
+        mem_bytes: { type: integer }
+    ProcessStdinRequest:
+      type: object
+      properties:
+        data_b64: { type: string }
+      required: [data_b64]
+    ProcessKillRequest:
+      type: object
+      properties:
+        signal: { type: string, enum: [TERM, KILL, INT, HUP], default: TERM }
+      required: [signal]
+
+    Socks5StartRequest:
+      type: object
+      properties:
+        bind_host: { type: string, default: "127.0.0.1" }
+        bind_port: { type: integer, default: 1080 }
+        auth:
+          type: object
+          nullable: true
+          properties:
+            username: { type: string, nullable: true }
+            password: { type: string, nullable: true }
+      required: [bind_host, bind_port]
+    Socks5StartResponse:
+      type: object
+      properties:
+        proxy_id: { type: string, format: uuid }
+        url: { type: string, example: "socks5://127.0.0.1:1080" }
+    Socks5StopRequest:
+      type: object
+      properties:
+        proxy_id: { type: string, format: uuid }
+      required: [proxy_id]
+
+    NetworkInterceptRulesRequest:
+      type: object
+      properties:
+        rules:
+          type: array
+          items:
+            $ref: "#/components/schemas/NetworkRule"
+      required: [rules]
+    NetworkInterceptRulesResponse:
+      type: object
+      properties:
+        rule_set_id: { type: string, format: uuid }
+        applied: { type: boolean }
+    NetworkRule:
+      type: object
+      properties:
+        id: { type: string }
+        match:
+          type: object
+          properties:
+            protocol: { type: string, enum: [http, https], nullable: true }
+            host_contains: { type: string, nullable: true }
+            path_regex: { type: string, nullable: true }
+            method: { type: string, enum: [GET, POST, PUT, DELETE, PATCH, HEAD, OPTIONS], nullable: true }
+        action:
+          type: object
+          properties:
+            type: { type: string, enum: [block, delay, modify_request, modify_response, mock_response] }
+            delay_ms: { type: integer, nullable: true }
+            set_request_headers: { type: object, additionalProperties: { type: string }, nullable: true }
+            set_response_headers: { type: object, additionalProperties: { type: string }, nullable: true }
+            status: { type: integer, nullable: true }
+            body_b64: { type: string, nullable: true }
+      required: [id, match, action]
+
+    HarEntryEvent:
+      type: object
+      properties:
+        ts: { type: string, format: date-time }
+        entry:
+          type: object
+          properties:
+            request:
+              type: object
+              properties:
+                method: { type: string }
+                url: { type: string }
+                headers:
+                  type: array
+                  items:
+                    type: object
+                    properties:
+                      name: { type: string }
+                      value: { type: string }
+            response:
+              type: object
+              properties:
+                status: { type: integer }
+                headers:
+                  type: array
+                  items:
+                    type: object
+                    properties:
+                      name: { type: string }
+                      value: { type: string }
+                timings:
+                  type: object
+                  properties:
+                    blocked: { type: number, nullable: true }
+                    dns: { type: number, nullable: true }
+                    connect: { type: number, nullable: true }
+                    wait: { type: number, nullable: true }
+                    receive: { type: number, nullable: true }
+
+    ForwardRequest:
+      type: object
+      properties:
+        direction: { type: string, enum: [host_to_vm, vm_to_host] }
+        host_port: { type: integer }
+        vm_port: { type: integer }
+      required: [direction, host_port, vm_port]
+    ForwardResponse:
+      type: object
+      properties:
+        forward_id: { type: string, format: uuid }
+        active: { type: boolean }
+
+    BusPublishRequest:
+      type: object
+      properties:
+        channel: { type: string, example: agent }
+        type: { type: string, example: custom_event }
+        payload: { type: object }
+      required: [channel, type, payload]
+    BusPublishResponse:
+      type: object
+      properties:
+        delivered: { type: boolean }
+
+    ClipboardData:
+      type: object
+      properties:
+        type: { type: string, enum: [text, image] }
+        text: { type: string, nullable: true }
+        image_b64: { type: string, nullable: true }
+        image_mime: { type: string, nullable: true, example: image/png }
+      required: [type]
+
+    MetricsSnapshot:
+      type: object
+      properties:
+        cpu_pct: { type: number }
+        gpu_pct: { type: number }
+        mem:
+          type: object
+          properties:
+            used_bytes: { type: integer }
+            total_bytes: { type: integer }
+        disk:
+          type: object
+          properties:
+            read_bps: { type: integer }
+            write_bps: { type: integer }
+        net:
+          type: object
+          properties:
+            rx_bps: { type: integer }
+            tx_bps: { type: integer }
+
+    MacroCreateRequest:
+      type: object
+      properties:
+        name: { type: string }
+        steps:
+          type: array
+          items:
+            $ref: "#/components/schemas/MacroStep"
+      required: [name, steps]
+    MacroStep:
+      type: object
+      properties:
+        action: { type: string, example: keyboard.type }
+        text: { type: string, nullable: true }
+        key: { type: string, nullable: true }
+        ms: { type: integer, nullable: true, description: for sleep action }
+      required: [action]
+    MacroCreateResponse:
+      type: object
+      properties:
+        macro_id: { type: string, format: uuid }
+    MacroRunRequest:
+      type: object
+      properties:
+        macro_id: { type: string, format: uuid }
+      required: [macro_id]
+    MacroRunResponse:
+      type: object
+      properties:
+        started: { type: boolean }
+        run_id: { type: string, format: uuid }
+    MacroItem:
+      type: object
+      properties:
+        macro_id: { type: string, format: uuid }
+        name: { type: string }
+        steps_count: { type: integer }
+    MacroListResponse:
+      type: object
+      properties:
+        items:
+          type: array
+          items: { $ref: "#/components/schemas/MacroItem" }
+
+    ScriptUploadResponse:
+      type: object
+      properties:
+        path: { type: string }
+        size_bytes: { type: integer }
+    ScriptRunRequest:
+      type: object
+      properties:
+        path: { type: string }
+        args: { type: array, items: { type: string }, default: [] }
+        cwd: { type: string, nullable: true }
+        env: { type: object, additionalProperties: { type: string }, default: {} }
+        as_user: { type: string, nullable: true }
+        as_root: { type: boolean, default: false }
+        mode: { type: string, enum: [sync, async], default: sync }
+        stream: { type: boolean, default: true }
+      required: [path]
+    ScriptRunAsyncResponse:
+      type: object
+      properties:
+        run_id: { type: string, format: uuid }
+    ScriptListResponse:
+      type: object
+      properties:
+        items:
+          type: array
+          items:
+            type: object
+            properties:
+              path: { type: string }
+              size_bytes: { type: integer }
+              updated_at: { type: string, format: date-time }
+    ScriptDeleteRequest:
+      type: object
+      properties:
+        path: { type: string }
+      required: [path]
+
+    LocaleInfo:
+      type: object
+      properties:
+        locale: { type: string, example: en_US.UTF-8 }
+        keyboard_layout: { type: string, example: us }
+        timezone: { type: string, example: UTC }
+    LocaleUpdateRequest:
+      allOf:
+        - $ref: "#/components/schemas/LocaleInfo"
+      properties:
+        apply_to: { type: string, enum: [current_session, system], default: current_session }
+    LocaleUpdateResponse:
+      type: object
+      properties:
+        updated: { type: boolean }
+        requires_restart: { type: boolean }
+
+    BrowserHarStartRequest:
+      type: object
+      properties:
+        include_content: { type: boolean, default: true }
+    BrowserHarStartResponse:
+      type: object
+      properties:
+        har_session_id: { type: string, format: uuid }
+
+    PipeSendRequest:
+      type: object
+      properties:
+        channel: { type: string, default: default }
+        object: { type: object }
+      required: [channel, object]
+    PipeSendResponse:
+      type: object
+      properties:
+        enqueued: { type: boolean }
+
+  responses:
+    BadRequestError:
+      description: Bad Request
+      content:
+        application/json:
+          schema:
+            $ref: "#/components/schemas/Error"
+    ConflictError:
+      description: Conflict
+      content:
+        application/json:
+          schema:
+            $ref: "#/components/schemas/Error"
+    NotFoundError:
+      description: Not Found
+      content:
+        application/json:
+          schema:
+            $ref: "#/components/schemas/Error"
+    InternalError:
+      description: Internal Server Error
+      content:
+        application/json:
+          schema:
+            $ref: "#/components/schemas/Error"
diff --git a/operator-api/package.json b/operator-api/package.json
new file mode 100644
index 00000000..36775487
--- /dev/null
+++ b/operator-api/package.json
@@ -0,0 +1,40 @@
+{
+  "name": "kernel-computer-operator-api",
+  "version": "0.1.0",
+  "description": "Node.js (ESM) Hono server implementing the Kernel Computer Operator API",
+  "type": "module",
+  "main": "index.js",
+  "scripts": {
+    "start": "node index.js",
+    "dev": "NODE_ENV=development nodemon --watch src --ext js,json index.js",
+    "test": "cross-env PORT=10001 vitest run --reporter=verbose",
+    "test:watch": "cross-env PORT=10001 vitest",
+    "build:api": "cp .kernel-operator.env .env && bun build --compile --minify --sourcemap --bytecode --target=bun-linux-x64 ./index.js --outfile dist/kernel-operator-api && cp .env dist/.env",
+    "build:test": "cp .kernel-operator.env .env && bun build --compile --minify --sourcemap --target=bun-linux-x64 ./test.js --outfile dist/kernel-operator-test && cp .env dist/.env",
+    "build": "bun build:api && bun build:test && cp .env dist/.kernel-operator.env"
+  },
+  "dependencies": {
+    "@hono/node-server": "^1.13.8",
+    "busboy": "^1.6.0",
+    "chalk": "^5.3.0",
+    "chokidar": "^3.6.0",
+    "dotenv": "^16.4.5",
+    "extract-zip": "^2.0.1",
+    "formdata-node": "^6.0.3",
+    "hono": "^4.5.10",
+    "http-proxy": "^1.18.1",
+    "httpolyglot": "^0.1.2",
+    "mime-types": "^2.1.35",
+    "morgan": "^1.10.0",
+    "nanoid": "^5.0.7",
+    "pidusage": "^3.0.2",
+    "uuid": "^11.1.0",
+    "ws": "^8.18.3"
+  },
+  "devDependencies": {
+    "cross-env": "^7.0.3",
+    "nodemon": "^3.1.7",
+    "undici": "^7.13.0",
+    "vitest": "^2.0.5"
+  }
+}
diff --git a/operator-api/src/app.js b/operator-api/src/app.js
new file mode 100644
index 00000000..ae76810f
--- /dev/null
+++ b/operator-api/src/app.js
@@ -0,0 +1,40 @@
+import { Hono } from 'hono'
+import { recordingRouter } from './routes/recording.js'
+import { fsRouter } from './routes/fs.js'
+import { screenshotRouter } from './routes/screenshot.js'
+import { streamRouter } from './routes/stream.js'
+import { inputRouter } from './routes/input.js'
+import { processRouter } from './routes/process.js'
+import { networkRouter } from './routes/network.js'
+import { busRouter } from './routes/bus.js'
+import { logsRouter } from './routes/logs.js'
+import { clipboardRouter } from './routes/clipboard.js'
+import { metricsRouter } from './routes/metrics.js'
+import { macrosRouter } from './routes/macros.js'
+import { scriptsRouter } from './routes/scripts.js'
+import { osRouter } from './routes/os.js'
+import { browserRouter } from './routes/browser.js'
+import { pipeRouter } from './routes/pipe.js'
+import { healthRouter } from './routes/health.js'
+import { browserExtRouter } from './routes/browser-ext.js'
+
+export const app = new Hono()
+
+app.route('/', recordingRouter)
+app.route('/', fsRouter)
+app.route('/', screenshotRouter)
+app.route('/', streamRouter)
+app.route('/', inputRouter)
+app.route('/', processRouter)
+app.route('/', networkRouter)
+app.route('/', busRouter)
+app.route('/', logsRouter)
+app.route('/', clipboardRouter)
+app.route('/', metricsRouter)
+app.route('/', macrosRouter)
+app.route('/', scriptsRouter)
+app.route('/', osRouter)
+app.route('/', browserRouter)
+app.route('/', pipeRouter)
+app.route('/', healthRouter)
+app.route('/', browserExtRouter)
\ No newline at end of file
diff --git a/operator-api/src/routes/browser-ext.js b/operator-api/src/routes/browser-ext.js
new file mode 100644
index 00000000..95ce7f38
--- /dev/null
+++ b/operator-api/src/routes/browser-ext.js
@@ -0,0 +1,603 @@
+// src/routes/browser-ext.js
+// ESM. Requires: hono, undici, extract-zip, ws, chalk
+// Purpose: Force-install an unpacked Chromium extension from GitHub or a ZIP upload,
+//          publish it to a local "update server", and optionally pin its toolbar icon.
+// Notes:
+//   - Only Manifest V3 is supported.
+//   - Pinning is supported via policy key: ExtensionSettings[<id>].toolbar_pin = "force_pinned" (Chrome/Chromium 114+).
+//   - Incognito auto-enable is intentionally not implemented; Chrome policy does not support forcing it.
+
+import { Hono } from 'hono'
+import fs from 'node:fs/promises'
+import fssync from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+import crypto from 'node:crypto'
+import { spawn } from 'node:child_process'
+import { setTimeout as delay } from 'node:timers/promises'
+import extract from 'extract-zip'
+import { request } from 'undici'
+import { WebSocket } from 'ws'
+import chalk from 'chalk'
+
+export const browserExtRouter = new Hono()
+
+/* ────────────────────────────── HTTP routes ────────────────────────────── */
+
+// POST /browser/extension/add/unpacked  (multipart/form-data OR application/json)
+//   fields:
+//     github_url: string   OR
+//     archive_file: File (.zip, manifest at root or one-level nested)
+// Behavior:
+//   - Downloads/reads the archive
+//   - Extracts and validates manifest.json (MV3 only)
+//   - Packs extension with chromium --pack-extension using a stable per-source key
+//   - Publishes CRX + update.xml under repoStorageDir
+//   - Writes policy to force-install and (optionally) pin toolbar icon
+//   - Tries to hot-reload policy via DevTools; optionally restarts browser if needed
+browserExtRouter.post('/browser/extension/add/unpacked', async (c) => {
+  const origin = new URL(c.req.url).origin
+  const form = await readForm(c)
+
+  const params = {
+    github_url: form.github_url || undefined,
+    archive_file_path: form.archive_path || undefined,
+    chromiumBinary: process.env.CHROMIUM_BINARY || 'chromium',
+    devtoolsHost: process.env.CHROME_HOST || '127.0.0.1',
+    devtoolsPort: Number(process.env.CHROME_PORT || 9222),
+
+    // Resolve a writable managed policy directory automatically
+    policyDir: await detectPolicyDir([
+      '/etc/chromium/policies/managed',
+      '/etc/opt/chromium/policies/managed',
+      '/etc/opt/chrome/policies/managed',
+      '/etc/chrome/policies/managed'
+    ]),
+
+    // Local "update server" root and base URL
+    repoStorageDir: process.env.EXT_REPO_DIR || '/opt/extrepo',
+    repoBaseUrl: process.env.EXT_REPO_BASE_URL || `${origin}/extrepo`,
+
+    // Directory holding persistent RSA keys for stable extension IDs
+    keyStoreDir: process.env.EXT_KEY_STORE_DIR || '/var/lib/chrome-ext-keys',
+
+    // Toolbar pin control (Chrome/Chromium 114+). Safe to enable; ignored on older versions.
+    pinToToolbar: envBool(process.env.EXT_PIN_TOOLBAR, true),
+
+    tryHotReloadPolicy: true,
+    fallbackRestart: true,
+    waitInstallTimeoutMs: 25_000
+  }
+
+  logInfo('incoming', { from: params.github_url ? 'github' : 'upload', pinToToolbar: params.pinToToolbar })
+
+  try {
+    const result = await addUnpackedExtension(params)
+    logOk('done', { id: result.id, version: result.version, pinned: result.pinned, installed: result.installed })
+    return c.json(result, 201)
+  } catch (err) {
+    logFail('error', { error: err?.message || String(err) })
+    return c.json({ error: err.message || String(err) }, 500)
+  } finally {
+    if (form.cleanup) await form.cleanup().catch(() => { })
+  }
+})
+
+// GET /extrepo/*  (serves CRX and update.xml from repoStorageDir)
+//   Example paths:
+//     /extrepo/<extId>/<extId>.crx
+//     /extrepo/<extId>/update.xml
+browserExtRouter.get('/extrepo/*', async (c) => {
+  const baseDir = process.env.EXT_REPO_DIR || '/opt/extrepo'
+  const tail = c.req.path.replace(/^\/extrepo\/?/, '')
+  const safePath = path.normalize(tail).replace(/^(\.\.[/\\])+/, '')
+  const target = path.join(baseDir, safePath)
+  if (!target.startsWith(path.resolve(baseDir))) return c.text('Forbidden', 403)
+  try {
+    const stat = await fs.stat(target)
+    if (stat.isDirectory()) return c.text('Not Found', 404)
+    const ext = path.extname(target).toLowerCase()
+    const type =
+      ext === '.xml' ? 'application/xml' :
+        ext === '.crx' ? 'application/x-chrome-extension' :
+          'application/octet-stream'
+    const stream = fssync.createReadStream(target)
+    return new Response(stream, { headers: { 'content-type': type } })
+  } catch {
+    return c.text('Not Found', 404)
+  }
+})
+
+/* ───────────────────────────── form reader ───────────────────────────── */
+
+async function readForm(c) {
+  const ct = c.req.header('content-type') || ''
+  if (ct.includes('application/json')) {
+    const body = await c.req.json()
+    return {
+      github_url: body.github_url,
+      archive_path: undefined,
+      cleanup: async () => { }
+    }
+  }
+
+  const fd = await c.req.formData()
+  const github_url = fd.get('github_url')?.toString() || undefined
+  const file = fd.get('archive_file')
+  let archive_path
+  let cleanup = async () => { }
+
+  if (file && typeof file === 'object' && 'arrayBuffer' in file) {
+    const tmpRoot = await fs.mkdtemp(path.join(os.tmpdir(), 'extupload-'))
+    archive_path = path.join(tmpRoot, 'upload.zip')
+    const buf = Buffer.from(await file.arrayBuffer())
+    await fs.writeFile(archive_path, buf)
+    cleanup = async () => {
+      try { await fs.rm(tmpRoot, { recursive: true, force: true }) } catch { }
+    }
+  }
+
+  return { github_url, archive_path, cleanup }
+}
+
+/* ─────────────────────── core implementation ─────────────────────── */
+
+const DEFAULTS = {
+  chromiumBinary: process.env.CHROMIUM_BINARY || 'chromium',
+  devtoolsHost: process.env.CHROME_HOST || '127.0.0.1',
+  devtoolsPort: Number(process.env.CHROME_PORT || 9222),
+  policyDir: '/etc/chromium/policies/managed',
+  repoStorageDir: process.env.EXT_REPO_DIR || '/opt/extrepo',
+  repoBaseUrl: process.env.EXT_REPO_BASE_URL || 'http://127.0.0.1:3000/extrepo',
+  keyStoreDir: process.env.EXT_KEY_STORE_DIR || '/var/lib/chrome-ext-keys',
+  userDataDirsProbe: [
+    '/tmp/.chromium/chromium',
+    '/home/kernel/.config/chromium',
+    path.join(os.homedir(), '.config', 'chromium')
+  ]
+}
+
+const NIBBLE_MAP = 'abcdefghijklmnop'.split('')
+
+/**
+ * Add an unpacked extension by source (GitHub or uploaded ZIP),
+ * pack to CRX with a deterministic key, publish, and force-install via policy.
+ */
+async function addUnpackedExtension({
+  github_url,
+  archive_file_path,
+  chromiumBinary = DEFAULTS.chromiumBinary,
+  devtoolsHost = DEFAULTS.devtoolsHost,
+  devtoolsPort = DEFAULTS.devtoolsPort,
+  policyDir = DEFAULTS.policyDir,
+  repoStorageDir = DEFAULTS.repoStorageDir,
+  repoBaseUrl = DEFAULTS.repoBaseUrl,
+  keyStoreDir = DEFAULTS.keyStoreDir,
+  pinToToolbar = true,
+  tryHotReloadPolicy = true,
+  fallbackRestart = true,
+  waitInstallTimeoutMs = 25_000
+} = {}) {
+  assertOneSource(github_url, archive_file_path)
+
+  await ensureDir(repoStorageDir)
+  await ensureDir(policyDir)
+  await ensureDir(keyStoreDir)
+
+  const workRoot = await fs.mkdtemp(path.join(os.tmpdir(), 'extwork-'))
+  const srcZip = path.join(workRoot, 'src.zip')
+  const unpackDir = path.join(workRoot, 'unpacked')
+
+  // Acquire source archive
+  if (github_url) {
+    logStep('download', { github_url })
+    const zipUrl = await resolveGithubZipURL(github_url)
+    await downloadToFile(zipUrl, srcZip)
+  } else {
+    logStep('ingest-upload', { path: archive_file_path })
+    await fs.copyFile(archive_file_path, srcZip)
+  }
+
+  // Unpack and locate manifest.json
+  logStep('extract', { to: unpackDir })
+  await extract(srcZip, { dir: unpackDir })
+  const extRoot = await resolveExtensionRoot(unpackDir)
+
+  // Validate manifest
+  const manifestPath = path.join(extRoot, 'manifest.json')
+  const manifest = await readJson(manifestPath)
+  validateManifest(manifest)
+  logStep('manifest', { version: manifest.version, mv: manifest.manifest_version })
+
+  // Stable key per source to keep extension ID constant across updates
+  const sourceKeyId = await decideKeyId({ github_url, manifest })
+  const pemPath = path.join(keyStoreDir, `${sourceKeyId}.pem`)
+  if (!fssync.existsSync(pemPath)) {
+    logStep('keygen', { id: sourceKeyId })
+    await ensureDir(keyStoreDir)
+    const { privateKey } = crypto.generateKeyPairSync('rsa', { modulusLength: 2048 })
+    const pem = privateKey.export({ type: 'pkcs8', format: 'pem' })
+    await fs.writeFile(pemPath, pem, { mode: 0o600 })
+  }
+
+  // Pack to CRX
+  const outCrx = path.join(workRoot, 'packed.crx')
+  logStep('pack', { binary: chromiumBinary })
+  await packWithChromium({ chromiumBinary, extRoot, pemPath, outCrx })
+
+  // Compute extension ID from key
+  const extId = await computeExtensionIdFromPem(pemPath)
+  logStep('ext-id', { id: extId })
+
+  // Publish CRX + update.xml
+  const publicDir = path.join(repoStorageDir, extId)
+  await ensureDir(publicDir)
+  const finalCrx = path.join(publicDir, `${extId}.crx`)
+  await fs.copyFile(outCrx, finalCrx)
+  const updateXmlPath = path.join(publicDir, 'update.xml')
+  const codebaseUrl = `${trimSlash(repoBaseUrl)}/${extId}/${extId}.crx`
+  const updateUrl = `${trimSlash(repoBaseUrl)}/${extId}/update.xml`
+  await writeUpdateXml({ updateXmlPath, extId, version: manifest.version, codebaseUrl })
+  logStep('publish', { crx: finalCrx, update_xml: updateXmlPath, update_url: updateUrl })
+
+  // Write policy: force-install and optionally force-pin
+  const policyPath = path.join(policyDir, `force_${extId}.json`)
+  const policyPayload = {
+    ExtensionInstallForcelist: [`${extId};${updateUrl}`],
+    ...(pinToToolbar && {
+      ExtensionSettings: {
+        [extId]: { toolbar_pin: 'force_pinned' } // Chrome/Chromium 114+
+      }
+    })
+  }
+  await fs.writeFile(policyPath, JSON.stringify(policyPayload, null, 2) + '\n', { mode: 0o644 })
+  logStep('policy-write', { path: policyPath, pin: !!pinToToolbar })
+
+  // Detect profile dir and check prior installation
+  const userDataDir = await locateUserDataDir(DEFAULTS.userDataDirsProbe)
+  const extInstallDir = path.join(userDataDir, 'Default', 'Extensions', extId)
+  const installedBefore = await dirExists(extInstallDir)
+
+  // Try to apply policy without restart
+  if (tryHotReloadPolicy) {
+    logStep('policy-reload', { via: 'DevTools' })
+    await devtoolsReloadPolicies({ devtoolsHost, devtoolsPort }).catch(() => { })
+  }
+
+  // Wait for install on disk
+  let installed = await waitForExtensionInstallOnDisk(extInstallDir, waitInstallTimeoutMs)
+
+  // Fallback: restart browser to pick up policy
+  if (!installed && fallbackRestart) {
+    logWarn('fallback-restart', { host: devtoolsHost, port: devtoolsPort })
+    await devtoolsRestartBrowser({ devtoolsHost, devtoolsPort }).catch(() => { })
+    await waitDevToolsUp({ devtoolsHost, devtoolsPort, timeoutMs: 20_000 }).catch(() => { })
+    installed = await waitForExtensionInstallOnDisk(extInstallDir, 15_000)
+  }
+
+  await safeRm(workRoot)
+
+  return {
+    id: extId,
+    version: manifest.version,
+    crx_path: finalCrx,
+    update_xml_path: updateXmlPath,
+    update_url: updateUrl,
+    policy_path: policyPath,
+    installed: installed || installedBefore || false,
+    profile_extensions_dir: extInstallDir,
+    pinned: !!pinToToolbar
+  }
+}
+
+/* ────────────────────────────── helpers ────────────────────────────── */
+
+function assertOneSource(github_url, archive_file_path) {
+  const provided = [!!github_url, !!archive_file_path].filter(Boolean).length
+  if (provided !== 1) throw new Error('Provide exactly one of github_url or archive_file')
+}
+
+async function ensureDir(p) {
+  await fs.mkdir(p, { recursive: true })
+}
+
+async function safeRm(p) {
+  try { await fs.rm(p, { recursive: true, force: true }) } catch { }
+}
+
+async function detectPolicyDir(candidates) {
+  for (const dir of candidates) {
+    try {
+      await fs.mkdir(dir, { recursive: true })
+      const test = path.join(dir, '.write_test')
+      await fs.writeFile(test, 'x')
+      await fs.rm(test)
+      return dir
+    } catch { }
+  }
+  // Last resort: return first path; writes will error explicitly if not writable
+  return candidates[0]
+}
+
+async function downloadToFile(url, outPath) {
+  let res = await request(url, { maxRedirections: 3 }).catch(() => null)
+  if (!res || res.statusCode < 200 || res.statusCode >= 300) {
+    throw new Error(`Download failed ${res ? res.statusCode : 'net'} for ${url}`)
+  }
+  const file = fssync.createWriteStream(outPath)
+  await new Promise((resolve, reject) => {
+    res.body.pipe(file)
+    res.body.on('error', reject)
+    file.on('finish', resolve)
+  })
+}
+
+async function resolveGithubZipURL(input) {
+  const u = new URL(input)
+  if (u.hostname !== 'github.com') throw new Error('github_url must be github.com')
+  const parts = u.pathname.split('/').filter(Boolean)
+  if (parts.length < 2) throw new Error('Invalid GitHub repo URL')
+
+  // Already a refs/heads archive URL
+  if (parts.includes('archive') && parts.includes('refs') && parts.includes('heads')) {
+    return String(u)
+  }
+
+  // /owner/repo or /owner/repo/tree/<branch>
+  const treeIdx = parts.indexOf('tree')
+  let branch = null
+  if (treeIdx >= 0 && parts[treeIdx + 1]) branch = parts[treeIdx + 1]
+  const [owner, repo] = parts
+
+  const tries = []
+  if (branch) {
+    tries.push(`https://codeload.github.com/${owner}/${repo}/zip/refs/heads/${branch}`)
+  } else {
+    tries.push(`https://codeload.github.com/${owner}/${repo}/zip/refs/heads/main`)
+    tries.push(`https://codeload.github.com/${owner}/${repo}/zip/refs/heads/master`)
+  }
+
+  for (const url of tries) {
+    const head = await request(url, { method: 'HEAD' }).catch(() => null)
+    if (head && head.statusCode === 200) return url
+  }
+  return `https://codeload.github.com/${owner}/${repo}/zip/HEAD`
+}
+
+async function resolveExtensionRoot(unpackedDir) {
+  if (await fileExists(path.join(unpackedDir, 'manifest.json'))) return unpackedDir
+
+  const entries = await fs.readdir(unpackedDir, { withFileTypes: true })
+  const dirs = entries.filter((e) => e.isDirectory())
+  if (dirs.length === 1) {
+    const cand = path.join(unpackedDir, dirs[0].name)
+    if (await fileExists(path.join(cand, 'manifest.json'))) return cand
+  }
+  for (const e of entries) {
+    if (!e.isDirectory()) continue
+    const cand = path.join(unpackedDir, e.name)
+    if (await fileExists(path.join(cand, 'manifest.json'))) return cand
+  }
+  throw new Error('manifest.json not found')
+}
+
+async function readJson(p) {
+  const buf = await fs.readFile(p)
+  return JSON.parse(buf.toString('utf8'))
+}
+
+function validateManifest(m) {
+  if (!m || typeof m !== 'object') throw new Error('Invalid manifest.json')
+  if (!m.manifest_version) throw new Error('manifest_version missing')
+  if (m.manifest_version !== 3) throw new Error('Only Manifest V3 is supported')
+  if (!m.version) throw new Error('manifest version missing')
+  if (!/^\d+(\.\d+){0,3}$/.test(m.version)) throw new Error('manifest version must be dotted number')
+}
+
+async function decideKeyId({ github_url, manifest }) {
+  if (github_url) {
+    const norm = github_url.replace(/\.git$/, '').toLowerCase()
+    return 'gh_' + crypto.createHash('sha256').update(norm).digest('hex').slice(0, 16)
+  }
+  const name = String(manifest.name || 'uploaded').toLowerCase()
+  return 'up_' + crypto.createHash('sha256').update(name).digest('hex').slice(0, 16)
+}
+
+async function lookupUser(name) {
+  const txt = await fs.readFile('/etc/passwd', 'utf8')
+  const line = txt.split('\n').find(l => l.startsWith(name + ':'))
+  if (!line) throw new Error(`User not found: ${name}`)
+  const parts = line.split(':')
+  return { uid: Number(parts[2]), gid: Number(parts[3]), home: parts[5] }
+}
+
+async function packWithChromium({ chromiumBinary, extRoot, pemPath, outCrx }) {
+  // chromium --pack-extension requires a readable key file; we chown to the target user if needed
+  const args = [`--no-sandbox`, `--pack-extension=${extRoot}`, `--pack-extension-key=${pemPath}`]
+  const { uid, gid, home } = await lookupUser(process.env.PACK_AS_USER || 'kernel')
+  try { await fs.chown(pemPath, uid, gid) } catch { }
+  await new Promise((resolve, reject) => {
+    const p = spawn(chromiumBinary, args, {
+      stdio: ['ignore', 'pipe', 'pipe'],
+      env: { ...process.env, HOME: home, DISPLAY: process.env.DISPLAY || ':1' },
+      uid, gid
+    })
+    let stderr = ''
+    p.stderr.on('data', d => { stderr += String(d) })
+    p.on('error', reject)
+    p.on('close', code => code === 0 ? resolve() : reject(new Error(`${chromiumBinary} ${args.join(' ')} exited ${code}\n${stderr}`)))
+  })
+  const produced = `${extRoot}.crx`
+  if (!fssync.existsSync(produced)) throw new Error('Chromium packer did not create .crx')
+  await fs.copyFile(produced, outCrx)
+}
+
+async function computeExtensionIdFromPem(pemPath) {
+  const pem = await fs.readFile(pemPath, 'utf8')
+  const keyObj = crypto.createPrivateKey(pem)
+  const pub = crypto.createPublicKey(keyObj)
+  const spkiDer = pub.export({ type: 'spki', format: 'der' })
+  const hash = crypto.createHash('sha256').update(spkiDer).digest()
+  const first16 = hash.subarray(0, 16)
+  let id = ''
+  for (const b of first16) id += NIBBLE_MAP[(b >> 4) & 0x0f] + NIBBLE_MAP[b & 0x0f]
+  return id
+}
+
+async function writeUpdateXml({ updateXmlPath, extId, version, codebaseUrl }) {
+  const xml =
+    `<?xml version="1.0" encoding="UTF-8"?>\n` +
+    `<gupdate xmlns="http://www.google.com/update2/response" protocol="2.0">\n` +
+    `  <app appid="${extId}">\n` +
+    `    <updatecheck codebase="${codebaseUrl}" version="${version}"/>\n` +
+    `  </app>\n` +
+    `</gupdate>\n`
+  await fs.writeFile(updateXmlPath, xml, { mode: 0o644 })
+}
+
+function trimSlash(s) { return s.replace(/\/+$/, '') }
+
+async function execFileStrict(cmd, args = [], opts = {}) {
+  await new Promise((resolve, reject) => {
+    const p = spawn(cmd, args, { stdio: ['ignore', 'pipe', 'pipe'], ...opts })
+    let stderr = ''
+    p.stderr.on('data', (d) => { stderr += d.toString() })
+    p.on('error', reject)
+    p.on('close', (code) => {
+      if (code === 0) resolve()
+      else reject(new Error(`${cmd} ${args.join(' ')} exited ${code}\n${stderr}`))
+    })
+  })
+}
+
+async function fileExists(p) {
+  try { await fs.access(p); return true } catch { return false }
+}
+
+async function dirExists(p) {
+  try { const st = await fs.stat(p); return st.isDirectory() } catch { return false }
+}
+
+async function locateUserDataDir(candidates) {
+  for (const cand of candidates) if (await dirExists(cand)) return cand
+  return candidates[0]
+}
+
+/* ───────── DevTools helpers ───────── */
+
+async function getBrowserWsUrl({ devtoolsHost, devtoolsPort }) {
+  const url = `http://${devtoolsHost}:${devtoolsPort}/json/version`
+  const res = await request(url)
+  if (res.statusCode !== 200) throw new Error('DevTools not reachable')
+  const data = await res.body.json()
+  if (!data.webSocketDebuggerUrl) throw new Error('webSocketDebuggerUrl missing')
+  return data.webSocketDebuggerUrl
+}
+
+async function cdpSession(wsUrl) {
+  const ws = new WebSocket(wsUrl, { perMessageDeflate: false })
+  await new Promise((resolve, reject) => {
+    ws.once('open', resolve)
+    ws.once('error', reject)
+  })
+  let id = 0
+  const pending = new Map()
+  ws.on('message', (data) => {
+    const msg = JSON.parse(String(data))
+    if (msg.id && pending.has(msg.id)) {
+      const { resolve, reject } = pending.get(msg.id)
+      pending.delete(msg.id)
+      if (msg.error) reject(new Error(msg.error.message || 'CDP error'))
+      else resolve(msg.result)
+    }
+  })
+  function call(method, params) {
+    return new Promise((resolve, reject) => {
+      const msg = { id: ++id, method, params }
+      pending.set(id, { resolve, reject })
+      ws.send(JSON.stringify(msg), (err) => err && reject(err))
+    })
+  }
+  function close() { try { ws.close() } catch { } }
+  return { call, close, ws }
+}
+
+async function devtoolsReloadPolicies({ devtoolsHost, devtoolsPort }) {
+  const wsUrl = await getBrowserWsUrl({ devtoolsHost, devtoolsPort })
+  const cdp = await cdpSession(wsUrl)
+  try {
+    const { targetId } = await cdp.call('Target.createTarget', { url: 'chrome://policy' })
+    const { sessionId } = await cdp.call('Target.attachToTarget', { targetId, flatten: true })
+    await cdp.call('Runtime.enable', { sessionId })
+    await cdp.call('Runtime.evaluate', {
+      sessionId,
+      expression: 'chrome && chrome.send ? chrome.send("reloadPolicies") : null',
+      awaitPromise: false
+    })
+    await delay(1000)
+    await cdp.call('Target.closeTarget', { targetId })
+  } finally {
+    cdp.close()
+  }
+}
+
+async function devtoolsRestartBrowser({ devtoolsHost, devtoolsPort }) {
+  const wsUrl = await getBrowserWsUrl({ devtoolsHost, devtoolsPort })
+  const cdp = await cdpSession(wsUrl)
+  try {
+    await cdp.call('Target.createTarget', { url: 'chrome://restart' })
+  } finally {
+    cdp.close()
+  }
+}
+
+async function waitDevToolsUp({ devtoolsHost, devtoolsPort, timeoutMs }) {
+  const start = Date.now()
+  while (Date.now() - start < timeoutMs) {
+    try {
+      const wsUrl = await getBrowserWsUrl({ devtoolsHost, devtoolsPort })
+      if (wsUrl) return true
+    } catch { }
+    await delay(500)
+  }
+  return false
+}
+
+async function waitForExtensionInstallOnDisk(extInstallDir, timeoutMs) {
+  const start = Date.now()
+  while (Date.now() - start < timeoutMs) {
+    if (await dirExists(extInstallDir)) {
+      const subs = await fs.readdir(extInstallDir).catch(() => [])
+      if (subs.length > 0) return true
+    }
+    await delay(500)
+  }
+  return false
+}
+
+/* ─────────────────────────── logging helpers ─────────────────────────── */
+
+function logStep(event, data) { log(chalk.cyan('[step]'), event, data) }
+function logInfo(event, data) { log(chalk.blue('[info]'), event, data) }
+function logWarn(event, data) { log(chalk.yellow('[warn]'), event, data) }
+function logOk(event, data) { log(chalk.green('[ok]'), event, data) }
+function logFail(event, data) { log(chalk.red('[fail]'), event, data) }
+
+function log(prefix, event, data) {
+  if (data && Object.keys(data).length) {
+    // Safe, one-line JSON for structured logs
+    console.log(prefix, event, JSON.stringify(data))
+  } else {
+    console.log(prefix, event)
+  }
+}
+
+/* ─────────────────────────── misc utilities ─────────────────────────── */
+
+function envBool(value, def = false) {
+  if (value == null) return def
+  const v = String(value).trim().toLowerCase()
+  if (['1', 'true', 'yes', 'y', 'on'].includes(v)) return true
+  if (['0', 'false', 'no', 'n', 'off'].includes(v)) return false
+  return def
+}
diff --git a/operator-api/src/routes/browser.js b/operator-api/src/routes/browser.js
new file mode 100644
index 00000000..67c0c327
--- /dev/null
+++ b/operator-api/src/routes/browser.js
@@ -0,0 +1,37 @@
+import { Hono } from 'hono'
+import { uid } from '../utils/ids.js'
+import { sseHeaders, sseFormat } from '../utils/sse.js'
+import { EventEmitter } from 'node:events'
+
+const sessions = new Map() // id -> emitter
+
+export const browserRouter = new Hono()
+
+browserRouter.post('/browser/har/start', async (c) => {
+  const body = await c.req.json().catch(() => ({}))
+  const har_session_id = uid()
+  sessions.set(har_session_id, new EventEmitter())
+  return c.json({ har_session_id })
+})
+
+browserRouter.get('/browser/har/:har_session_id/stream', async (c) => {
+  const id = c.req.param('har_session_id')
+  const em = sessions.get(id)
+  if (!em) return c.json({ message: 'Not Found' }, 404)
+  const stream = new ReadableStream({
+    start(controller) {
+      const h = (obj) => controller.enqueue(new TextEncoder().encode(sseFormat(obj)))
+      em.on('har', h)
+    }
+  })
+  return new Response(stream, { headers: sseHeaders() })
+})
+
+browserRouter.post('/browser/har/stop', async (c) => {
+  const body = await c.req.json()
+  const id = body?.har_session_id
+  const em = sessions.get(id)
+  if (!em) return c.json({ message: 'Not Found' }, 404)
+  sessions.delete(id)
+  return c.json({ ok: true })
+})
diff --git a/operator-api/src/routes/bus.js b/operator-api/src/routes/bus.js
new file mode 100644
index 00000000..945a5608
--- /dev/null
+++ b/operator-api/src/routes/bus.js
@@ -0,0 +1,26 @@
+import { Hono } from 'hono'
+import { EventEmitter } from 'node:events'
+import { sseHeaders, sseFormat } from '../utils/sse.js'
+
+const bus = new EventEmitter()
+
+export const busRouter = new Hono()
+
+busRouter.post('/bus/publish', async (c) => {
+  const body = await c.req.json()
+  bus.emit(body.channel || 'default', { ts: new Date().toISOString(), type: body.type, payload: body.payload })
+  return c.json({ delivered: true })
+})
+
+busRouter.get('/bus/subscribe', async (c) => {
+  const channel = c.req.query('channel')
+  if (!channel) return c.json({ message: 'Missing channel' }, 400)
+  const stream = new ReadableStream({
+    start(controller) {
+      const h = (obj) => controller.enqueue(new TextEncoder().encode(sseFormat(obj)))
+      bus.on(channel, h)
+    },
+    cancel() {}
+  })
+  return new Response(stream, { headers: sseHeaders() })
+})
diff --git a/operator-api/src/routes/clipboard.js b/operator-api/src/routes/clipboard.js
new file mode 100644
index 00000000..2ebde934
--- /dev/null
+++ b/operator-api/src/routes/clipboard.js
@@ -0,0 +1,120 @@
+import { Hono } from 'hono'
+import { execCapture } from '../utils/exec.js'
+import chalk from 'chalk'
+
+export const clipboardRouter = new Hono()
+
+// Debug logging function
+const debug = (message) => {
+  if (process.env.DEBUG_LOGS) {
+    console.log(chalk.cyan('[clipboard]'), message)
+  }
+}
+
+async function wlGet() {
+  debug('Attempting to get clipboard content using wl-paste')
+  const txt = await execCapture('bash', ['-lc', 'wl-paste -t text 2>/dev/null || true'])
+  if (txt.stdout?.length) return { type: 'text', text: txt.stdout.toString('utf8') }
+  const png = await execCapture('bash', ['-lc', 'wl-paste -t image/png | base64 -w0 2>/dev/null || true'])
+  if (png.stdout?.length) return { type: 'image', image_b64: png.stdout.toString('utf8'), image_mime: 'image/png' }
+  return { type: 'text', text: '' }
+}
+
+async function wlSet({ type, text, image_b64, image_mime }) {
+  debug(`Setting clipboard with wayland: type=${type}`)
+  if (type === 'text') await execCapture('bash', ['-lc', `printf %s ${JSON.stringify(text || '')} | wl-copy`])
+  else if (type === 'image' && image_b64) await execCapture('bash', ['-lc', `base64 -d | wl-copy -t ${image_mime || 'image/png'}`], { input: Buffer.from(image_b64, 'base64') })
+}
+
+async function xGet() {
+  debug('Attempting to get clipboard content using xclip')
+  const display = process.env.DISPLAY || ':20'
+  const txt = await execCapture('bash', ['-lc', `DISPLAY=${display} xclip -selection clipboard -o 2>/dev/null || true`])
+  return { type: 'text', text: txt.stdout.toString('utf8') }
+}
+
+async function xSet({ type, text }) {
+  debug(`Setting clipboard with xclip: type=${type}`)
+  const display = process.env.DISPLAY || ':20'
+  if (type === 'text') await execCapture('bash', ['-lc', `printf %s ${JSON.stringify(text || '')} | DISPLAY=${display} xclip -selection clipboard`])
+}
+
+clipboardRouter.get('/clipboard', async (c) => {
+  try {
+    debug('GET /clipboard request received')
+    // Try xclip first, fall back to wayland
+    try {
+      debug('Trying xclip first')
+      return c.json(await xGet())
+    } catch (error) {
+      debug(`xclip failed: ${error.message}, trying wayland`)
+      return c.json(await wlGet())
+    }
+  } catch (error) {
+    debug(`Error in GET /clipboard: ${error.message}`)
+    return c.json({ type: 'text', text: '' })
+  }
+})
+
+clipboardRouter.post('/clipboard', async (c) => {
+  try {
+    debug('POST /clipboard request received')
+    const body = await c.req.json()
+    
+    // Try xclip first, fall back to wayland
+    try {
+      debug('Trying to set clipboard with xclip')
+      await xSet(body)
+    } catch (error) {
+      debug(`xclip set failed: ${error.message}, trying wayland`)
+      await wlSet(body)
+    }
+    
+    return c.json({ ok: true })
+  } catch (e) {
+    debug(`Error in POST /clipboard: ${e.message}`)
+    return c.json({ message: String(e.message) }, 400)
+  }
+})
+
+clipboardRouter.get('/clipboard/stream', async (c) => {
+  debug('GET /clipboard/stream request received')
+  // simple poller
+  let lastText = ''
+  const stream = new ReadableStream({
+    async start(controller) {
+      const enc = new TextEncoder()
+      const loop = async () => {
+        try {
+          let res = { type: 'text', text: '' }
+          
+          // Try xclip first, fall back to wayland
+          try {
+            res = await xGet()
+          } catch {
+            try {
+              res = await wlGet()
+            } catch (error) {
+              debug(`Both clipboard methods failed: ${error.message}`)
+            }
+          }
+          
+          const curr = res.type === 'text' ? res.text : res.image_b64?.slice(0, 16) || ''
+          if (curr !== lastText) {
+            lastText = curr
+            debug(`Clipboard content changed, sending update: ${res.type}`)
+            controller.enqueue(enc.encode(`event: data\ndata: ${JSON.stringify({ ts: new Date().toISOString(), type: res.type, preview: res.type === 'text' ? (res.text || '').slice(0, 100) : 'image...' })}\n\n`))
+          }
+        } catch (error) {
+          debug(`Error in clipboard stream: ${error.message}`)
+        }
+        setTimeout(loop, 1000)
+      }
+      loop()
+    },
+    cancel() {
+      debug('Clipboard stream cancelled')
+    }
+  })
+  return new Response(stream, { headers: { ...{ 'Cache-Control': 'no-cache' }, ...{ 'Content-Type': 'text/event-stream' }, 'X-SSE-Content-Type': 'application/json' } })
+})
diff --git a/operator-api/src/routes/fs.js b/operator-api/src/routes/fs.js
new file mode 100644
index 00000000..4a38252b
--- /dev/null
+++ b/operator-api/src/routes/fs.js
@@ -0,0 +1,192 @@
+import fs from 'node:fs'
+import path from 'node:path'
+import { Hono } from 'hono'
+import { DATA_DIR } from '../utils/env.js'
+import { b64 } from '../utils/base64.js'
+import { sseHeaders, sseFormat } from '../utils/sse.js'
+import chokidar from 'chokidar'
+import { uid } from '../utils/ids.js'
+
+export const fsRouter = new Hono()
+
+function ok(c) { return c.json({ ok: true }) }
+
+fsRouter.get('/fs/read_file', async (c) => {
+  const p = c.req.query('path')
+  if (!p || !p.startsWith('/')) return c.json({ message: 'Invalid path' }, 400)
+  if (!fs.existsSync(p)) return c.json({ message: 'Not Found' }, 404)
+  const stream = fs.createReadStream(p)
+  return new Response(stream, { status: 200, headers: { 'Content-Type': 'application/octet-stream' } })
+})
+
+fsRouter.put('/fs/write_file', async (c) => {
+  const url = new URL(c.req.url)
+  const p = url.searchParams.get('path')
+  const mode = url.searchParams.get('mode') || '0644'
+  if (!p || !p.startsWith('/')) return c.json({ message: 'Invalid path' }, 400)
+  const buf = Buffer.from(await c.req.arrayBuffer())
+  fs.mkdirSync(path.dirname(p), { recursive: true })
+  fs.writeFileSync(p, buf, { mode: parseInt(mode, 8) })
+  return c.json({ ok: true }, 201)
+})
+
+fsRouter.get('/fs/list_files', async (c) => {
+  const p = c.req.query('path')
+  if (!p || !p.startsWith('/')) return c.json({ message: 'Invalid path' }, 400)
+  if (!fs.existsSync(p)) return c.json({ message: 'Not Found' }, 404)
+  const names = fs.readdirSync(p)
+  const items = names.map((name) => {
+    const fp = path.join(p, name)
+    const st = fs.statSync(fp)
+    return {
+      name, path: fp, size_bytes: st.isDirectory() ? 0 : st.size,
+      is_dir: st.isDirectory(),
+      mod_time: st.mtime.toISOString(),
+      mode: (st.mode & 0o7777).toString(8)
+    }
+  })
+  return c.json(items)
+})
+
+fsRouter.put('/fs/create_directory', async (c) => {
+  const body = await c.req.json()
+  const p = body?.path
+  const mode = body?.mode ? parseInt(body.mode, 8) : 0o755
+  if (!p || !p.startsWith('/')) return c.json({ message: 'Invalid path' }, 400)
+  fs.mkdirSync(p, { recursive: true, mode })
+  return c.json({ ok: true }, 201)
+})
+
+fsRouter.put('/fs/delete_file', async (c) => {
+  const body = await c.req.json()
+  const p = body?.path
+  if (!p || !p.startsWith('/')) return c.json({ message: 'Invalid path' }, 400)
+  if (!fs.existsSync(p)) return c.json({ message: 'Not Found' }, 404)
+  const st = fs.statSync(p)
+  if (st.isDirectory()) return c.json({ message: 'Is directory' }, 400)
+  fs.rmSync(p, { force: true })
+  return ok(c)
+})
+
+fsRouter.put('/fs/delete_directory', async (c) => {
+  const body = await c.req.json()
+  const p = body?.path
+  if (!p || !p.startsWith('/')) return c.json({ message: 'Invalid path' }, 400)
+  fs.rmSync(p, { recursive: true, force: true })
+  return ok(c)
+})
+
+fsRouter.put('/fs/set_file_permissions', async (c) => {
+  const body = await c.req.json()
+  const p = body?.path
+  if (!p || !p.startsWith('/')) return c.json({ message: 'Invalid path' }, 400)
+  if (!fs.existsSync(p)) return c.json({ message: 'Not Found' }, 404)
+  if (body.mode) fs.chmodSync(p, parseInt(body.mode, 8))
+  if (body.owner || body.group) {
+    try {
+      const uid = body.owner ? Number.isNaN(Number(body.owner)) ? process.getuid?.() : Number(body.owner) : undefined
+      const gid = body.group ? Number.isNaN(Number(body.group)) ? process.getgid?.() : Number(body.group) : undefined
+      if (uid !== undefined || gid !== undefined) fs.chownSync(p, uid ?? fs.statSync(p).uid, gid ?? fs.statSync(p).gid)
+    } catch {}
+  }
+  return ok(c)
+})
+
+fsRouter.get('/fs/file_info', async (c) => {
+  const p = c.req.query('path')
+  if (!p || !p.startsWith('/')) return c.json({ message: 'Invalid path' }, 400)
+  if (!fs.existsSync(p)) return c.json({ message: 'Not Found' }, 404)
+  const st = fs.statSync(p)
+  return c.json({
+    name: path.basename(p),
+    path: p,
+    size_bytes: st.isDirectory() ? 0 : st.size,
+    is_dir: st.isDirectory(),
+    mod_time: st.mtime.toISOString(),
+    mode: (st.isDirectory() ? 'd' : '-') + (st.mode & 0o777).toString(8)
+  })
+})
+
+fsRouter.put('/fs/move', async (c) => {
+  const body = await c.req.json()
+  if (!body?.src_path || !body?.dest_path) return c.json({ message: 'Missing paths' }, 400)
+  fs.mkdirSync(path.dirname(body.dest_path), { recursive: true })
+  fs.renameSync(body.src_path, body.dest_path)
+  return ok(c)
+})
+
+const watches = new Map() // id -> {watcher, path}
+fsRouter.post('/fs/watch', async (c) => {
+  const body = await c.req.json()
+  if (!body?.path) return c.json({ message: 'Missing path' }, 400)
+  const id = uid()
+  const watcher = chokidar.watch(body.path, { ignoreInitial: true, persistent: true, depth: body.recursive ? undefined : 0 })
+  watches.set(id, { watcher, path: body.path })
+  return c.json({ watch_id: id }, 201)
+})
+
+fsRouter.get('/fs/watch/:watch_id/events', async (c) => {
+  const id = c.req.param('watch_id')
+  const item = watches.get(id)
+  if (!item) return c.json({ message: 'Not Found' }, 404)
+  const { watcher } = item
+  const stream = new ReadableStream({
+    start(controller) {
+      const send = (type, p, is_dir) => controller.enqueue(new TextEncoder().encode(`event: data\ndata: ${JSON.stringify({ type, name: p.split('/').pop(), path: p, is_dir })}\n\n`))
+      watcher.on('add', (p) => send('CREATE', p, false))
+      watcher.on('addDir', (p) => send('CREATE', p, true))
+      watcher.on('change', (p) => send('WRITE', p, false))
+      watcher.on('unlink', (p) => send('DELETE', p, false))
+      watcher.on('unlinkDir', (p) => send('DELETE', p, true))
+    },
+    cancel() {}
+  })
+  return new Response(stream, { headers: { 'Content-Type': 'text/event-stream', 'Cache-Control': 'no-cache', Connection: 'keep-alive', 'X-SSE-Content-Type': 'application/json' } })
+})
+
+fsRouter.delete('/fs/watch/:watch_id', async (c) => {
+  const id = c.req.param('watch_id')
+  const item = watches.get(id)
+  if (!item) return c.json({ message: 'Not Found' }, 404)
+  await item.watcher.close()
+  watches.delete(id)
+  return new Response(null, { status: 204 })
+})
+
+fsRouter.post('/fs/upload', async (c) => {
+  const form = await c.req.parseBody()
+  const pathDest = form['path']
+  const file = form['file']
+  if (!pathDest || !file) return c.json({ message: 'Missing fields' }, 400)
+  const buf = Buffer.from(await file.arrayBuffer())
+  fs.mkdirSync(path.dirname(pathDest), { recursive: true })
+  fs.writeFileSync(pathDest, buf)
+  return c.json({ path: pathDest, size_bytes: buf.length })
+})
+
+fsRouter.get('/fs/download', async (c) => {
+  const p = c.req.query('path')
+  if (!p || !fs.existsSync(p)) return c.json({ message: 'Not Found' }, 404)
+  const stream = fs.createReadStream(p)
+  return new Response(stream, { headers: { 'Content-Type': 'application/octet-stream' } })
+})
+
+fsRouter.get('/fs/tail/stream', async (c) => {
+  const p = c.req.query('path')
+  if (!p || !fs.existsSync(p)) return c.json({ message: 'Not Found' }, 404)
+  const { spawn } = await import('node:child_process')
+  const proc = spawn('tail', ['-n', '0', '-F', p])
+  const stream = new ReadableStream({
+    start(controller) {
+      proc.stdout.on('data', (d) => {
+        const lines = d.toString('utf8').split('\n').filter(Boolean)
+        for (const line of lines) controller.enqueue(new TextEncoder().encode(`event: data\ndata: ${JSON.stringify({ line, ts: new Date().toISOString() })}\n\n`))
+      })
+      proc.on('close', () => controller.close())
+    },
+    cancel() {
+      proc.kill('SIGINT')
+    }
+  })
+  return new Response(stream, { headers: sseHeaders() })
+})
diff --git a/operator-api/src/routes/health.js b/operator-api/src/routes/health.js
new file mode 100644
index 00000000..18dce50b
--- /dev/null
+++ b/operator-api/src/routes/health.js
@@ -0,0 +1,6 @@
+import { Hono } from 'hono'
+export const healthRouter = new Hono()
+const start = Date.now()
+healthRouter.get('/health', async (c) => {
+  return c.json({ status: 'ok', uptime_sec: Math.round((Date.now() - start) / 1000) })
+})
diff --git a/operator-api/src/routes/input.js b/operator-api/src/routes/input.js
new file mode 100644
index 00000000..05d26bd8
--- /dev/null
+++ b/operator-api/src/routes/input.js
@@ -0,0 +1,606 @@
+// src/routes/input.js
+import 'dotenv/config'
+import { Hono } from 'hono'
+import { execCapture } from '../utils/exec.js'
+
+export const inputRouter = new Hono()
+
+const display = process.env.DISPLAY || ':0'
+const XDOTOOL = process.env.XDOTOOL_BIN || '/usr/bin/xdotool'
+
+// ---------- helpers ----------
+function asString(v, fallback = '') {
+  if (v === undefined || v === null) return fallback
+  return String(v)
+}
+
+
+
+async function runXdotool(args) {
+  const res = await execCapture(XDOTOOL, args, { env: { ...process.env, DISPLAY: display } })
+  if (res.code !== 0) throw new Error(res.stderr.toString('utf8') || 'xdotool error')
+  return res
+}
+
+function parseFirstId(stdout) {
+  return stdout.toString('utf8').split('\n').filter(Boolean)[0]
+}
+
+function matchToSearchArgs(match) {
+  const args = ['search']
+  if (match && match.only_visible) args.push('--onlyvisible')
+  if (match && (match.title_contains || match.name)) {
+    args.push('--name', match.title_contains ?? match.name)
+  }
+  if (match && match.class) args.push('--class', match.class)
+  if (match && match.pid) args.push('--pid', String(match.pid))
+  if (args.length === 1) args.push('--onlyvisible', '.')
+  return args
+}
+
+async function findWindowId(match) {
+  const found = await execCapture('xdotool', matchToSearchArgs(match))
+  const wid = parseFirstId(found.stdout)
+  return wid || undefined
+}
+
+
+async function findWindowIdsMultiple(match) {
+  const found = await execCapture('xdotool', matchToSearchArgs(match))
+  const stdout = found.stdout.toString('utf8')
+  const windowIds = stdout.split('\n').filter(Boolean)
+  return windowIds.length > 0 ? windowIds : []
+}
+
+
+function buttonNumFromName(name) {
+  if (typeof name === 'number') return String(name)
+  const map = { left: 1, middle: 2, right: 3, back: 8, forward: 9 }
+  return String(map[String(name)] ?? 1)
+}
+
+// ---------- mouse ----------
+inputRouter.post('/input/mouse/move', async (c) => {
+  try {
+    const { x, y } = await c.req.json()
+    if (typeof x !== 'number' || typeof y !== 'number') return c.json({ message: 'Invalid coords' }, 400)
+    await runXdotool(['mousemove', String(x), String(y)])
+    return c.json({ ok: true })
+  } catch (e) {
+    return c.json({ message: String(e.message) }, 400)
+  }
+})
+
+inputRouter.post('/input/mouse/move_relative', async (c) => {
+  try {
+    const { dx = 0, dy = 0 } = await c.req.json()
+    await runXdotool(['mousemove_relative', '--', String(dx), String(dy)])
+    return c.json({ ok: true })
+  } catch (e) {
+    return c.json({ message: String(e.message) }, 400)
+  }
+})
+
+inputRouter.post('/input/mouse/click', async (c) => {
+  try {
+    const body = await c.req.json()
+    const button = buttonNumFromName(body.button)
+    const count = body.count ?? body.num_clicks ?? 1
+    await runXdotool(['click', '--repeat', String(count), button])
+    return c.json({ ok: true })
+  } catch (e) {
+    return c.json({ message: String(e.message) }, 400)
+  }
+})
+
+inputRouter.post('/input/mouse/down', async (c) => {
+  try {
+    const { button } = await c.req.json()
+    await runXdotool(['mousedown', buttonNumFromName(button)])
+    return c.json({ ok: true })
+  } catch (e) {
+    return c.json({ message: String(e.message) }, 400)
+  }
+})
+
+inputRouter.post('/input/mouse/up', async (c) => {
+  try {
+    const { button } = await c.req.json()
+    await runXdotool(['mouseup', buttonNumFromName(button)])
+    return c.json({ ok: true })
+  } catch (e) {
+    return c.json({ message: String(e.message) }, 400)
+  }
+})
+
+inputRouter.post('/input/mouse/scroll', async (c) => {
+  try {
+    const { dx = 0, dy = -120 } = await c.req.json()
+    const verticalClicks = Math.max(1, Math.round(Math.abs(dy) / 120))
+    const horizontalClicks = Math.max(0, Math.round(Math.abs(dx) / 120))
+    const vButton = dy < 0 ? '5' : '4'
+    const hButton = dx > 0 ? '7' : '6'
+    for (let i = 0; i < verticalClicks; i++) await runXdotool(['click', vButton])
+    for (let i = 0; i < horizontalClicks; i++) await runXdotool(['click', hButton])
+    return c.json({ ok: true })
+  } catch (e) {
+    return c.json({ message: String(e.message) }, 400)
+  }
+})
+
+inputRouter.get('/input/mouse/location', async (c) => {
+  try {
+    const res = await runXdotool(['getmouselocation', '--shell'])
+    const out = res.stdout.toString('utf8').trim().split('\n')
+    const kv = {}
+    for (const line of out) {
+      const [k, v] = line.split('=')
+      kv[k] = v
+    }
+    return c.json({
+      x: Number(kv['X']),
+      y: Number(kv['Y']),
+      screen: Number(kv['SCREEN']),
+      window: asString(kv['WINDOW']),
+    })
+  } catch (e) {
+    return c.json({ message: String(e.message) }, 400)
+  }
+})
+
+// ---------- keyboard ----------
+inputRouter.post('/input/keyboard/type', async (c) => {
+  try {
+    const { text, wpm = 300, enter = false } = await c.req.json()
+    if (typeof text !== 'string') return c.json({ message: 'Missing text' }, 400)
+    const delay = Math.max(1, Math.round(60000 / (wpm * 5)))
+    await runXdotool(['type', '--delay', String(delay), '--clearmodifiers', '--', text])
+    if (enter) await runXdotool(['key', 'Return'])
+    return c.json({ ok: true })
+  } catch (e) {
+    return c.json({ message: String(e.message) }, 400)
+  }
+})
+
+inputRouter.post('/input/keyboard/key', async (c) => {
+  try {
+    const { keys } = await c.req.json()
+    const seq = Array.isArray(keys) ? keys : [asString(keys)]
+    if (!seq.length || !seq[0]) return c.json({ message: 'Missing keys' }, 400)
+    await runXdotool(['key', ...seq])
+    return c.json({ ok: true })
+  } catch (e) {
+    return c.json({ message: String(e.message) }, 400)
+  }
+})
+
+inputRouter.post('/input/keyboard/key_down', async (c) => {
+  try {
+    const { key } = await c.req.json()
+    await runXdotool(['keydown', key])
+    return c.json({ ok: true })
+  } catch (e) {
+    return c.json({ message: String(e.message) }, 400)
+  }
+})
+
+inputRouter.post('/input/keyboard/key_up', async (c) => {
+  try {
+    const { key } = await c.req.json()
+    await runXdotool(['keyup', key])
+    return c.json({ ok: true })
+  } catch (e) {
+    return c.json({ message: String(e.message) }, 400)
+  }
+})
+
+// ---------- windows ----------
+inputRouter.post('/input/window/activate', async (c) => {
+  try {
+    const { match } = await c.req.json()
+    const wid = await findWindowId(match)
+    if (!wid) return c.json({ activated: false })
+    await runXdotool(['windowactivate', wid])
+    return c.json({ activated: true, wid })
+  } catch {
+    return c.json({ activated: false })
+  }
+})
+
+inputRouter.post('/input/window/focus', async (c) => {
+  try {
+    const { match } = await c.req.json()
+    const wid = await findWindowId(match)
+    if (!wid) return c.json({ focused: false })
+    await runXdotool(['windowfocus', wid])
+    return c.json({ focused: true, wid })
+  } catch {
+    return c.json({ focused: false })
+  }
+})
+
+inputRouter.post('/input/window/move_resize', async (c) => {
+  try {
+    const { match, x, y, width, height } = await c.req.json()
+    const wid = await findWindowId(match)
+    if (!wid) return c.json({ message: 'Not Found' }, 404)
+    if (x !== undefined && y !== undefined) await runXdotool(['windowmove', wid, String(x), String(y)])
+    if (width !== undefined && height !== undefined) await runXdotool(['windowsize', wid, String(width), String(height)])
+    return c.json({ ok: true, wid })
+  } catch (e) {
+    return c.json({ message: String(e.message) }, 400)
+  }
+})
+
+inputRouter.post('/input/window/raise', async (c) => {
+  try {
+    const { match } = await c.req.json()
+    const wid = await findWindowId(match)
+    if (!wid) return c.json({ message: 'Not Found' }, 404)
+    await runXdotool(['windowraise', wid])
+    return c.json({ ok: true, wid })
+  } catch (e) {
+    return c.json({ message: String(e.message) }, 400)
+  }
+})
+
+inputRouter.post('/input/window/minimize', async (c) => {
+  try {
+    const { match } = await c.req.json()
+    const wid = await findWindowId(match)
+    if (!wid) return c.json({ message: 'Not Found' }, 404)
+    await runXdotool(['windowminimize', wid])
+    return c.json({ ok: true, wid })
+  } catch (e) {
+    return c.json({ message: String(e.message) }, 400)
+  }
+})
+
+inputRouter.post('/input/window/map', async (c) => {
+  try {
+    const { match } = await c.req.json()
+    const wid = await findWindowId(match)
+    if (!wid) return c.json({ message: 'Not Found' }, 404)
+    await runXdotool(['windowmap', wid])
+    return c.json({ ok: true, wid })
+  } catch (e) {
+    return c.json({ message: String(e.message) }, 400)
+  }
+})
+
+inputRouter.post('/input/window/unmap', async (c) => {
+  try {
+    const { match } = await c.req.json()
+    const wid = await findWindowId(match)
+    if (!wid) return c.json({ message: 'Not Found' }, 404)
+    await runXdotool(['windowunmap', wid])
+    return c.json({ ok: true, wid })
+  } catch (e) {
+    return c.json({ message: String(e.message) }, 400)
+  }
+})
+
+inputRouter.post('/input/window/close', async (c) => {
+  try {
+    const { match } = await c.req.json()
+    // Note: Using findWindowIdsMultiple instead of findWindowId to close multiple windows
+    const windowIds = await findWindowIdsMultiple(match)
+    if (windowIds.length === 0) return c.json({ message: 'Not Found' }, 404)
+    
+    for (const wid of windowIds) {
+      await runXdotool(['windowclose', wid])
+    }
+    
+    return c.json({ ok: true, windowIds })
+  } catch (e) {
+    return c.json({ message: String(e.message) }, 400)
+  }
+})
+
+// Original version that only closes a single window
+// inputRouter.post('/input/window/close', async (c) => {
+//   try {
+//     const { match } = await c.req.json()
+//     const wid = await findWindowId(match)
+//     if (!wid) return c.json({ message: 'Not Found' }, 404)
+//     await runXdotool(['windowclose', wid])
+//     return c.json({ ok: true, wid })
+//   } catch (e) {
+//     return c.json({ message: String(e.message) }, 400)
+//   }
+// })
+
+inputRouter.post('/input/window/kill', async (c) => {
+  try {
+    const { match } = await c.req.json()
+    const wid = await findWindowId(match)
+    if (!wid) return c.json({ message: 'Not Found' }, 404)
+    await runXdotool(['windowkill', wid])
+    return c.json({ ok: true, wid })
+  } catch (e) {
+    return c.json({ message: String(e.message) }, 400)
+  }
+})
+
+inputRouter.get('/input/window/active', async (c) => {
+  try {
+    const res = await runXdotool(['getactivewindow'])
+    return c.json({ wid: parseFirstId(res.stdout) })
+  } catch (e) {
+    return c.json({ message: String(e.message) }, 400)
+  }
+})
+
+inputRouter.get('/input/window/focused', async (c) => {
+  try {
+    const res = await runXdotool(['getwindowfocus'])
+    return c.json({ wid: parseFirstId(res.stdout) })
+  } catch (e) {
+    return c.json({ message: String(e.message) }, 400)
+  }
+})
+
+inputRouter.post('/input/window/name', async (c) => {
+  try {
+    const { wid } = await c.req.json()
+    if (!wid) return c.json({ message: 'Missing wid' }, 400)
+    const res = await runXdotool(['getwindowname', String(wid)])
+    return c.json({ wid, name: res.stdout.toString('utf8').trim() })
+  } catch (e) {
+    return c.json({ message: String(e.message) }, 400)
+  }
+})
+
+inputRouter.post('/input/window/pid', async (c) => {
+  try {
+    const { wid } = await c.req.json()
+    if (!wid) return c.json({ message: 'Missing wid' }, 400)
+    const res = await runXdotool(['getwindowpid', String(wid)])
+    return c.json({ wid, pid: Number(res.stdout.toString('utf8').trim()) })
+  } catch (e) {
+    return c.json({ message: String(e.message) }, 400)
+  }
+})
+
+inputRouter.post('/input/window/geometry', async (c) => {
+  try {
+    const { wid } = await c.req.json()
+    if (!wid) return c.json({ message: 'Missing wid' }, 400)
+    const res = await runXdotool(['getwindowgeometry', '--shell', String(wid)])
+    const out = res.stdout.toString('utf8').trim().split('\n')
+    const kv = {}
+    for (const line of out) {
+      const [k, v] = line.split('=')
+      kv[k] = v
+    }
+    return c.json({
+      wid,
+      x: Number(kv['X']),
+      y: Number(kv['Y']),
+      width: Number(kv['WIDTH']),
+      height: Number(kv['HEIGHT']),
+      screen: Number(kv['SCREEN']),
+    })
+  } catch (e) {
+    return c.json({ message: String(e.message) }, 400)
+  }
+})
+
+// ---------- desktop / screen ----------
+inputRouter.get('/input/display/geometry', async (c) => {
+  try {
+    const res = await runXdotool(['getdisplaygeometry'])
+    const [widthStr, heightStr] = res.stdout.toString('utf8').trim().split(' ')
+    return c.json({ width: Number(widthStr), height: Number(heightStr) })
+  } catch (e) {
+    return c.json({ message: String(e.message) }, 400)
+  }
+})
+
+inputRouter.get('/input/desktop/count', async (c) => {
+  try {
+    const res = await runXdotool(['get_num_desktops'])
+    return c.json({ count: Number(res.stdout.toString('utf8').trim()) })
+  } catch (e) {
+    return c.json({ message: String(e.message) }, 400)
+  }
+})
+
+inputRouter.post('/input/desktop/count', async (c) => {
+  try {
+    const { count } = await c.req.json()
+    await runXdotool(['set_num_desktops', String(count)])
+    return c.json({ ok: true, count })
+  } catch (e) {
+    return c.json({ message: String(e.message) }, 400)
+  }
+})
+
+inputRouter.get('/input/desktop/current', async (c) => {
+  try {
+    const res = await runXdotool(['get_desktop'])
+    return c.json({ index: Number(res.stdout.toString('utf8').trim()) })
+  } catch (e) {
+    return c.json({ message: String(e.message) }, 400)
+  }
+})
+
+inputRouter.post('/input/desktop/current', async (c) => {
+  try {
+    const { index } = await c.req.json()
+    await runXdotool(['set_desktop', String(index)])
+    return c.json({ ok: true, index })
+  } catch (e) {
+    return c.json({ message: String(e.message) }, 400)
+  }
+})
+
+inputRouter.post('/input/desktop/window_desktop', async (c) => {
+  try {
+    const { match, index } = await c.req.json()
+    const wid = await findWindowId(match)
+    if (!wid) return c.json({ message: 'Not Found' }, 404)
+    await runXdotool(['set_desktop_for_window', wid, String(index)])
+    return c.json({ ok: true, wid, index })
+  } catch (e) {
+    return c.json({ message: String(e.message) }, 400)
+  }
+})
+
+inputRouter.post('/input/desktop/viewport', async (c) => {
+  try {
+    const { x, y } = await c.req.json()
+    await runXdotool(['set_desktop_viewport', String(x), String(y)])
+    return c.json({ ok: true, x, y })
+  } catch (e) {
+    return c.json({ message: String(e.message) }, 400)
+  }
+})
+
+inputRouter.get('/input/desktop/viewport', async (c) => {
+  try {
+    const res = await runXdotool(['get_desktop_viewport'])
+    const [xStr, yStr] = res.stdout.toString('utf8').trim().split(' ')
+    return c.json({ x: Number(xStr), y: Number(yStr) })
+  } catch (e) {
+    return c.json({ message: String(e.message) }, 400)
+  }
+})
+
+// ---------- combos / convenience ----------
+inputRouter.post('/input/combo/activate_and_type', async (c) => {
+  try {
+    const { match, text, enter = false, wpm = 300 } = await c.req.json()
+    const wid = await findWindowId(match)
+    if (!wid) return c.json({ message: 'Not Found' }, 404)
+    await runXdotool(['windowactivate', wid])
+    const delay = Math.max(1, Math.round(60000 / (wpm * 5)))
+    await runXdotool(['type', '--delay', String(delay), '--clearmodifiers', '--', String(text ?? '')])
+    if (enter) await runXdotool(['key', 'Return'])
+    return c.json({ ok: true, wid })
+  } catch (e) {
+    return c.json({ message: String(e.message) }, 400)
+  }
+})
+
+inputRouter.post('/input/combo/activate_and_keys', async (c) => {
+  try {
+    const { match, keys } = await c.req.json()
+    const wid = await findWindowId(match)
+    if (!wid) return c.json({ message: 'Not Found' }, 404)
+    await runXdotool(['windowactivate', wid])
+    const seq = Array.isArray(keys) ? keys : [asString(keys)]
+    if (!seq.length || !seq[0]) return c.json({ message: 'Missing keys' }, 400)
+    await runXdotool(['key', ...seq])
+    return c.json({ ok: true, wid })
+  } catch (e) {
+    return c.json({ message: String(e.message) }, 400)
+  }
+})
+
+inputRouter.post('/input/combo/window/center', async (c) => {
+  try {
+    const { match, width, height } = await c.req.json()
+    const wid = await findWindowId(match)
+    if (!wid) return c.json({ message: 'Not Found' }, 404)
+
+    const disp = await runXdotool(['getdisplaygeometry'])
+    const [dw, dh] = disp.stdout.toString('utf8').trim().split(' ').map(Number)
+
+    let w = width, h = height
+    if (w === undefined || h === undefined) {
+      const geo = await runXdotool(['getwindowgeometry', '--shell', wid])
+      const lines = geo.stdout.toString('utf8').trim().split('\n')
+      const kv = {}
+      for (const line of lines) {
+        const [k, v] = line.split('=')
+        kv[k] = Number(v)
+      }
+      w = w ?? kv['WIDTH']
+      h = h ?? kv['HEIGHT']
+    }
+
+    const x = Math.max(0, Math.round((dw - Number(w)) / 2))
+    const y = Math.max(0, Math.round((dh - Number(h)) / 2))
+    await runXdotool(['windowmove', wid, String(x), String(y)])
+    if (width !== undefined && height !== undefined) {
+      await runXdotool(['windowsize', wid, String(width), String(height)])
+    }
+    return c.json({ ok: true, wid, x, y, width: Number(w), height: Number(h) })
+  } catch (e) {
+    return c.json({ message: String(e.message) }, 400)
+  }
+})
+
+inputRouter.post('/input/combo/window/snap', async (c) => {
+  try {
+    const { match, position } = await c.req.json()
+    const wid = await findWindowId(match)
+    if (!wid) return c.json({ message: 'Not Found' }, 404)
+
+    const disp = await runXdotool(['getdisplaygeometry'])
+    const [dw, dh] = disp.stdout.toString('utf8').trim().split(' ').map(Number)
+
+    let x = 0, y = 0, w = dw, h = dh
+    switch (position) {
+      case 'left': w = Math.floor(dw / 2); h = dh; x = 0; y = 0; break
+      case 'right': w = Math.floor(dw / 2); h = dh; x = dw - w; y = 0; break
+      case 'top': w = dw; h = Math.floor(dh / 2); x = 0; y = 0; break
+      case 'bottom': w = dw; h = Math.floor(dh / 2); x = 0; y = dh - h; break
+      case 'topleft': w = Math.floor(dw / 2); h = Math.floor(dh / 2); x = 0; y = 0; break
+      case 'topright': w = Math.floor(dw / 2); h = Math.floor(dh / 2); x = dw - w; y = 0; break
+      case 'bottomleft': w = Math.floor(dw / 2); h = Math.floor(dh / 2); x = 0; y = dh - h; break
+      case 'bottomright': w = Math.floor(dw / 2); h = Math.floor(dh / 2); x = dw - w; y = dh - h; break
+      case 'maximize': w = dw; h = dh; x = 0; y = 0; break
+      default: return c.json({ message: 'Invalid position' }, 400)
+    }
+    await runXdotool(['windowmove', wid, String(x), String(y)])
+    await runXdotool(['windowsize', wid, String(w), String(h)])
+    return c.json({ ok: true, wid, x, y, width: w, height: h })
+  } catch (e) {
+    return c.json({ message: String(e.message) }, 400)
+  }
+})
+
+// ---------- process / exec / sleep ----------
+inputRouter.post('/input/system/exec', async (c) => {
+  try {
+    const { command, args = [] } = await c.req.json()
+    if (!command) return c.json({ message: 'Missing command' }, 400)
+    const res = await execCapture(String(command), args.map(String))
+    return c.json({
+      code: res.code,
+      stdout: res.stdout.toString('utf8'),
+      stderr: res.stderr.toString('utf8'),
+    })
+  } catch (e) {
+    return c.json({ message: String(e.message) }, 400)
+  }
+})
+
+inputRouter.post('/input/system/sleep', async (c) => {
+  try {
+    const { seconds } = await c.req.json()
+    await runXdotool(['sleep', String(Number(seconds) || 0)])
+    return c.json({ ok: true })
+  } catch (e) {
+    return c.json({ message: String(e.message) }, 400)
+  }
+})
+
+// ---------- aliases for backward compat ----------
+inputRouter.post('/computer/move_mouse', async (c) => inputRouter.routes.get('/input/mouse/move')(c))
+inputRouter.post('/computer/click_mouse', async (c) => {
+  try {
+    const body = await c.req.json()
+    const button = buttonNumFromName(body.button)
+    const clickType = body.click_type || 'click'
+    const count = body.num_clicks || 1
+    if (clickType === 'down') await runXdotool(['mousedown', String(button)])
+    else if (clickType === 'up') await runXdotool(['mouseup', String(button)])
+    else await runXdotool(['click', '--repeat', String(count), String(button)])
+    return c.json({ ok: true })
+  } catch (e) {
+    return c.json({ message: String(e.message) }, 400)
+  }
+})
diff --git a/operator-api/src/routes/logs.js b/operator-api/src/routes/logs.js
new file mode 100644
index 00000000..0e27cb98
--- /dev/null
+++ b/operator-api/src/routes/logs.js
@@ -0,0 +1,36 @@
+import { Hono } from 'hono'
+import { spawn } from 'node:child_process'
+import { sseHeaders } from '../utils/sse.js'
+
+export const logsRouter = new Hono()
+
+logsRouter.get('/logs/stream', async (c) => {
+  const source = c.req.query('source')
+  const path = c.req.query('path')
+  const follow = c.req.query('follow') !== 'false'
+  let proc
+  if (source === 'path' && path) {
+    proc = spawn('tail', [follow ? '-F' : '-f', path])
+  } else if (source === 'kernel') {
+    proc = spawn('journalctl', ['-k', '-f'])
+  } else if (source === 'syslog') {
+    proc = spawn('journalctl', ['-f'])
+  } else if (source === 'application') {
+    proc = spawn('journalctl', ['-f', '-t', 'application'])
+  } else {
+    return c.json({ message: 'Bad Request' }, 400)
+  }
+  const stream = new ReadableStream({
+    start(controller) {
+      proc.stdout.on('data', (d) => {
+        const lines = d.toString('utf8').split('\n').filter(Boolean)
+        for (const line of lines) controller.enqueue(new TextEncoder().encode(`event: data\ndata: ${JSON.stringify({ source, line, ts: new Date().toISOString() })}\n\n`))
+      })
+      proc.on('close', () => controller.close())
+    },
+    cancel() {
+      proc.kill('SIGINT')
+    }
+  })
+  return new Response(stream, { headers: sseHeaders() })
+})
diff --git a/operator-api/src/routes/macros.js b/operator-api/src/routes/macros.js
new file mode 100644
index 00000000..1ab6f185
--- /dev/null
+++ b/operator-api/src/routes/macros.js
@@ -0,0 +1,50 @@
+import { Hono } from 'hono'
+import { uid } from '../utils/ids.js'
+import { execCapture } from '../utils/exec.js'
+import 'dotenv/config'
+
+const macros = new Map() // id -> {name, steps}
+const display = process.env.DISPLAY || ':0'
+const XDOTOOL = process.env.XDOTOOL_BIN || '/usr/bin/xdotool'
+
+export const macrosRouter = new Hono()
+
+async function runXdotool(args) {
+  const res = await execCapture(XDOTOOL, args, { env: { ...process.env, DISPLAY: display } })
+  if (res.code !== 0) throw new Error(res.stderr.toString('utf8') || 'xdotool error')
+  return res
+}
+
+macrosRouter.post('/macros/create', async (c) => {
+  const body = await c.req.json()
+  if (!body?.name || !Array.isArray(body.steps)) return c.json({ message: 'Bad Request' }, 400)
+  const id = uid()
+  macros.set(id, { macro_id: id, name: body.name, steps: body.steps })
+  return c.json({ macro_id: id })
+})
+
+macrosRouter.post('/macros/run', async (c) => {
+  const body = await c.req.json()
+  const item = [...macros.values()].find((m) => m.macro_id === body.macro_id)
+  if (!item) return c.json({ message: 'Not Found' }, 404)
+  const run_id = uid()
+    ; (async () => {
+      for (const step of item.steps) {
+        if (step.action === 'keyboard.type' && step.text) await runXdotool(['type', '--clearmodifiers', '--', step.text])
+        else if (step.action === 'keyboard.key' && step.key) await runXdotool(['key', step.key])
+        else if (step.action === 'sleep' && step.ms) await runXdotool(['sleep', String(step.ms / 1000)])
+      }
+    })()
+  return c.json({ started: true, run_id })
+})
+
+macrosRouter.get('/macros/list', async (c) => {
+  return c.json({ items: [...macros.values()].map((m) => ({ macro_id: m.macro_id, name: m.name, steps_count: m.steps.length })) })
+})
+
+macrosRouter.delete('/macros/:macro_id', async (c) => {
+  const id = c.req.param('macro_id')
+  if (!macros.has(id)) return c.json({ message: 'Not Found' }, 404)
+  macros.delete(id)
+  return c.json({ ok: true })
+})
\ No newline at end of file
diff --git a/operator-api/src/routes/metrics.js b/operator-api/src/routes/metrics.js
new file mode 100644
index 00000000..a3c1b6a3
--- /dev/null
+++ b/operator-api/src/routes/metrics.js
@@ -0,0 +1,34 @@
+import { Hono } from 'hono'
+import os from 'node:os'
+import pidusage from 'pidusage'
+import { sseHeaders, sseFormat } from '../utils/sse.js'
+
+export const metricsRouter = new Hono()
+
+function snapshot() {
+  const memUsed = os.totalmem() - os.freemem()
+  return {
+    cpu_pct: 0,
+    gpu_pct: 0,
+    mem: { used_bytes: memUsed, total_bytes: os.totalmem() },
+    disk: { read_bps: 0, write_bps: 0 },
+    net: { rx_bps: 0, tx_bps: 0 }
+  }
+}
+
+metricsRouter.get('/metrics/snapshot', async (c) => {
+  return c.json(snapshot())
+})
+
+metricsRouter.get('/metrics/stream', async (c) => {
+  const stream = new ReadableStream({
+    start(controller) {
+      const enc = new TextEncoder()
+      const iv = setInterval(() => {
+        controller.enqueue(enc.encode(sseFormat({ ts: new Date().toISOString(), ...snapshot() })))
+      }, 1000)
+    },
+    cancel() {}
+  })
+  return new Response(stream, { headers: sseHeaders() })
+})
diff --git a/operator-api/src/routes/network.js b/operator-api/src/routes/network.js
new file mode 100644
index 00000000..b0508d27
--- /dev/null
+++ b/operator-api/src/routes/network.js
@@ -0,0 +1,82 @@
+import { Hono } from 'hono'
+// import { startSocks, stopSocks } from '../services/socksService.js'
+import { applyRules, deleteRuleSet, harStreamEmitter } from '../services/interceptService.js'
+import { addForward, removeForward } from '../services/forwardService.js'
+import { sseHeaders, sseFormat } from '../utils/sse.js'
+
+export const networkRouter = new Hono()
+
+console.warn(`[operator-api/src/routes/network.js] : disabled socks5 endpoints + removed socks5 package for now (build crashes kernel container)`)
+
+/*
+networkRouter.post('/network/proxy/socks5/start', async (c) => {
+  try {
+    const body = await c.req.json()
+    const { proxy_id, url } = startSocks(body)
+    return c.json({ proxy_id, url })
+  } catch (e) {
+    return c.json({ message: String(e.message) }, 400)
+  }
+})
+
+networkRouter.post('/network/proxy/socks5/stop', async (c) => {
+  try {
+    const body = await c.req.json()
+    stopSocks(body)
+    return c.json({ ok: true })
+  } catch (e) {
+    return c.json({ message: String(e.message) }, 404)
+  }
+})
+*/
+
+networkRouter.post('/network/intercept/rules', async (c) => {
+  try {
+    const body = await c.req.json()
+    const res = applyRules(body)
+    return c.json(res)
+  } catch (e) {
+    return c.json({ message: String(e.message) }, 400)
+  }
+})
+
+networkRouter.delete('/network/intercept/rules/:rule_set_id', async (c) => {
+  try {
+    deleteRuleSet({ rule_set_id: c.req.param('rule_set_id') })
+    return c.json({ ok: true })
+  } catch (e) {
+    return c.json({ message: String(e.message) }, 404)
+  }
+})
+
+networkRouter.get('/network/har/stream', async (c) => {
+  const em = harStreamEmitter()
+  const stream = new ReadableStream({
+    start(controller) {
+      const handler = (obj) => controller.enqueue(new TextEncoder().encode(sseFormat(obj)))
+      em.on('har', handler)
+    },
+    cancel() {}
+  })
+  return new Response(stream, { headers: sseHeaders() })
+})
+
+networkRouter.post('/network/forward', async (c) => {
+  try {
+    const body = await c.req.json()
+    const res = addForward(body)
+    return c.json(res)
+  } catch (e) {
+    return c.json({ message: String(e.message) }, 400)
+  }
+})
+
+networkRouter.delete('/network/forward/:forward_id', async (c) => {
+  try {
+    const id = c.req.param('forward_id')
+    removeForward({ forward_id: id })
+    return c.json({ ok: true })
+  } catch (e) {
+    return c.json({ message: String(e.message) }, 404)
+  }
+})
diff --git a/operator-api/src/routes/os.js b/operator-api/src/routes/os.js
new file mode 100644
index 00000000..5a90ed02
--- /dev/null
+++ b/operator-api/src/routes/os.js
@@ -0,0 +1,21 @@
+import 'dotenv/config'
+import { Hono } from 'hono'
+
+export const osRouter = new Hono()
+
+osRouter.get('/os/locale', async (c) => {
+  const locale = process.env.LANG || 'en_US.UTF-8'
+  const keyboard_layout = process.env.XKB_DEFAULT_LAYOUT || 'us'
+  const timezone = process.env.TZ || 'UTC'
+  return c.json({ locale, keyboard_layout, timezone })
+})
+
+osRouter.post('/os/locale', async (c) => {
+  const body = await c.req.json()
+  const locale = body?.locale || process.env.LANG
+  const keyboard_layout = body?.keyboard_layout || 'us'
+  const timezone = body?.timezone || 'UTC'
+  process.env.LANG = locale
+  process.env.TZ = timezone
+  return c.json({ updated: true, requires_restart: false })
+})
diff --git a/operator-api/src/routes/pipe.js b/operator-api/src/routes/pipe.js
new file mode 100644
index 00000000..aa18922d
--- /dev/null
+++ b/operator-api/src/routes/pipe.js
@@ -0,0 +1,31 @@
+import { Hono } from 'hono'
+import { EventEmitter } from 'node:events'
+import { sseHeaders, sseFormat } from '../utils/sse.js'
+
+const channels = new Map() // name -> emitter
+
+function getEmitter(name) {
+  if (!channels.has(name)) channels.set(name, new EventEmitter())
+  return channels.get(name)
+}
+
+export const pipeRouter = new Hono()
+
+pipeRouter.post('/pipe/send', async (c) => {
+  const body = await c.req.json()
+  const ch = getEmitter(body.channel || 'default')
+  ch.emit('msg', { ts: new Date().toISOString(), object: body.object })
+  return c.json({ enqueued: true })
+})
+
+pipeRouter.get('/pipe/recv/stream', async (c) => {
+  const chName = c.req.query('channel') || 'default'
+  const ch = getEmitter(chName)
+  const stream = new ReadableStream({
+    start(controller) {
+      const h = (obj) => controller.enqueue(new TextEncoder().encode(sseFormat(obj)))
+      ch.on('msg', h)
+    }
+  })
+  return new Response(stream, { headers: sseHeaders() })
+})
diff --git a/operator-api/src/routes/process.js b/operator-api/src/routes/process.js
new file mode 100644
index 00000000..4bf3f4ec
--- /dev/null
+++ b/operator-api/src/routes/process.js
@@ -0,0 +1,92 @@
+import 'dotenv/config'
+import { Hono } from 'hono'
+import { spawn } from 'node:child_process'
+import { b64, fromB64 } from '../utils/base64.js'
+import { uid } from '../utils/ids.js'
+import { sseHeaders } from '../utils/sse.js'
+
+const procs = new Map() // id -> {proc, started_at}
+
+export const processRouter = new Hono()
+
+function toEnv(obj) {
+  const env = { ...process.env }
+  for (const k of Object.keys(obj || {})) env[k] = String(obj[k])
+  return env
+}
+
+processRouter.post('/process/exec', async (c) => {
+  try {
+    const body = await c.req.json()
+    const { command, args = [], cwd, env = {}, as_root = false, timeout_sec = null, stream = false, as_user } = body
+    if (!command) return c.json({ message: 'Missing command' }, 400)
+    const child = spawn(command, args, { cwd: cwd || undefined, env: toEnv(env), shell: false })
+    let stdout = Buffer.alloc(0)
+    let stderr = Buffer.alloc(0)
+    child.stdout?.on('data', (d) => (stdout = Buffer.concat([stdout, d])))
+    child.stderr?.on('data', (d) => (stderr = Buffer.concat([stderr, d])))
+    const code = await new Promise((resolve) => child.on('close', resolve))
+    return c.json({ exit_code: code, stdout_b64: b64(stdout), stderr_b64: b64(stderr), duration_ms: 0 })
+  } catch (e) {
+    return c.json({ message: String(e.message) }, 400)
+  }
+})
+
+processRouter.post('/process/spawn', async (c) => {
+  try {
+    const body = await c.req.json()
+    const { command, args = [], cwd, env = {}, as_root = false, timeout_sec = null } = body
+    if (!command) return c.json({ message: 'Missing command' }, 400)
+    const process_id = uid()
+    const child = spawn(command, args, { cwd: cwd || undefined, env: toEnv(env), shell: false })
+    procs.set(process_id, { proc: child, started_at: new Date().toISOString(), pid: child.pid })
+    return c.json({ process_id, pid: child.pid, started_at: new Date().toISOString() })
+  } catch (e) {
+    return c.json({ message: String(e.message) }, 400)
+  }
+})
+
+processRouter.get('/process/:process_id/status', async (c) => {
+  const id = c.req.param('process_id')
+  const item = procs.get(id)
+  if (!item) return c.json({ message: 'Not Found' }, 404)
+  const state = item.proc.killed ? 'exited' : item.proc.exitCode == null ? 'running' : 'exited'
+  return c.json({ state, exit_code: item.proc.exitCode ?? null, cpu_pct: 0, mem_bytes: 0 })
+})
+
+processRouter.get('/process/:process_id/stdout/stream', async (c) => {
+  const id = c.req.param('process_id')
+  const item = procs.get(id)
+  if (!item) return c.json({ message: 'Not Found' }, 404)
+  const stream = new ReadableStream({
+    start(controller) {
+      const enc = new TextEncoder()
+      const send = (stream, data) => controller.enqueue(enc.encode(`event: data\ndata: ${JSON.stringify({ stream, data_b64: b64(data) })}\n\n`))
+      item.proc.stdout?.on('data', (d) => send('stdout', d))
+      item.proc.stderr?.on('data', (d) => send('stderr', d))
+      item.proc.on('close', (code) => controller.enqueue(enc.encode(`event: data\ndata: ${JSON.stringify({ event: 'exit', exit_code: code })}\n\n`)))
+    },
+    cancel() {}
+  })
+  return new Response(stream, { headers: sseHeaders() })
+})
+
+processRouter.post('/process/:process_id/stdin', async (c) => {
+  const id = c.req.param('process_id')
+  const item = procs.get(id)
+  if (!item) return c.json({ message: 'Not Found' }, 404)
+  const body = await c.req.json()
+  const buf = Buffer.from(body.data_b64, 'base64')
+  item.proc.stdin?.write(buf)
+  return c.json({ written_bytes: buf.length })
+})
+
+processRouter.post('/process/:process_id/kill', async (c) => {
+  const id = c.req.param('process_id')
+  const item = procs.get(id)
+  if (!item) return c.json({ message: 'Not Found' }, 404)
+  const body = await c.req.json()
+  const sigMap = { TERM: 'SIGTERM', KILL: 'SIGKILL', INT: 'SIGINT', HUP: 'SIGHUP' }
+  item.proc.kill(sigMap[body.signal] || 'SIGTERM')
+  return c.json({ ok: true })
+})
diff --git a/operator-api/src/routes/recording.js b/operator-api/src/routes/recording.js
new file mode 100644
index 00000000..9d2df3b2
--- /dev/null
+++ b/operator-api/src/routes/recording.js
@@ -0,0 +1,66 @@
+import fs from 'node:fs'
+import { Hono } from 'hono'
+import { b64 } from '../utils/base64.js'
+import {
+  startRecording,
+  stopRecording,
+  getRecorderInfoList,
+  getLatestFilePath,
+  isRecording,
+  deleteRecording
+} from '../services/recordingService.js'
+
+export const recordingRouter = new Hono()
+
+recordingRouter.post('/recording/start', async (c) => {
+  try {
+    const body = await c.req.json().catch(() => ({}))
+    const res = startRecording(body || {})
+    return c.json({ ok: true, id: res.id, started_at: res.started_at }, 201)
+  } catch (e) {
+    return c.json({ message: String(e.message || e) }, e.message === 'Already recording' ? 409 : 500)
+  }
+})
+
+recordingRouter.post('/recording/stop', async (c) => {
+  try {
+    const body = await c.req.json().catch(() => ({}))
+    stopRecording({ id: body?.id || 'default', forceStop: Boolean(body?.forceStop) })
+    return c.json({ ok: true })
+  } catch (e) {
+    return c.json({ message: String(e.message || e) }, 400)
+  }
+})
+
+recordingRouter.get('/recording/download', async (c) => {
+  const id = c.req.query('id') || 'default'
+  if (isRecording({ id })) {
+    return new Response(null, { status: 202, headers: { 'Retry-After': '3' } })
+  }
+  const filePath = getLatestFilePath({ id })
+  if (!filePath || !fs.existsSync(filePath)) return c.json({ message: 'Not found' }, 404)
+  const stat = fs.statSync(filePath)
+  const stream = fs.createReadStream(filePath)
+  return new Response(stream, {
+    status: 200,
+    headers: {
+      'Content-Type': 'video/mp4',
+      'X-Recording-Started-At': new Date(stat.birthtimeMs || stat.ctimeMs).toISOString(),
+      'X-Recording-Finished-At': new Date(stat.mtimeMs).toISOString()
+    }
+  })
+})
+
+recordingRouter.get('/recording/list', async (c) => {
+  return c.json(getRecorderInfoList())
+})
+
+recordingRouter.post('/recording/delete', async (c) => {
+  try {
+    const body = await c.req.json().catch(() => ({}))
+    deleteRecording({ id: body?.id || 'default' })
+    return c.json({ ok: true })
+  } catch (e) {
+    return c.json({ message: String(e.message || e) }, e.message === 'Not found' ? 404 : 400)
+  }
+})
diff --git a/operator-api/src/routes/screenshot.js b/operator-api/src/routes/screenshot.js
new file mode 100644
index 00000000..29852dea
--- /dev/null
+++ b/operator-api/src/routes/screenshot.js
@@ -0,0 +1,77 @@
+import 'dotenv/config'
+import fs from 'node:fs'
+import path from 'node:path'
+import { Hono } from 'hono'
+import { uid } from '../utils/ids.js'
+import { b64 } from '../utils/base64.js'
+import { execCapture } from '../utils/exec.js'
+import { SCREENSHOTS_DIR } from '../utils/env.js'
+
+const FFMPEG = process.env.FFMPEG_BIN || '/usr/bin/ffmpeg'
+const DISPLAY = process.env.DISPLAY || ':0'
+const WIDTH = Number(process.env.WIDTH || 1024)
+const HEIGHT = Number(process.env.HEIGHT || 768)
+
+if (DISPLAY == ':20') {
+  console.warn(`DISPLAY from env: ${DISPLAY} [likely for debugging in a remote VM]`)
+}
+
+async function capture({ region, include_cursor, display = 0, format = 'png', quality }) {
+  const id = uid()
+  const ext = format === 'jpeg' ? 'jpg' : 'png'
+  const outPath = path.join(SCREENSHOTS_DIR, `${id}.${ext}`)
+
+  // Try grim (Wayland), fallback to ffmpeg x11grab
+  let ok = false
+  // grim region format: x y w h
+  const grimRegion = region ? `${region.x},${region.y} ${region.width}x${region.height}` : null
+
+  if (!ok) {
+    const { code } = await execCapture('bash', ['-lc', `command -v grim >/dev/null 2>&1`])
+    if (code === 0) {
+      const args = []
+      if (grimRegion) args.push('-g', grimRegion)
+      args.push(outPath)
+      const res = await execCapture('grim', args)
+      ok = res.code === 0
+    }
+  }
+
+  if (!ok) {
+    // We can omit video_size as ffmpeg will detect the screen dimensions automatically
+    const input = ['-f', 'x11grab', '-i', `${DISPLAY}.0`]
+    const vf = region ? `crop=${region.width}:${region.height}:${region.x}:${region.y}` : 'null'
+    const args = [...input, '-vframes', '1', '-vf', vf, outPath]
+    const res = await execCapture(FFMPEG, ['-y', ...args])
+    ok = res.code === 0
+  }
+
+  if (!fs.existsSync(outPath)) throw new Error('Capture failed')
+  const bytes = fs.readFileSync(outPath)
+  return { id, path: outPath, content_type: ext === 'jpg' ? 'image/jpeg' : 'image/png', bytes }
+}
+
+export const screenshotRouter = new Hono()
+
+screenshotRouter.post('/screenshot/capture', async (c) => {
+  try {
+    const body = await c.req.json().catch(() => ({}))
+    const res = await capture(body || {})
+    return c.json({ screenshot_id: res.id, content_type: res.content_type, bytes_b64: b64(res.bytes) })
+  } catch (e) {
+    return c.json({ message: String(e.message || e) }, 500)
+  }
+})
+
+screenshotRouter.get('/screenshot/:screenshot_id', async (c) => {
+  const id = c.req.param('screenshot_id')
+  const png = path.join(SCREENSHOTS_DIR, `${id}.png`)
+  const jpg = path.join(SCREENSHOTS_DIR, `${id}.jpg`)
+  let file = null
+  if (fs.existsSync(png)) file = png
+  else if (fs.existsSync(jpg)) file = jpg
+  if (!file) return c.json({ message: 'Not Found' }, 404)
+  const stream = fs.createReadStream(file)
+  const ct = file.endsWith('.jpg') ? 'image/jpeg' : 'image/png'
+  return new Response(stream, { headers: { 'Content-Type': ct } })
+})
diff --git a/operator-api/src/routes/scripts.js b/operator-api/src/routes/scripts.js
new file mode 100644
index 00000000..f66b3a1c
--- /dev/null
+++ b/operator-api/src/routes/scripts.js
@@ -0,0 +1,86 @@
+import 'dotenv/config'
+import fs from 'node:fs'
+import path from 'node:path'
+import { Hono } from 'hono'
+import { SCRIPTS_DIR } from '../utils/env.js'
+import { uid } from '../utils/ids.js'
+import { spawn } from 'node:child_process'
+import { sseHeaders } from '../utils/sse.js'
+import { b64 } from '../utils/base64.js'
+
+const runs = new Map() // run_id -> {proc}
+
+export const scriptsRouter = new Hono()
+
+scriptsRouter.post('/scripts/upload', async (c) => {
+  const form = await c.req.parseBody()
+  const destPath = form['path']
+  const file = form['file']
+  const executable = String(form['executable'] || 'true') === 'true'
+  if (!destPath || !file) return c.json({ message: 'Bad Request' }, 400)
+  const abs = destPath.startsWith('/') ? destPath : path.join(SCRIPTS_DIR, destPath)
+  fs.mkdirSync(path.dirname(abs), { recursive: true })
+  const buf = Buffer.from(await file.arrayBuffer())
+  fs.writeFileSync(abs, buf)
+  if (executable) fs.chmodSync(abs, 0o755)
+  return c.json({ path: abs, size_bytes: buf.length })
+})
+
+scriptsRouter.post('/scripts/run', async (c) => {
+  const body = await c.req.json()
+  const { path: scriptPath, args = [], cwd, env = {}, as_user = null, as_root = false, mode = 'sync', stream = true } = body
+  if (!scriptPath || !fs.existsSync(scriptPath)) return c.json({ message: 'Not Found' }, 404)
+  if (mode === 'async') {
+    const run_id = uid()
+    const proc = spawn(scriptPath, args, { cwd: cwd || path.dirname(scriptPath), env: { ...process.env, ...env }, shell: false })
+    runs.set(run_id, { proc })
+    return c.json({ run_id })
+  } else {
+    const proc = spawn(scriptPath, args, { cwd: cwd || path.dirname(scriptPath), env: { ...process.env, ...env }, shell: false })
+    let stdout = Buffer.alloc(0)
+    let stderr = Buffer.alloc(0)
+    proc.stdout.on('data', (d) => (stdout = Buffer.concat([stdout, d])))
+    proc.stderr.on('data', (d) => (stderr = Buffer.concat([stderr, d])))
+    const code = await new Promise((res) => proc.on('close', res))
+    return c.json({ exit_code: code, stdout_b64: b64(stdout), stderr_b64: b64(stderr), duration_ms: 0 })
+  }
+})
+
+scriptsRouter.get('/scripts/run/:run_id/logs/stream', async (c) => {
+  const run_id = c.req.param('run_id')
+  const item = runs.get(run_id)
+  if (!item) return c.json({ message: 'Not Found' }, 404)
+  const stream = new ReadableStream({
+    start(controller) {
+      const enc = new TextEncoder()
+      const send = (stream, data) => controller.enqueue(enc.encode(`event: data\ndata: ${JSON.stringify({ stream, data_b64: b64(data) })}\n\n`))
+      item.proc.stdout?.on('data', (d) => send('stdout', d))
+      item.proc.stderr?.on('data', (d) => send('stderr', d))
+      item.proc.on('close', (code) => controller.enqueue(enc.encode(`event: data\ndata: ${JSON.stringify({ event: 'exit', exit_code: code })}\n\n`)))
+    },
+    cancel() {}
+  })
+  return new Response(stream, { headers: sseHeaders() })
+})
+
+scriptsRouter.get('/scripts/list', async (c) => {
+  const items = []
+  function walk(dir) {
+    for (const name of fs.readdirSync(dir)) {
+      const p = path.join(dir, name)
+      const st = fs.statSync(p)
+      if (st.isDirectory()) walk(p)
+      else items.push({ path: p, size_bytes: st.size, updated_at: st.mtime.toISOString() })
+    }
+  }
+  walk(SCRIPTS_DIR)
+  return c.json({ items })
+})
+
+scriptsRouter.delete('/scripts/delete', async (c) => {
+  const body = await c.req.json()
+  const p = body?.path
+  if (!p || !fs.existsSync(p)) return c.json({ message: 'Not Found' }, 404)
+  fs.rmSync(p, { force: true })
+  return c.json({ ok: true })
+})
diff --git a/operator-api/src/routes/stream.js b/operator-api/src/routes/stream.js
new file mode 100644
index 00000000..64e3000e
--- /dev/null
+++ b/operator-api/src/routes/stream.js
@@ -0,0 +1,39 @@
+import { Hono } from 'hono'
+import { startStream, stopStream, metricsEmitter } from '../services/streamService.js'
+import { sseHeaders, sseFormat } from '../utils/sse.js'
+
+export const streamRouter = new Hono()
+
+streamRouter.post('/stream/start', async (c) => {
+  try {
+    const body = await c.req.json()
+    const { stream_id } = startStream(body)
+    return c.json({ stream_id, status: 'starting', metrics_endpoint: `/stream/${stream_id}/metrics/stream` })
+  } catch (e) {
+    return c.json({ message: String(e.message || e) }, 400)
+  }
+})
+
+streamRouter.post('/stream/stop', async (c) => {
+  try {
+    const body = await c.req.json()
+    stopStream(body)
+    return c.json({ stream_id: body.stream_id, status: 'stopped' })
+  } catch (e) {
+    return c.json({ message: String(e.message || e) }, 404)
+  }
+})
+
+streamRouter.get('/stream/:stream_id/metrics/stream', async (c) => {
+  const id = c.req.param('stream_id')
+  const em = metricsEmitter(id)
+  if (!em) return c.json({ message: 'Not Found' }, 404)
+  const stream = new ReadableStream({
+    start(controller) {
+      const onData = (obj) => controller.enqueue(new TextEncoder().encode(sseFormat(obj)))
+      em.on('metrics', onData)
+    },
+    cancel() {}
+  })
+  return new Response(stream, { headers: sseHeaders() })
+})
diff --git a/operator-api/src/services/forwardService.js b/operator-api/src/services/forwardService.js
new file mode 100644
index 00000000..073df707
--- /dev/null
+++ b/operator-api/src/services/forwardService.js
@@ -0,0 +1,25 @@
+import { spawn } from 'node:child_process'
+import { uid } from '../utils/ids.js'
+
+const forwards = new Map() // id -> {proc, direction, host_port, vm_port}
+
+export function addForward({ direction, host_port, vm_port }) {
+  const id = uid()
+  let proc
+  if (direction === 'host_to_vm') {
+    // Listen on VM host_port and forward to vm_port (localhost)
+    proc = spawn('socat', [`TCP-LISTEN:${host_port},fork,reuseaddr`, `TCP:127.0.0.1:${vm_port}`])
+  } else {
+    proc = spawn('socat', [`TCP-LISTEN:${vm_port},fork,reuseaddr`, `TCP:127.0.0.1:${host_port}`])
+  }
+  forwards.set(id, { proc, direction, host_port, vm_port })
+  return { forward_id: id, active: true }
+}
+
+export function removeForward({ forward_id }) {
+  const item = forwards.get(forward_id)
+  if (!item) throw new Error('Not Found')
+  item.proc.kill('SIGINT')
+  forwards.delete(forward_id)
+  return true
+}
diff --git a/operator-api/src/services/interceptService.js b/operator-api/src/services/interceptService.js
new file mode 100644
index 00000000..856125ef
--- /dev/null
+++ b/operator-api/src/services/interceptService.js
@@ -0,0 +1,76 @@
+import 'dotenv/config'
+import http from 'node:http'
+import httpProxy from 'http-proxy'
+import { uid } from '../utils/ids.js'
+import { EventEmitter } from 'node:events'
+
+const ruleSets = new Map() // id -> {rules}
+const harEmitter = new EventEmitter()
+
+let proxyServer = null
+let runningPort = Number(process.env.HTTP_PROXY_PORT || 8082)
+
+function ensureProxy() {
+  if (proxyServer) return
+  const proxy = httpProxy.createProxyServer({})
+  proxy.on('proxyRes', function (proxyRes, req, res) {
+    const entry = {
+      request: { method: req.method, url: req.url, headers: Object.entries(req.headers).map(([name, value]) => ({ name, value: String(value) })) },
+      response: { status: proxyRes.statusCode, headers: Object.entries(proxyRes.headers).map(([name, value]) => ({ name, value: String(value) })) }
+    }
+    harEmitter.emit('har', { ts: new Date().toISOString(), entry })
+  })
+  proxyServer = http.createServer((req, res) => {
+    const url = new URL(req.url, `http://${req.headers.host}`)
+    // apply first matching rule
+    for (const [, set] of ruleSets) {
+      for (const rule of set.rules) {
+        const m = rule.match || {}
+        const methodOk = !m.method || m.method === req.method
+        const hostOk = !m.host_contains || (req.headers.host || '').includes(m.host_contains)
+        const pathOk = !m.path_regex || new RegExp(m.path_regex).test(url.pathname)
+        const protoOk = !m.protocol || m.protocol === 'http'
+        if (methodOk && hostOk && pathOk && protoOk) {
+          const a = rule.action
+          if (a.type === 'block') {
+            res.statusCode = 403
+            res.end('blocked')
+            return
+          }
+          if (a.type === 'delay' && a.delay_ms) {
+            const hold = setTimeout(() => {}, a.delay_ms)
+          }
+          if (a.type === 'mock_response') {
+            res.writeHead(a.status || 200, a.set_response_headers || {})
+            const body = a.body_b64 ? Buffer.from(a.body_b64, 'base64') : Buffer.from('')
+            res.end(body)
+            return
+          }
+          if (a.type === 'modify_request' && a.set_request_headers) {
+            for (const [k, v] of Object.entries(a.set_request_headers)) req.headers[k.toLowerCase()] = v
+          }
+        }
+      }
+    }
+    proxy.web(req, res, { target: `${url.protocol}//${url.host}` })
+  })
+  proxyServer.listen(runningPort, '0.0.0.0')
+}
+
+export function applyRules({ rules }) {
+  ensureProxy()
+  const id = uid()
+  ruleSets.set(id, { rules })
+  return { rule_set_id: id, applied: true }
+}
+
+export function deleteRuleSet({ rule_set_id }) {
+  if (!ruleSets.has(rule_set_id)) throw new Error('Not Found')
+  ruleSets.delete(rule_set_id)
+  return true
+}
+
+export function harStreamEmitter() {
+  ensureProxy()
+  return harEmitter
+}
diff --git a/operator-api/src/services/recordingService.js b/operator-api/src/services/recordingService.js
new file mode 100644
index 00000000..8d05c16e
--- /dev/null
+++ b/operator-api/src/services/recordingService.js
@@ -0,0 +1,142 @@
+import 'dotenv/config'
+import fs from 'node:fs'
+import path from 'node:path'
+import { spawnSync } from 'node:child_process'
+import { execSpawn } from '../utils/exec.js'
+import { RECORDINGS_DIR } from '../utils/env.js'
+import { uid } from '../utils/ids.js'
+
+const FFMPEG = process.env.FFMPEG_BIN || '/usr/bin/ffmpeg'
+const WIDTH = Number(process.env.WIDTH || 1024)
+const HEIGHT = Number(process.env.HEIGHT || 768)
+const DISPLAY = process.env.DISPLAY || ':0'
+
+const state = new Map() // id -> {proc, file, started_at, finished_at}
+
+// Best-effort discovery of a PulseAudio monitor for "what-you-hear" capture.
+let _cachedPulseMonitor = undefined
+function detectPulseMonitor() {
+  if (_cachedPulseMonitor !== undefined) return _cachedPulseMonitor
+  const env = { ...process.env }
+  try {
+    // 1) Try the real default sink -> "<sink>.monitor"
+    let sink = null
+    const getSink = spawnSync('pactl', ['get-default-sink'], { env, encoding: 'utf8' })
+    if (getSink.status === 0) sink = getSink.stdout.trim()
+    if (!sink) {
+      // Older PulseAudio: parse "pactl info"
+      const info = spawnSync('pactl', ['info'], { env, encoding: 'utf8' })
+      if (info.status === 0) {
+        const m = info.stdout.match(/Default Sink:\s*(.+)\s*$/m)
+        if (m) sink = m[1].trim()
+      }
+    }
+    const list = spawnSync('pactl', ['list', 'short', 'sources'], { env, encoding: 'utf8' })
+    const sourcesTxt = list.status === 0 ? list.stdout : ''
+    const hasSource = (name) => sourcesTxt.split('\n').some((ln) => ln.split('\t')[1] === name)
+    if (sink && hasSource(`${sink}.monitor`)) {
+      _cachedPulseMonitor = `${sink}.monitor`
+      return _cachedPulseMonitor
+    }
+    // 2) Project's common virtual sink name
+    if (hasSource('audio_output.monitor')) {
+      _cachedPulseMonitor = 'audio_output.monitor'
+      return _cachedPulseMonitor
+    }
+  } catch (_) {
+    // ignore
+  }
+  _cachedPulseMonitor = null
+  return null
+}
+
+function buildArgsMp4({ framerate = 20, maxDurationInSeconds, audio = true }) {
+  const args = ['-nostdin', '-hide_banner']
+  // Video input (x11grab)
+  args.push('-f', 'x11grab')
+  // Width/height omitted intentionally; X server provides exact geometry
+  args.push('-i', `${DISPLAY}.0`)
+  // Optional audio input (PulseAudio "monitor" of output)
+  const pulseMonitor = audio ? detectPulseMonitor() : null
+  if (pulseMonitor) {
+    args.push('-f', 'pulse', '-i', pulseMonitor)
+  }
+  // Output encoders and common options
+  args.push(
+    '-r', String(framerate),
+    '-c:v', 'libx264',
+    '-preset', 'veryfast',
+    '-pix_fmt', 'yuv420p',
+    '-movflags', '+faststart'
+  )
+  if (maxDurationInSeconds) args.push('-t', String(maxDurationInSeconds))
+  if (pulseMonitor) {
+    // AAC in MP4; 48k stereo; stop when the shorter stream ends
+    args.push('-c:a', 'aac', '-b:a', '128k', '-ac', '2', '-ar', '48000', '-shortest')
+  }
+  return args
+}
+
+export function startRecording({ id, framerate, maxDurationInSeconds, maxFileSizeInMB }) {
+  const recId = id || 'default'
+  if (state.get(recId)?.proc) throw new Error('Already recording')
+  const fileName = `${recId}-${Date.now()}.mp4`
+  const outPath = path.join(RECORDINGS_DIR, fileName)
+  const args = buildArgsMp4({ framerate, maxDurationInSeconds })
+  if (maxFileSizeInMB) args.push('-fs', String(maxFileSizeInMB * 1024 * 1024))
+  args.push(outPath)
+  const proc = execSpawn(FFMPEG, ['-y', ...args], { env: { ...process.env } })
+  const started_at = new Date().toISOString()
+  state.set(recId, { proc, file: outPath, started_at, finished_at: null })
+  proc.on('close', () => {
+    const rec = state.get(recId)
+    if (rec) {
+      rec.finished_at = new Date().toISOString()
+      rec.proc = null
+      state.set(recId, rec)
+    }
+  })
+  return { id: recId, file: outPath, started_at }
+}
+
+export function stopRecording({ id = 'default', forceStop = false }) {
+  const rec = state.get(id)
+  if (!rec?.proc) throw new Error('Not recording')
+  if (forceStop) rec.proc.kill('SIGKILL')
+  else rec.proc.kill('SIGINT')
+  return true
+}
+
+export function getRecorderInfoList() {
+  const items = []
+  for (const [id, r] of state.entries()) {
+    items.push({
+      id,
+      isRecording: Boolean(r.proc),
+      started_at: r.started_at || null,
+      finished_at: r.finished_at || null
+    })
+  }
+  if (!items.length) {
+    items.push({ id: 'default', isRecording: false, started_at: null, finished_at: null })
+  }
+  return items
+}
+
+export function getLatestFilePath({ id }) {
+  const rec = state.get(id || 'default')
+  if (!rec) return null
+  return rec.file
+}
+
+export function isRecording({ id }) {
+  const rec = state.get(id || 'default')
+  return Boolean(rec?.proc)
+}
+
+export function deleteRecording({ id }) {
+  const rec = state.get(id || 'default')
+  if (!rec?.file) throw new Error('Not found')
+  fs.rmSync(rec.file, { force: true })
+  return true
+}
diff --git a/operator-api/src/services/socksService.js b/operator-api/src/services/socksService.js
new file mode 100644
index 00000000..fb235942
--- /dev/null
+++ b/operator-api/src/services/socksService.js
@@ -0,0 +1,28 @@
+import socks from 'socksv5'
+import { uid } from '../utils/ids.js'
+
+const proxies = new Map() // id -> {server, host, port}
+
+export function startSocks({ bind_host = '127.0.0.1', bind_port = 1080, auth = null }) {
+  const server = socks.createServer((info, accept, deny) => accept())
+  if (auth?.username || auth?.password) {
+    server.useAuth(socks.auth.UserPassword((user, pass, cb) => {
+      if (user === (auth.username || '') && pass === (auth.password || '')) cb(true)
+      else cb(false)
+    }))
+  } else {
+    server.useAuth(socks.auth.None())
+  }
+  server.listen(bind_port, bind_host)
+  const proxy_id = uid()
+  proxies.set(proxy_id, { server, host: bind_host, port: bind_port })
+  return { proxy_id, url: `socks5://${bind_host}:${bind_port}` }
+}
+
+export function stopSocks({ proxy_id }) {
+  const p = proxies.get(proxy_id)
+  if (!p) throw new Error('Not Found')
+  p.server.close()
+  proxies.delete(proxy_id)
+  return true
+}
diff --git a/operator-api/src/services/streamService.js b/operator-api/src/services/streamService.js
new file mode 100644
index 00000000..65840529
--- /dev/null
+++ b/operator-api/src/services/streamService.js
@@ -0,0 +1,72 @@
+import 'dotenv/config'
+import { execSpawn } from '../utils/exec.js'
+import { uid } from '../utils/ids.js'
+import { EventEmitter } from 'node:events'
+
+const FFMPEG = process.env.FFMPEG_BIN || '/usr/bin/ffmpeg'
+const DISPLAY = process.env.DISPLAY || ':0'
+const WIDTH = Number(process.env.WIDTH || 1024)
+const HEIGHT = Number(process.env.HEIGHT || 768)
+const PULSE_SOURCE = process.env.PULSE_SOURCE || 'default'
+
+const streams = new Map() // id -> {proc, emitter}
+
+export function startStream(req) {
+  const stream_id = uid()
+  const {
+    region = null,
+    display = 0,
+    fps = 30,
+    video_codec = 'h264',
+    video_bitrate_kbps = 3500,
+    audio = { capture_system: true, capture_mic: false },
+    rtmps_url,
+    stream_key
+  } = req
+
+  if (!rtmps_url || !stream_key) throw new Error('Missing RTMPS params')
+
+  // We can omit video_size as ffmpeg will detect the screen dimensions automatically
+  const input = ['-f', 'x11grab', '-r', String(fps), '-i', `${DISPLAY}.0`]
+  const audioArgs = audio?.capture_system ? ['-f', 'pulse', '-i', PULSE_SOURCE] : []
+  const vf = region ? ['-filter:v', `crop=${region.width}:${region.height}:${region.x}:${region.y}`] : []
+  const out = ['-c:v', video_codec === 'h265' ? 'libx265' : video_codec === 'av1' ? 'libsvtav1' : 'libx264', '-b:v', `${video_bitrate_kbps}k`, '-c:a', 'aac', '-f', 'flv', `${rtmps_url}/${stream_key}`]
+
+  const args = ['-thread_queue_size', '512', ...input, ...audioArgs, ...vf, ...out]
+  const proc = execSpawn(FFMPEG, ['-hide_banner', ...args], { env: { ...process.env } })
+  const emitter = new EventEmitter()
+  streams.set(stream_id, { proc, emitter })
+
+  proc.stderr.on('data', (d) => {
+    const s = d.toString('utf8')
+    // rough parse
+    const fpsMatch = s.match(/fps=\s*([\d.]+)/)
+    const kbpsMatch = s.match(/bitrate=\s*([\d.]+)kbits\/s/)
+    const dropMatch = s.match(/drop=\s*(\d+)/)
+    const obj = {
+      ts: new Date().toISOString(),
+      fps: fpsMatch ? Number(fpsMatch[1]) : undefined,
+      bitrate_kbps: kbpsMatch ? Number(kbpsMatch[1]) : undefined,
+      dropped_frames: dropMatch ? Number(dropMatch[1]) : undefined
+    }
+    emitter.emit('metrics', obj)
+  })
+  proc.on('close', () => {
+    emitter.emit('metrics', { ts: new Date().toISOString(), ended: true })
+  })
+
+  return { stream_id }
+}
+
+export function stopStream({ stream_id }) {
+  const item = streams.get(stream_id)
+  if (!item) throw new Error('Not Found')
+  item.proc.kill('SIGINT')
+  return true
+}
+
+export function metricsEmitter(stream_id) {
+  const item = streams.get(stream_id)
+  if (!item) return null
+  return item.emitter
+}
diff --git a/operator-api/src/utils/base64.js b/operator-api/src/utils/base64.js
new file mode 100644
index 00000000..54ab640b
--- /dev/null
+++ b/operator-api/src/utils/base64.js
@@ -0,0 +1,3 @@
+export const b64 = (buf) => Buffer.from(buf).toString('base64')
+export const b64json = (obj) => b64(Buffer.from(JSON.stringify(obj)))
+export const fromB64 = (s) => Buffer.from(s, 'base64')
diff --git a/operator-api/src/utils/env.js b/operator-api/src/utils/env.js
new file mode 100644
index 00000000..833a04d5
--- /dev/null
+++ b/operator-api/src/utils/env.js
@@ -0,0 +1,17 @@
+import 'dotenv/config'
+import fs from 'node:fs'
+import path from 'node:path'
+
+export const DATA_DIR = process.env.DATA_DIR || '/tmp/kernel-operator-api/data'
+export const TMP_DIR = path.join(DATA_DIR, 'tmp')
+export const SCRIPTS_DIR = path.join(DATA_DIR, 'scripts')
+export const RECORDINGS_DIR = path.join(DATA_DIR, 'recordings')
+export const SCREENSHOTS_DIR = path.join(DATA_DIR, 'screenshots')
+
+export function ensureDirs() {
+  for (const p of [DATA_DIR, TMP_DIR, SCRIPTS_DIR, RECORDINGS_DIR, SCREENSHOTS_DIR]) {
+    fs.mkdirSync(p, { recursive: true })
+  }
+}
+
+ensureDirs()
diff --git a/operator-api/src/utils/exec.js b/operator-api/src/utils/exec.js
new file mode 100644
index 00000000..04a1626d
--- /dev/null
+++ b/operator-api/src/utils/exec.js
@@ -0,0 +1,98 @@
+import { spawn } from 'node:child_process'
+import chalk from 'chalk'
+
+const DEBUG_ENABLED = process.env.DEBUG_LOGS === 'true' || process.env.DEBUG_LOGS === true
+
+function debug(...args) {
+  if (DEBUG_ENABLED) {
+    console.log(...args)
+  }
+}
+export function execSpawn(cmd, args = [], opts = {}) {
+  debug(chalk.blue('[EXEC]'), chalk.cyan('Spawning command:'), chalk.yellow(`${cmd} ${args.join(' ')}`))
+  const child = spawn(cmd, args, { shell: false, ...opts })
+  
+  if (DEBUG_ENABLED) {
+    child.stdout?.on('data', (data) => {
+      debug(chalk.blue('[EXEC]'), chalk.green('[STDOUT]'), data.toString().trim())
+    })
+    
+    child.stderr?.on('data', (data) => {
+      debug(chalk.blue('[EXEC]'), chalk.red('[STDERR]'), data.toString().trim())
+    })
+    
+    child.on('close', (code) => {
+      const exitColor = code === 0 ? chalk.green : chalk.red
+      debug(chalk.blue('[EXEC]'), chalk.cyan('Command exited with code:'), exitColor(code))
+    })
+  }
+  
+  return child
+}
+
+export async function execCapture(cmd, args = [], opts = {}) {
+  debug(chalk.blue('[EXEC]'), chalk.cyan('Capturing output from:'), chalk.yellow(`${cmd} ${args.join(' ')}`))
+  return new Promise((resolve) => {
+    const child = execSpawn(cmd, args, opts)
+    let stdout = Buffer.alloc(0)
+    let stderr = Buffer.alloc(0)
+    
+    child.stdout?.on('data', (d) => {
+      debug(chalk.blue('[EXEC]'), chalk.green('[STDOUT]'), chalk.cyan(`Received ${d.length} bytes`))
+      stdout = Buffer.concat([stdout, d])
+    })
+    
+    child.stderr?.on('data', (d) => {
+      const stderrStr = d.toString().trim()
+      debug(
+        chalk.blue('[EXEC]'), 
+        chalk.red('[STDERR]'), 
+        chalk.cyan(`Received ${d.length} bytes`),
+        '\n', 
+        chalk.red('↳'), 
+        chalk.yellow(stderrStr)
+      )
+      stderr = Buffer.concat([stderr, d])
+    })
+    
+    child.on('close', (code) => {
+      const exitColor = code === 0 ? chalk.green : chalk.red
+      debug(
+        chalk.blue('[EXEC]'),
+        chalk.cyan('Command completed with exit code:'),
+        exitColor(code)
+      )
+      
+      debug(
+        chalk.blue('[EXEC]'),
+        chalk.cyan(`Total stdout: ${stdout.length} bytes, stderr: ${stderr.length} bytes`)
+      )
+      
+      if (stdout.length > 0) {
+        const preview = stdout.toString().substring(0, 100)
+        debug(
+          chalk.blue('[EXEC]'),
+          chalk.green('[STDOUT]'),
+          chalk.cyan('Preview:'),
+          '\n',
+          chalk.green('↳'),
+          preview + (stdout.length > 100 ? chalk.dim('...') : '')
+        )
+      }
+      
+      if (stderr.length > 0) {
+        const preview = stderr.toString().substring(0, 100)
+        debug(
+          chalk.blue('[EXEC]'),
+          chalk.red('[STDERR]'),
+          chalk.cyan('Preview:'),
+          '\n',
+          chalk.red('↳'),
+          preview + (stderr.length > 100 ? chalk.dim('...') : '')
+        )
+      }
+      
+      resolve({ code, stdout, stderr })
+    })
+  })
+}
diff --git a/operator-api/src/utils/ids.js b/operator-api/src/utils/ids.js
new file mode 100644
index 00000000..5fcfec8e
--- /dev/null
+++ b/operator-api/src/utils/ids.js
@@ -0,0 +1,3 @@
+import { customAlphabet } from 'nanoid'
+export const rid = customAlphabet('0123456789abcdefghijklmnopqrstuvwxyz', 10)
+export const uid = () => rid()
diff --git a/operator-api/src/utils/sse.js b/operator-api/src/utils/sse.js
new file mode 100644
index 00000000..ab6e5d47
--- /dev/null
+++ b/operator-api/src/utils/sse.js
@@ -0,0 +1,13 @@
+export function sseHeaders(extra = {}) {
+  return {
+    'Content-Type': 'text/event-stream; charset=utf-8',
+    'Cache-Control': 'no-cache, no-transform',
+    Connection: 'keep-alive',
+    'X-SSE-Content-Type': 'application/json',
+    ...extra
+  }
+}
+
+export function sseFormat(obj) {
+  return `event: data\ndata: ${JSON.stringify(obj)}\n\n`
+}
diff --git a/operator-api/test.js b/operator-api/test.js
new file mode 100644
index 00000000..42394e0c
--- /dev/null
+++ b/operator-api/test.js
@@ -0,0 +1,665 @@
+// `--all` or `input fs` (categories)
+
+import { execSync } from 'node:child_process'
+import { promises as fsp } from 'node:fs'
+import { dirname, join } from 'node:path'
+import os from 'node:os'
+import chalk from 'chalk'
+
+// ---------------------------- CLI / Config ----------------------------
+const args = process.argv.slice(2)
+const flags = new Set(args.filter(a => a.startsWith('-')))
+const names = args.filter(a => !a.startsWith('-'))
+
+const RUN_ALL = flags.has('--all')
+const BASE_URL = 'http://127.0.0.1:10001'
+const ALWAYS_DEBUG = true
+
+// ---------------------------- Utilities ----------------------------
+function now() { return Date.now() }
+function ms(n) { return `${n}ms` }
+
+function banner(title) {
+  const line = '─'.repeat(78)
+  console.log(chalk.gray(line))
+  console.log(chalk.bold.white(title))
+  console.log(chalk.gray(line))
+}
+
+function statusLine(kind, text) {
+  const tag = kind === 'PASS' ? chalk.bgGreen.black(' PASS ')
+    : kind === 'FAIL' ? chalk.bgRed.white(' FAIL ')
+      : kind === 'SKIP' ? chalk.bgYellow.black(' SKIP ')
+        : chalk.bgBlue.white(` ${kind} `)
+  console.log(`${tag} ${text}`)
+}
+
+function toCurl(fullUrl, init = {}) {
+  let curlCmd = `curl -sS -X ${init.method || 'GET'} "${fullUrl}"`
+  const headers = { ...(init.headers || {}) }
+  for (const [k, v] of Object.entries(headers)) curlCmd += ` -H "${k}: ${v}"`
+  if (init.body && typeof init.body === 'string') curlCmd += ` -d '${init.body.replace(/'/g, "'\\''")}'`
+  return curlCmd
+}
+
+async function j(url, init = {}) {
+  const full = `${BASE_URL}${url}`
+  const headers = { 'content-type': 'application/json', ...(init.headers || {}) }
+  if (ALWAYS_DEBUG) console.log(chalk.cyan('[http]'), chalk.yellow(toCurl(full, { ...init, headers })))
+  const r = await fetch(full, { ...init, headers })
+  const txt = await r.text()
+  let body
+  try { body = JSON.parse(txt) } catch {
+    const isBinaryish = /[\x00-\x08\x0E-\x1F]/.test(txt)
+    const isLarge = txt.length > 1000
+    body = isBinaryish || isLarge ? `${txt.substring(0, 500)}... [${txt.length} bytes${isBinaryish ? ', binary' : ''}]` : txt
+  }
+  if (ALWAYS_DEBUG) {
+    console.log(chalk.cyan('[http]'), chalk.green(`status=${r.status}`))
+    if (typeof body === 'object') {
+      const jsonString = JSON.stringify(body, null, 2)
+      const maxLength = 3_000
+      const maxLengthSlice = 1_000
+      if (jsonString.length > maxLength) {
+        console.log(chalk.magenta('[body]'), chalk.gray(`${jsonString.substring(0, maxLengthSlice)}... [${jsonString.length} bytes total]`))
+      } else {
+        console.log(chalk.magenta('[body]'), chalk.gray(jsonString))
+      }
+    } else if (typeof body === 'string') {
+      const maxLength = 3_000
+      const maxLengthSlice = 1_500
+      if (body.length > maxLength) {
+        console.log(chalk.magenta('[body]'), chalk.gray(`${body.substring(0, maxLengthSlice)}... [${body.length} bytes total]`))
+      } else {
+        console.log(chalk.magenta('[body]'), chalk.gray(body))
+      }
+    } else {
+      console.log(chalk.magenta('[body]'), chalk.gray(String(body)))
+    }
+  }
+  return { status: r.status, headers: r.headers, body }
+}
+
+async function raw(url, init = {}) {
+  const full = `${BASE_URL}${url}`
+  if (ALWAYS_DEBUG) console.log(chalk.cyan('[http] raw'), chalk.yellow(toCurl(full, init)))
+  return fetch(full, init)
+}
+
+async function readSSE(path, { max = 1, timeoutMs = 5000 } = {}) {
+  const full = `${BASE_URL}${path}`
+  if (ALWAYS_DEBUG) console.log(chalk.cyan('[sse] connect'), chalk.yellow(full), chalk.gray(`max=${max} timeout=${timeoutMs}`))
+  const res = await fetch(full)
+  if (!res.ok) throw new Error(`bad status ${res.status}`)
+  const reader = res.body.getReader()
+  const decoder = new TextDecoder('utf-8')
+  const events = []
+  let buf = ''
+  const start = now()
+  while (events.length < max && (now() - start) < timeoutMs) {
+    const { value, done } = await reader.read()
+    if (done) break
+    const chunk = decoder.decode(value, { stream: true })
+    if (ALWAYS_DEBUG && chunk.trim()) console.log(chalk.blue('[sse] data'), chalk.gray(chunk.replace(/\n/g, '\\n')))
+    buf += chunk
+    let idx
+    while ((idx = buf.indexOf('\n\n')) !== -1) {
+      const block = buf.slice(0, idx)
+      buf = buf.slice(idx + 2)
+      const dataLine = block.split('\n').find(l => l.startsWith('data: '))
+      if (dataLine) {
+        const json = dataLine.slice(6)
+        try {
+          const obj = JSON.parse(json)
+          events.push(obj)
+          if (ALWAYS_DEBUG) console.log(chalk.green('[sse] event'), chalk.gray(JSON.stringify(obj)))
+        } catch { }
+      }
+      if (events.length >= max) break
+    }
+  }
+  try { reader.cancel() } catch { }
+  return events
+}
+
+function hasCmd(cmd) {
+  try {
+    execSync(`bash -lc "command -v ${cmd} >/dev/null 2>&1"`, { stdio: 'ignore' })
+    return true
+  } catch {
+    return false
+  }
+}
+
+function tmpPath(name = 'kco') {
+  const id = Math.random().toString(36).slice(2)
+  const p = `${os.tmpdir().replace(/\/$/, '')}/${name}-${id}`
+  if (ALWAYS_DEBUG) console.log(chalk.cyan('[tmp]'), chalk.yellow(p))
+  return p
+}
+
+// ---------------------------- Harness ----------------------------
+const RESULTS = []
+
+async function runTest(category, name, fn, { timeoutMs = 30000, skipIf = false } = {}) {
+  if (skipIf) {
+    RESULTS.push({ category, name, status: 'SKIP', ms: 0, note: typeof skipIf === 'string' ? skipIf : '' })
+    statusLine('SKIP', `[${category}] ${name}${skipIf ? `  (${skipIf})` : ''}`)
+    return
+  }
+  const t0 = now()
+  try {
+    await Promise.race([
+      fn(),
+      (async () => { await new Promise(r => setTimeout(r, timeoutMs)); throw new Error(`timeout after ${timeoutMs}ms`) })()
+    ])
+    const dur = now() - t0
+    RESULTS.push({ category, name, status: 'PASS', ms: dur })
+    statusLine('PASS', `[${category}] ${name}  ${ms(dur)}`)
+  } catch (e) {
+    const dur = now() - t0
+    RESULTS.push({ category, name, status: 'FAIL', ms: dur, error: String(e && e.message || e) })
+    statusLine('FAIL', `[${category}] ${name}  ${ms(dur)}  :: ${String(e && e.message || e)}`)
+  }
+}
+
+function filterCategory(cat) {
+  if (RUN_ALL) return true
+  if (names.length === 0) return true
+  return names.some(n => cat.toLowerCase().includes(n.toLowerCase()))
+}
+
+// ---------------------------- Suites ----------------------------
+async function suite_health() {
+  await runTest('health', 'GET /health is ok', async () => {
+    const r = await j('/health')
+    if (r.status !== 200) throw new Error('status != 200')
+    if (!r.body || r.body.status !== 'ok') throw new Error('bad body')
+  })
+}
+
+async function suite_browser() {
+  await runTest('browser', 'HAR start/stream/stop', async () => {
+    const start = await j('/browser/har/start', { method: 'POST', body: JSON.stringify({}) })
+    if (start.status !== 200) throw new Error('start failed')
+    const id = start.body.har_session_id
+    const res = await raw(`/browser/har/${id}/stream`)
+    if (res.status !== 200) throw new Error('stream status != 200')
+    const reader = res.body.getReader()
+    await reader.cancel()
+    const stop = await j('/browser/har/stop', { method: 'POST', body: JSON.stringify({ har_session_id: id }) })
+    if (stop.status !== 200) throw new Error('stop failed')
+  })
+}
+
+async function suite_bus() {
+  await runTest('bus', 'publish/subscribe SSE', async () => {
+    const p = readSSE(`/bus/subscribe?channel=ch1`, { max: 1, timeoutMs: 4000 })
+    const pub = await j('/bus/publish', { method: 'POST', body: JSON.stringify({ channel: 'ch1', type: 'note', payload: { msg: 'hello' } }) })
+    if (pub.status !== 200) throw new Error('publish failed')
+    const ev = await p
+    if (!Array.isArray(ev) || ev.length < 1) throw new Error('no events')
+    if (ev[0]?.payload?.msg !== 'hello') throw new Error('payload mismatch')
+  })
+}
+
+async function suite_clipboard() {
+  await runTest('clipboard', 'GET /clipboard responds', async () => {
+    const r = await j('/clipboard')
+    if (r.status !== 200) throw new Error('status != 200')
+    if (!['text', 'image'].includes(r.body.type)) throw new Error('bad type')
+  })
+
+  const toolsPresent = hasCmd('xclip') || (hasCmd('wl-copy') && hasCmd('wl-paste'))
+  await runTest('clipboard', 'stream detects change (best-effort)', async () => {
+    const ts = Date.now().toString()
+    const text = `Test ${ts}`
+    const set = await j('/clipboard', { method: 'POST', body: JSON.stringify({ type: 'text', text }) })
+    if (set.status !== 200 || set.body.ok !== true) throw new Error('POST /clipboard failed')
+    const res = await raw('/clipboard/stream')
+    if (res.status !== 200) throw new Error('stream open failed')
+    const reader = res.body.getReader()
+    let found = false
+    const endAt = now() + 5000
+    while (now() < endAt && !found) {
+      const { done, value } = await reader.read()
+      if (done) break
+      const chunk = new TextDecoder().decode(value)
+      if (chunk.includes(ts)) found = true
+      await new Promise(r => setTimeout(r, 150))
+    }
+    try { reader.cancel() } catch { }
+    if (!found) throw new Error('no change detected')
+  }, { skipIf: toolsPresent ? false : 'clipboard tools missing' })
+}
+
+async function suite_fs() {
+  await runTest('fs', 'create/list/file_info/delete_directory', async () => {
+    const dir = tmpPath('fsdir')
+    let r = await j('/fs/create_directory', { method: 'PUT', body: JSON.stringify({ path: dir, mode: '0755' }) })
+    if (r.status !== 201) throw new Error('create_directory failed')
+    r = await j(`/fs/list_files?path=${encodeURIComponent(dirname(dir))}`)
+    if (r.status !== 200 || !Array.isArray(r.body)) throw new Error('list_files failed')
+    r = await j(`/fs/file_info?path=${encodeURIComponent(dir)}`)
+    if (r.status !== 200 || r.body.is_dir !== true) throw new Error('file_info failed')
+    r = await j('/fs/delete_directory', { method: 'PUT', body: JSON.stringify({ path: dir }) })
+    if (r.status !== 200) throw new Error('delete_directory failed')
+  })
+
+  await runTest('fs', 'write/read/download/move/delete_file', async () => {
+    const p1 = tmpPath('fsfile.txt')
+    let r = await raw(`/fs/write_file?path=${encodeURIComponent(p1)}&mode=0644`, { method: 'PUT', body: Buffer.from('hello world') })
+    if (r.status !== 201) throw new Error('write_file failed')
+    r = await raw(`/fs/read_file?path=${encodeURIComponent(p1)}`)
+    if (r.status !== 200) throw new Error('read_file failed')
+    const txt = await r.text()
+    if (txt !== 'hello world') throw new Error('content mismatch')
+    r = await raw(`/fs/download?path=${encodeURIComponent(p1)}`)
+    if (r.status !== 200) throw new Error('download failed')
+    const p2 = tmpPath('fsfile2.txt')
+    let jres = await j('/fs/move', { method: 'PUT', body: JSON.stringify({ src_path: p1, dest_path: p2 }) })
+    if (jres.status !== 200) throw new Error('move failed')
+    jres = await j('/fs/delete_file', { method: 'PUT', body: JSON.stringify({ path: p2 }) })
+    if (jres.status !== 200) throw new Error('delete_file failed')
+  })
+
+  await runTest('fs', 'upload', async () => {
+    const p = tmpPath('upload.bin')
+    const data = new TextEncoder().encode('payload')
+    const form = new FormData()
+    form.set('path', p)
+    form.set('file', new Blob([data], { type: 'application/octet-stream' }), 'file.bin')
+    const r = await raw('/fs/upload', { method: 'POST', body: form })
+    if (r.status !== 200) throw new Error('upload failed')
+    const st = await fsp.stat(p)
+    if (st.size !== data.length) throw new Error('size mismatch')
+  })
+
+  await runTest('fs', 'set_file_permissions', async () => {
+    const p = tmpPath('perm.txt')
+    await raw(`/fs/write_file?path=${encodeURIComponent(p)}&mode=0644`, { method: 'PUT', body: Buffer.from('x') })
+    const r = await j('/fs/set_file_permissions', { method: 'PUT', body: JSON.stringify({ path: p, mode: '0755' }) })
+    if (r.status !== 200) throw new Error('set perms failed')
+  })
+
+  await runTest('fs', 'tail/stream yields events', async () => {
+    const p = tmpPath('tail.log')
+    await raw(`/fs/write_file?path=${encodeURIComponent(p)}&mode=0644`, { method: 'PUT', body: Buffer.from('initial\n') })
+    const res = await raw(`/fs/tail/stream?path=${encodeURIComponent(p)}`)
+    if (res.status !== 200 || res.headers.get('Content-Type')?.startsWith('text/event-stream') !== true) throw new Error('tail stream failed')
+    const reader = res.body.getReader()
+    const line = `new line ${Date.now()}\n`
+    await fsp.appendFile(p, line)
+    let found = false
+    const endAt = now() + 5000
+    while (now() < endAt && !found) {
+      const { done, value } = await reader.read()
+      if (done) break
+      const chunk = new TextDecoder().decode(value)
+      if (chunk.includes(line.trim())) found = true
+      await new Promise(r => setTimeout(r, 150))
+    }
+    try { reader.cancel() } catch { }
+    if (!found) throw new Error('no tail event seen')
+  })
+
+  await runTest('fs', 'watch events', async () => {
+    const dir = tmpPath('watch-dir')
+    await fsp.mkdir(dir, { recursive: true })
+    let r = await j('/fs/watch', { method: 'POST', body: JSON.stringify({ path: dir, recursive: true }) })
+    if (r.status !== 200 || !r.body.watch_id) throw new Error('watch start failed')
+    const wid = r.body.watch_id
+    const stream = await raw(`/fs/watch/${wid}/events`)
+    if (stream.status !== 200) throw new Error('watch stream failed')
+    const reader = stream.body.getReader()
+    const testFile = join(dir, `t-${Date.now()}.txt`)
+    await fsp.writeFile(testFile, 'content')
+    let got = false
+    const endAt = now() + 5000
+    while (now() < endAt && !got) {
+      const { done, value } = await reader.read()
+      if (done) break
+      const chunk = new TextDecoder().decode(value)
+      if (chunk.includes(testFile.split('/').pop())) got = true
+      await new Promise(r => setTimeout(r, 150))
+    }
+    try { reader.cancel() } catch { }
+    await j(`/fs/watch/${wid}`, { method: 'DELETE' })
+    if (!got) throw new Error('no watch event seen')
+    try { await fsp.unlink(testFile) } catch { }
+    try { await fsp.rmdir(dir) } catch { }
+  })
+}
+
+async function suite_input() {
+  const haveXdotool = hasCmd(process.env.XDOTOOL_BIN || 'xdotool')
+  const skipReason = haveXdotool ? false : 'xdotool not found'
+
+  await runTest('input', 'mouse basic', async () => {
+    let r = await j('/input/mouse/move', { method: 'POST', body: JSON.stringify({ x: 100, y: 100 }) })
+    if (r.status !== 200) throw new Error('move failed')
+    r = await j('/input/mouse/click', { method: 'POST', body: JSON.stringify({ button: 'left', count: 1 }) })
+    if (r.status !== 200) throw new Error('click failed')
+    r = await j('/input/mouse/location')
+    if (r.status !== 200 || typeof r.body.x !== 'number') throw new Error('location failed')
+  }, { skipIf: skipReason })
+
+  await runTest('input', 'keyboard basic', async () => {
+    let r = await j('/input/keyboard/type', { method: 'POST', body: JSON.stringify({ text: 'test', wpm: 300 }) })
+    if (r.status !== 200) throw new Error('type failed')
+    r = await j('/input/keyboard/key', { method: 'POST', body: JSON.stringify({ keys: ['Return'] }) })
+    if (r.status !== 200) throw new Error('key failed')
+  }, { skipIf: skipReason })
+
+  await runTest('input', 'window ops and combos (best-effort)', async () => {
+    const ok = s => [200, 404].includes(s)
+    let r = await j('/input/window/move_resize', { method: 'POST', body: JSON.stringify({ match: { name: 'chromium' }, x: 0, y: 0, width: 800, height: 600 }) })
+    if (!ok(r.status)) throw new Error('move_resize bad status')
+    r = await j('/input/combo/window/center', { method: 'POST', body: JSON.stringify({ match: { name: 'chromium' }, width: 800, height: 600 }) })
+    if (!ok(r.status)) throw new Error('center bad status')
+    r = await j('/input/combo/window/snap', { method: 'POST', body: JSON.stringify({ match: { name: 'chromium' }, position: 'left' }) })
+    if (!ok(r.status)) throw new Error('snap bad status')
+  }, { skipIf: skipReason })
+}
+
+async function suite_logs() {
+  await runTest('logs', 'rejects bad request', async () => {
+    const res = await raw('/logs/stream')
+    if (res.status !== 400) throw new Error('should be 400')
+  })
+}
+
+async function suite_macros() {
+  await runTest('macros', 'create/list/delete + run + invalid run', async () => {
+    const create = await j('/macros/create', { method: 'POST', body: JSON.stringify({ name: 'type-hello', steps: [{ action: 'sleep', ms: 5 }, { action: 'keyboard.type', text: 'hello' }] }) })
+    if (create.status !== 200) throw new Error('create failed')
+    const id = create.body.macro_id
+    const list = await j('/macros/list')
+    if (list.status !== 200 || !Array.isArray(list.body.items)) throw new Error('list failed')
+    const run = await j('/macros/run', { method: 'POST', body: JSON.stringify({ macro_id: id }) })
+    if (run.status !== 200) throw new Error('run failed')
+    const invalid = await j('/macros/run', { method: 'POST', body: JSON.stringify({ macro_id: 'nope' }) })
+    if (invalid.status !== 404) throw new Error('invalid run should be 404')
+    const del = await j(`/macros/${id}`, { method: 'DELETE' })
+    if (del.status !== 200) throw new Error('delete failed')
+  })
+}
+
+async function suite_metrics() {
+  await runTest('metrics', 'snapshot', async () => {
+    const r = await j('/metrics/snapshot')
+    if (r.status !== 200 || typeof r.body.cpu_pct !== 'number') throw new Error('bad snapshot')
+  })
+  await runTest('metrics', 'stream yields', async () => {
+    const ev = await readSSE('/metrics/stream', { max: 2, timeoutMs: 4000 })
+    if (!Array.isArray(ev) || ev.length < 1) throw new Error('no events')
+  })
+}
+
+async function suite_network() {
+  await runTest('network', 'apply/delete intercept rules', async () => {
+    const rules = { rules: [{ match: { method: 'GET', host_contains: 'example.com' }, action: { type: 'block' } }] }
+    const apply = await j('/network/intercept/rules', { method: 'POST', body: JSON.stringify(rules) })
+    if (apply.status !== 200) throw new Error('apply failed')
+    const del = await j(`/network/intercept/rules/${apply.body.rule_set_id}`, { method: 'DELETE' })
+    if (del.status !== 200) throw new Error('delete failed')
+  })
+  await runTest('network', 'HAR stream opens', async () => {
+    const res = await raw('/network/har/stream')
+    if (res.status !== 200) throw new Error('har stream failed')
+    const reader = res.body.getReader()
+    await reader.cancel()
+  })
+}
+
+async function suite_os() {
+  await runTest('os', 'locale get/post', async () => {
+    let r = await j('/os/locale')
+    if (r.status !== 200) throw new Error('get failed')
+    r = await j('/os/locale', { method: 'POST', body: JSON.stringify({ locale: 'en_US.UTF-8', timezone: 'UTC', keyboard_layout: 'us' }) })
+    if (r.status !== 200 || r.body.updated !== true) throw new Error('post failed')
+  })
+}
+
+async function suite_pipe() {
+  await runTest('pipe', 'send/recv', async () => {
+    const recv = readSSE('/pipe/recv/stream?channel=x', { max: 1, timeoutMs: 4000 })
+    const send = await j('/pipe/send', { method: 'POST', body: JSON.stringify({ channel: 'x', object: { n: 42 } }) })
+    if (send.status !== 200) throw new Error('send failed')
+    const ev = await recv
+    if (!Array.isArray(ev) || ev.length < 1 || ev[0].object?.n !== 42) throw new Error('bad event')
+  })
+}
+
+async function suite_process() {
+  await runTest('process', 'exec', async () => {
+    const r = await j('/process/exec', { method: 'POST', body: JSON.stringify({ command: 'bash', args: ['-lc', 'printf hi'] }) })
+    if (r.status !== 200) throw new Error('exec failed')
+    const out = Buffer.from(r.body.stdout_b64, 'base64').toString('utf8')
+    if (out !== 'hi') throw new Error('stdout mismatch')
+  })
+  await runTest('process', 'spawn/status/stream/kill', async () => {
+    const start = await j('/process/spawn', { method: 'POST', body: JSON.stringify({ command: 'bash', args: ['-lc', 'for i in 1 2 3; do echo $i; sleep 1; done'] }) })
+    if (start.status !== 200) throw new Error('spawn failed')
+    const pid = start.body.process_id
+    const status = await j(`/process/${pid}/status`)
+    if (status.status !== 200) throw new Error('status failed')
+    const ev = await readSSE(`/process/${pid}/stdout/stream`, { max: 2, timeoutMs: 6000 })
+    if (!Array.isArray(ev) || ev.length < 1) throw new Error('no stream')
+    const kill = await j(`/process/${pid}/kill`, { method: 'POST', body: JSON.stringify({ signal: 'TERM' }) })
+    if (kill.status !== 200) throw new Error('kill failed')
+  })
+}
+
+async function suite_recording() {
+  const haveFFmpeg = hasCmd(process.env.FFMPEG_BIN || 'ffmpeg')
+  await runTest('recording', 'start/list/stop/download/delete', async () => {
+    let r = await j('/recording/start', { method: 'POST', body: JSON.stringify({ id: 't1', maxDurationInSeconds: 1 }) })
+    if (r.status !== 201) throw new Error('start failed')
+    r = await j('/recording/list')
+    if (r.status !== 200) throw new Error('list failed')
+    await new Promise(res => setTimeout(res, 1500))
+    const d = await raw('/recording/download?id=t1')
+    if (![200, 404, 202].includes(d.status)) throw new Error('download bad status')
+    const del = await j('/recording/delete', { method: 'POST', body: JSON.stringify({ id: 't1' }) })
+    if (![200, 404].includes(del.status)) throw new Error('delete bad status')
+  }, { skipIf: haveFFmpeg ? false : 'ffmpeg missing' })
+}
+
+async function suite_screenshot() {
+  const haveFFmpeg = hasCmd(process.env.FFMPEG_BIN || 'ffmpeg')
+  const haveGrim = hasCmd('grim')
+  await runTest('screenshot', 'capture returns image bytes (best-effort)', async () => {
+    const r = await j('/screenshot/capture', { method: 'POST', body: JSON.stringify({ format: 'png' }) })
+    if (![200, 500].includes(r.status)) throw new Error('bad status')
+    if (r.status === 200) {
+      if (!r.body.bytes_b64 || !r.body.content_type) throw new Error('missing fields')
+    }
+  }, { skipIf: (haveFFmpeg || haveGrim) ? false : 'ffmpeg/grim missing' })
+}
+
+async function suite_scripts() {
+  await runTest('scripts', 'upload/list/run/delete', async () => {
+    const scriptPath = tmpPath('script.sh')
+    const shebang = '#!/usr/bin/env bash\n'
+    const form = new FormData()
+    form.set('path', scriptPath)
+    form.set('file', new Blob([shebang + 'echo hi'], { type: 'text/x-shellscript' }), 'script.sh')
+    form.set('executable', 'true')
+    const up = await raw('/scripts/upload', { method: 'POST', body: form })
+    if (up.status !== 200) throw new Error('upload failed')
+    const list = await j('/scripts/list')
+    if (list.status !== 200 || !Array.isArray(list.body.items)) throw new Error('list failed')
+    const run = await j('/scripts/run', { method: 'POST', body: JSON.stringify({ path: scriptPath }) })
+    if (run.status !== 200) throw new Error('run failed')
+    const out = Buffer.from(run.body.stdout_b64, 'base64').toString('utf8').trim()
+    if (out !== 'hi') throw new Error('stdout mismatch')
+    const del = await j('/scripts/delete', { method: 'DELETE', body: JSON.stringify({ path: scriptPath }) })
+    if (del.status !== 200) throw new Error('delete failed')
+  })
+}
+
+async function suite_stream() {
+  const haveFFmpeg = hasCmd(process.env.FFMPEG_BIN || 'ffmpeg')
+  await runTest('stream', 'start metrics stream then stop (best-effort)', async () => {
+    const start = await j('/stream/start', { method: 'POST', body: JSON.stringify({ rtmps_url: 'rtmps://example.com/live', stream_key: 'testkey', fps: 1, audio: { capture_system: false } }) })
+    if (![200, 400].includes(start.status)) throw new Error('start bad status')
+    if (start.status === 200) {
+      const { stream_id } = start.body
+      const ev = await readSSE(`/stream/${stream_id}/metrics/stream`, { max: 1, timeoutMs: 5000 })
+      if (!Array.isArray(ev)) throw new Error('no metrics')
+      const stop = await j('/stream/stop', { method: 'POST', body: JSON.stringify({ stream_id }) })
+      if (stop.status !== 200) throw new Error('stop failed')
+    }
+  }, { skipIf: haveFFmpeg ? false : 'ffmpeg missing' })
+}
+async function suite_browser_ext() {
+  await runTest('browser-ext', 'add unpacked extension from GitHub', async () => {
+    // Create form data for the extension upload
+    const form = new FormData()
+    form.set('github_url', 'https://github.com/raiden-staging/kernel-chrome-ext')
+    
+    const r = await raw('/browser/extension/add/unpacked', { 
+      method: 'POST', 
+      body: form
+    })
+    
+    const body = await r.json()
+    if (r.status !== 201) throw new Error(`bad status ${r.status}`)
+    if (!body.id || !body.version) throw new Error('missing extension details')
+    console.log(chalk.gray(`Extension ID: ${body.id}, Version: ${body.version}`))
+  })
+  
+  await runTest('browser-ext', 'add unpacked extension from file', async () => {
+    // Create a test zip file
+    const testZipPath = tmpPath('test-extension.zip')
+    // This test would need a real zip file with extension content
+    // For now we'll just check if the endpoint handles file uploads correctly
+    
+    const form = new FormData()
+    form.set('archive_file', new Blob(['test content'], { type: 'application/zip' }), 'test-extension.zip')
+    
+    const r = await raw('/browser/extension/add/unpacked', { 
+      method: 'POST', 
+      body: form
+    })
+    
+    // This will likely fail with 500 since we're not providing a real extension zip
+    // But we're testing the form handling, not the extension loading
+    if (![201, 500].includes(r.status)) throw new Error(`unexpected status ${r.status}`)
+  })
+}
+
+// ---------------------------- Runner ----------------------------
+const SUITES = [
+  ['health', suite_health],
+  // ['browser', suite_browser],
+  ['browser-ext', suite_browser_ext],
+  ['bus', suite_bus],
+  ['clipboard', suite_clipboard],
+  ['fs', suite_fs],
+  ['input', suite_input],
+  ['logs', suite_logs],
+  ['macros', suite_macros],
+  ['metrics', suite_metrics],
+  ['network', suite_network],
+  ['os', suite_os],
+  ['pipe', suite_pipe],
+  ['process', suite_process],
+  ['recording', suite_recording],
+  ['screenshot', suite_screenshot],
+  ['scripts', suite_scripts],
+  ['stream', suite_stream],
+]
+
+async function main() {
+  // If no parameters specified and not running all tests, display available tests and exit
+  if (!RUN_ALL && names.length === 0) {
+    console.log(chalk.bgBlue.white(' AVAILABLE TESTS '))
+    console.log(chalk.gray('─'.repeat(78)))
+    
+    // Group tests by category
+    const categories = {}
+    for (const [cat, _] of SUITES) {
+      if (!categories[cat]) categories[cat] = true
+    }
+    
+    // Display available test categories
+    console.log(chalk.yellow('Categories:'))
+    Object.keys(categories).sort().forEach(cat => {
+      console.log(`  ${chalk.green('•')} ${chalk.cyan(cat)}`)
+    })
+    
+    console.log('')
+    console.log(chalk.yellow('Usage:'))
+    console.log(`  ${chalk.green('•')} Run all tests: ${chalk.white('--all')}`)
+    console.log(`  ${chalk.green('•')} Run specific categories: ${chalk.white('input fs network')}`)
+    
+    return
+  }
+
+  banner('Kernel Computer Operator API — Test Runner')
+  console.log(chalk.white(`Base URL: ${BASE_URL}`))
+  console.log(chalk.white(`Mode: ${RUN_ALL ? 'all' : (names.length ? `subset: ${names.join(', ')}` : 'default')}`))
+  console.log(chalk.white('Server: external only (never spawned)'))
+  console.log(chalk.white('Verbosity: always on'))
+
+  // Probe health once; fail fast if unreachable
+  try {
+    const r = await j('/health')
+    if (r.status !== 200) throw new Error('unhealthy')
+  } catch (e) {
+    console.error(chalk.bgRed.white(' FATAL '), `Cannot reach server at ${BASE_URL} /health :: ${String(e && e.message || e)}`)
+    process.exit(1)
+  }
+
+  const startAll = now()
+  for (const [cat, fn] of SUITES) {
+    if (!filterCategory(cat)) continue
+    banner(`Suite: ${cat}`)
+    try { await fn() } catch { }
+  }
+  const totalMs = now() - startAll
+
+  // Summary
+  const pass = RESULTS.filter(r => r.status === 'PASS').length
+  const fail = RESULTS.filter(r => r.status === 'FAIL').length
+  const skip = RESULTS.filter(r => r.status === 'SKIP').length
+  const total = RESULTS.length
+  const coverage = total > 0 ? Math.round(((pass + fail) / total) * 100) : 0
+  const reliability = (pass + fail) > 0 ? Math.round((pass / (pass + fail)) * 100) : 0
+
+  banner('Summary')
+  const lines = [
+    `Total: ${total}`,
+    `Pass:  ${pass}`,
+    `Fail:  ${fail}`,
+    `Skip:  ${skip}`,
+    `Elapsed: ${ms(totalMs)}`,
+    `Coverage: ${coverage}%`,
+    `Reliability: ${reliability}%`
+  ]
+  const width = Math.max(...lines.map(s => s.length)) + 4
+  const top = '┌' + '─'.repeat(width - 2) + '┐'
+  const bot = '└' + '─'.repeat(width - 2) + '┘'
+  console.log(chalk.gray(top))
+  for (const s of lines) console.log(chalk.gray('│ ') + s.padEnd(width - 4) + chalk.gray(' │'))
+  console.log(chalk.gray(bot))
+
+  // Failures detail
+  const failed = RESULTS.filter(r => r.status === 'FAIL')
+  if (failed.length) {
+    banner('Failures')
+    for (const f of failed) {
+      console.log(chalk.red(`• [${f.category}] ${f.name}  ${ms(f.ms)}  :: ${f.error || ''}`))
+    }
+  }
+
+  process.exit(fail > 0 ? 1 : 0)
+}
+
+// Entrypoint
+main().catch((e) => {
+  console.error(chalk.bgRed.white(' FATAL '), String(e && e.message || e))
+  process.exit(1)
+})
diff --git a/operator-api/test.js.bak b/operator-api/test.js.bak
new file mode 100644
index 00000000..9008fda2
--- /dev/null
+++ b/operator-api/test.js.bak
@@ -0,0 +1,185 @@
+#!/usr/bin/env node
+
+import { spawn } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+import { existsSync } from 'node:fs';
+import { readdir } from 'node:fs/promises';
+import chalk from 'chalk'
+import { createWriteStream } from 'node:fs';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+/**
+ * Lists all available test files in the tests directory
+ * @returns {Promise<string[]>} Array of test file paths
+ */
+async function listAvailableTests() {
+  try {
+    const testsDir = join(__dirname, 'tests');
+    const files = await readdir(testsDir);
+    return files
+      .filter(file => file.endsWith('.test.js'))
+      .sort((a, b) => a.localeCompare(b));
+  } catch (error) {
+    console.error(chalk.red(`Error listing test files: ${error.message}`));
+    return [];
+  }
+}
+/**
+ * Prints available tests in a formatted way
+ */
+async function printAvailableTests() {
+  const tests = await listAvailableTests();
+  
+  if (tests.length === 0) {
+    console.log(chalk.yellow('No test files found in the tests directory.'));
+    return;
+  }
+  
+  console.log(chalk.bold.blue('\n📋 Available Tests:'));
+  console.log(chalk.gray('─'.repeat(50)));
+  
+  tests.forEach((test, index) => {
+    const testName = test.replace('.test.js', '');
+    console.log(`${chalk.green(`[${index + 1}]`)} ${chalk.white(testName)}`);
+  });
+  
+  console.log(chalk.gray('─'.repeat(50)));
+  console.log(chalk.italic(`Run a specific test with: ${chalk.cyan('bun test.js <test-name>')}\n`));
+  
+  // Add a final separator before tests start
+  console.log(chalk.gray('═'.repeat(70)));
+  console.log(chalk.bold.green('▶ Starting Tests...'));
+  console.log(chalk.gray('═'.repeat(70)) + '\n');
+}
+
+printAvailableTests()
+
+// Parse command line arguments
+const args = process.argv.slice(2);
+const testFiles = [];
+const vitestArgs = [];
+let runAllTests = false;
+
+// Process arguments
+args.forEach(arg => {
+  if (arg === '--all') {
+    runAllTests = true;
+  } else if (arg.startsWith('--') || arg.startsWith('-')) {
+    vitestArgs.push(arg);
+  } else {
+    testFiles.push(arg);
+  }
+});
+
+// If --all flag is provided, run all tests with output to log file
+if (runAllTests) {
+  console.log(chalk.bold.blue('Running all tests and logging output to /tmp/kernel-operator.tests.log'));
+  
+  const logStream = createWriteStream('/tmp/kernel-operator.tests.log');
+  
+  // Get all test files
+  listAvailableTests().then(allTests => {
+    const allTestPaths = allTests.map(test => join(__dirname, 'tests', test));
+    
+    // Build vitest command for all tests
+    const command = 'npx';
+    const commandArgs = [
+      'vitest',
+      'run',
+      ...allTestPaths,
+      ...vitestArgs
+    ];
+    
+    // Run the tests with output to both console and log file
+    const testProcess = spawn(command, commandArgs, {
+      env: {
+        ...process.env,
+        PORT: '10001'
+      }
+    });
+    
+    testProcess.stdout.on('data', (data) => {
+      process.stdout.write(data);
+      logStream.write(data);
+    });
+    
+    testProcess.stderr.on('data', (data) => {
+      process.stderr.write(data);
+      logStream.write(data);
+    });
+    
+    testProcess.on('close', code => {
+      logStream.end();
+      console.log(chalk.gray('─'.repeat(50)));
+      console.log(chalk.bold(`Test logs saved to: ${chalk.cyan('/tmp/kernel-operator.tests.log')}`));
+      process.exit(code);
+    });
+  });
+} else {
+  // If no test files specified, run all tests
+  if (testFiles.length === 0) {
+    console.log('Running all tests...');
+  } else {
+    console.log(`Running tests: ${testFiles.join(', ')}`);
+  }
+
+  // Prepare test file paths
+  const testPaths = testFiles.map(file => {
+    // If file doesn't end with .test.js, add it
+    const testFile = file.endsWith('.test.js') ? file : `${file}.test.js`;
+    return join(__dirname, 'tests', testFile);
+  }).filter(path => {
+    const exists = existsSync(path);
+    if (!exists) {
+      console.warn(`Warning: Test file not found: ${path}`);
+    }
+    return exists;
+  });
+
+  // Build vitest command
+  const command = 'npx';
+  const commandArgs = [
+    'vitest',
+    'run',
+    ...(testPaths.length > 0 ? testPaths : []),
+    ...vitestArgs
+  ];
+
+  // Run the tests
+  const testProcess = spawn(command, commandArgs, {
+    stdio: 'inherit',
+    shell: true,
+    env: {
+      ...process.env,
+      PORT: '10001' // Ensure PORT is set in the environment for BASE_URL in tests
+    }
+  });
+
+  testProcess.on('close', code => {
+    process.exit(code);
+  });
+}
+
+/*
+Examples of how to use this test runner:
+
+1. Run all tests:
+   bun test.js
+
+2. Run a specific test file:
+   bun test.js screenshot
+
+3. Run multiple test files:
+   bun test.js screenshot stream
+
+4. Run with vitest options:
+   bun test.js screenshot --watch
+
+5. Run with both file and options:
+   bun test.js screenshot --bail
+   
+6. Run all tests with output logged to file:
+   bun test.js --all
+*/
diff --git a/operator-api/tests.docker.log b/operator-api/tests.docker.log
new file mode 100644
index 00000000..e4aa1f9d
--- /dev/null
+++ b/operator-api/tests.docker.log
@@ -0,0 +1,497 @@
+──────────────────────────────────────────────────────────────────────────────
+Kernel Computer Operator API — Test Runner
+──────────────────────────────────────────────────────────────────────────────
+Base URL: http://127.0.0.1:10001
+Mode: all
+Server: external only (never spawned)
+Verbosity: always on
+[http] curl -sS -X GET "http://127.0.0.1:10001/health" -H "content-type: application/json"
+[http] status=200
+[body] {
+  "status": "ok",
+  "uptime_sec": 10
+}
+──────────────────────────────────────────────────────────────────────────────
+Suite: health
+──────────────────────────────────────────────────────────────────────────────
+[http] curl -sS -X GET "http://127.0.0.1:10001/health" -H "content-type: application/json"
+[http] status=200
+[body] {
+  "status": "ok",
+  "uptime_sec": 10
+}
+ PASS  [health] GET /health is ok  3ms
+──────────────────────────────────────────────────────────────────────────────
+Suite: bus
+──────────────────────────────────────────────────────────────────────────────
+[sse] connect http://127.0.0.1:10001/bus/subscribe?channel=ch1 max=1 timeout=4000
+[http] curl -sS -X POST "http://127.0.0.1:10001/bus/publish" -H "content-type: application/json" -d '{"channel":"ch1","type":"note","payload":{"msg":"hello"}}'
+[sse] data event: data\ndata: {"ts":"2025-08-11T03:04:35.501Z","type":"note","payload":{"msg":"hello"}}\n\n
+[sse] event {"ts":"2025-08-11T03:04:35.501Z","type":"note","payload":{"msg":"hello"}}
+[http] status=200
+[body] {
+  "delivered": true
+}
+ PASS  [bus] publish/subscribe SSE  13ms
+──────────────────────────────────────────────────────────────────────────────
+Suite: clipboard
+──────────────────────────────────────────────────────────────────────────────
+[http] curl -sS -X GET "http://127.0.0.1:10001/clipboard" -H "content-type: application/json"
+[http] status=200
+[body] {
+  "type": "text",
+  "text": ""
+}
+ PASS  [clipboard] GET /clipboard responds  38ms
+[http] curl -sS -X POST "http://127.0.0.1:10001/clipboard" -H "content-type: application/json" -d '{"type":"text","text":"Test 1754881475551"}'
+ FAIL  [clipboard] stream detects change (best-effort)  30001ms  :: timeout after 30000ms
+──────────────────────────────────────────────────────────────────────────────
+Suite: fs
+──────────────────────────────────────────────────────────────────────────────
+[tmp] /tmp/fsdir-bewpd29tm3u
+[http] curl -sS -X PUT "http://127.0.0.1:10001/fs/create_directory" -H "content-type: application/json" -d '{"path":"/tmp/fsdir-bewpd29tm3u","mode":"0755"}'
+[http] status=201
+[body] {
+  "ok": true
+}
+[http] curl -sS -X GET "http://127.0.0.1:10001/fs/list_files?path=%2Ftmp" -H "content-type: application/json"
+[http] status=200
+[body] [
+  {
+    "name": "runtime-kernel",
+    "path": "/tmp/runtime-kernel",
+    "size_bytes": 0,
+    "is_dir": true,
+    "mod_time": "2025-08-11T03:04:23.843Z",
+    "mode": "755"
+  },
+  {
+    "name": ".chromium",
+    "path": "/tmp/.chromium",
+    "size_bytes": 0,
+    "is_dir": true,
+    "mod_time": "2025-08-11T03:04:24.899Z",
+    "mode": "700"
+  },
+  {
+    "name": "kernel-operator",
+    "path": "/tmp/kernel-operator",
+    "size_bytes": 0,
+    "is_dir": true,
+    "mod_time": "2025-08-11T03:04:35.383Z",
+    "mode": "755"
+  },
+  {
+    "name": ".X11-unix",
+    "path": "/tmp/.X11-unix",
+    "size_bytes": 0,
+    "is_dir": true,
+    "mod_time": "2025-08-11T03:04:21.471Z",
+    "mode": "1777"
+  },
+  {
+    "name": "fsdir-bewpd29tm3u",
+    "path": "/tmp/fsdir-bewpd29tm3u",
+    "size_bytes": 0,
+    "is_dir": true,
+    "mod_time": "2025-08-11T03:05:05.551Z",
+    "mode": "755"
+  },
+  {
+    "name": ".X1-lock",
+    "path": "/tmp/.X1-lock",
+    "size_bytes": 11,
+    "is_dir": false,
+    "mod_time": "2025-08-11T03:04:21.471Z",
+    "mode": "444"
+  },
+  {
+    "name": "xf86-input-neko.sock",
+    "path": "/tmp/xf86-input-neko.sock",
+    "size_bytes": 0,
+    "is_dir": false,
+    "mod_time": "2025-08-11T03:04:21.571Z",
+    "mode": "666"
+  },
+  {
+    "name": "chromium.log",
+    "path": "/tmp/chromium.log",
+    "size_bytes": 381,
+    "is_dir": false,
+    "mod_time": "2025-08-11T03:04:50.895Z",
+    "mode": "644"
+  },
+  {
+    "name": ".org.chromium.Chromium.ZDXFSK",
+    "path": "/tmp/.org.chromium.Chromium.ZDXFSK",
+    "size_bytes": 0,
+    "is_dir": true,
+    "mod_time": "2025-08-11T03:04:24.615Z",
+    "mode": "700"
+  }
+]
+[http] curl -sS -X GET "http://127.0.0.1:10001/fs/file_info?path=%2Ftmp%2Ffsdir-bewpd29tm3u" -H "content-type: application/json"
+[http] status=200
+[body] {
+  "name": "fsdir-bewpd29tm3u",
+  "path": "/tmp/fsdir-bewpd29tm3u",
+  "size_bytes": 0,
+  "is_dir": true,
+  "mod_time": "2025-08-11T03:05:05.551Z",
+  "mode": "d755"
+}
+[http] curl -sS -X PUT "http://127.0.0.1:10001/fs/delete_directory" -H "content-type: application/json" -d '{"path":"/tmp/fsdir-bewpd29tm3u"}'
+[http] status=200
+[body] {
+  "ok": true
+}
+ PASS  [fs] create/list/file_info/delete_directory  11ms
+[tmp] /tmp/fsfile.txt-j9kw33itxy
+[http] raw curl -sS -X PUT "http://127.0.0.1:10001/fs/write_file?path=%2Ftmp%2Ffsfile.txt-j9kw33itxy&mode=0644"
+[http] raw curl -sS -X GET "http://127.0.0.1:10001/fs/read_file?path=%2Ftmp%2Ffsfile.txt-j9kw33itxy"
+[http] raw curl -sS -X GET "http://127.0.0.1:10001/fs/download?path=%2Ftmp%2Ffsfile.txt-j9kw33itxy"
+[tmp] /tmp/fsfile2.txt-hb0n1iijnlv
+[http] curl -sS -X PUT "http://127.0.0.1:10001/fs/move" -H "content-type: application/json" -d '{"src_path":"/tmp/fsfile.txt-j9kw33itxy","dest_path":"/tmp/fsfile2.txt-hb0n1iijnlv"}'
+[http] status=200
+[body] {
+  "ok": true
+}
+[http] curl -sS -X PUT "http://127.0.0.1:10001/fs/delete_file" -H "content-type: application/json" -d '{"path":"/tmp/fsfile2.txt-hb0n1iijnlv"}'
+[http] status=200
+[body] {
+  "ok": true
+}
+ PASS  [fs] write/read/download/move/delete_file  17ms
+[tmp] /tmp/upload.bin-m6triwf7qd
+[http] raw curl -sS -X POST "http://127.0.0.1:10001/fs/upload"
+ PASS  [fs] upload  6ms
+[tmp] /tmp/perm.txt-190q45tab5q
+[http] raw curl -sS -X PUT "http://127.0.0.1:10001/fs/write_file?path=%2Ftmp%2Fperm.txt-190q45tab5q&mode=0644"
+[http] curl -sS -X PUT "http://127.0.0.1:10001/fs/set_file_permissions" -H "content-type: application/json" -d '{"path":"/tmp/perm.txt-190q45tab5q","mode":"0755"}'
+[http] status=200
+[body] {
+  "ok": true
+}
+ PASS  [fs] set_file_permissions  5ms
+[tmp] /tmp/tail.log-n5gkubl324
+[http] raw curl -sS -X PUT "http://127.0.0.1:10001/fs/write_file?path=%2Ftmp%2Ftail.log-n5gkubl324&mode=0644"
+[http] raw curl -sS -X GET "http://127.0.0.1:10001/fs/tail/stream?path=%2Ftmp%2Ftail.log-n5gkubl324"
+ PASS  [fs] tail/stream yields events  1160ms
+[tmp] /tmp/watch-dir-5eazd8pflaa
+[http] curl -sS -X POST "http://127.0.0.1:10001/fs/watch" -H "content-type: application/json" -d '{"path":"/tmp/watch-dir-5eazd8pflaa","recursive":true}'
+[http] status=201
+[body] {
+  "watch_id": "xwnhmq3wlt"
+}
+ FAIL  [fs] watch events  8ms  :: watch start failed
+──────────────────────────────────────────────────────────────────────────────
+Suite: input
+──────────────────────────────────────────────────────────────────────────────
+[http] curl -sS -X POST "http://127.0.0.1:10001/input/mouse/move" -H "content-type: application/json" -d '{"x":100,"y":100}'
+[http] status=200
+[body] {
+  "ok": true
+}
+[http] curl -sS -X POST "http://127.0.0.1:10001/input/mouse/click" -H "content-type: application/json" -d '{"button":"left","count":1}'
+[http] status=200
+[body] {
+  "ok": true
+}
+[http] curl -sS -X GET "http://127.0.0.1:10001/input/mouse/location" -H "content-type: application/json"
+[http] status=200
+[body] {
+  "x": 100,
+  "y": 100,
+  "screen": 0,
+  "window": "10485764"
+}
+ PASS  [input] mouse basic  128ms
+[http] curl -sS -X POST "http://127.0.0.1:10001/input/keyboard/type" -H "content-type: application/json" -d '{"text":"test","wpm":300}'
+[http] status=200
+[body] {
+  "ok": true
+}
+[http] curl -sS -X POST "http://127.0.0.1:10001/input/keyboard/key" -H "content-type: application/json" -d '{"keys":["Return"]}'
+[http] status=200
+[body] {
+  "ok": true
+}
+ PASS  [input] keyboard basic  113ms
+[http] curl -sS -X POST "http://127.0.0.1:10001/input/window/move_resize" -H "content-type: application/json" -d '{"match":{"name":"chromium"},"x":0,"y":0,"width":800,"height":600}'
+[http] status=200
+[body] {
+  "ok": true,
+  "wid": "10485760"
+}
+[http] curl -sS -X POST "http://127.0.0.1:10001/input/combo/window/center" -H "content-type: application/json" -d '{"match":{"name":"chromium"},"width":800,"height":600}'
+[http] status=200
+[body] {
+  "ok": true,
+  "wid": "10485760",
+  "x": 112,
+  "y": 84,
+  "width": 800,
+  "height": 600
+}
+[http] curl -sS -X POST "http://127.0.0.1:10001/input/combo/window/snap" -H "content-type: application/json" -d '{"match":{"name":"chromium"},"position":"left"}'
+[http] status=200
+[body] {
+  "ok": true,
+  "wid": "10485760",
+  "x": 0,
+  "y": 0,
+  "width": 512,
+  "height": 768
+}
+ PASS  [input] window ops and combos (best-effort)  76ms
+──────────────────────────────────────────────────────────────────────────────
+Suite: logs
+──────────────────────────────────────────────────────────────────────────────
+[http] raw curl -sS -X GET "http://127.0.0.1:10001/logs/stream"
+ PASS  [logs] rejects bad request  2ms
+──────────────────────────────────────────────────────────────────────────────
+Suite: macros
+──────────────────────────────────────────────────────────────────────────────
+[http] curl -sS -X POST "http://127.0.0.1:10001/macros/create" -H "content-type: application/json" -d '{"name":"type-hello","steps":[{"action":"sleep","ms":5},{"action":"keyboard.type","text":"hello"}]}'
+[http] status=200
+[body] {
+  "macro_id": "eu72hl09sb"
+}
+[http] curl -sS -X GET "http://127.0.0.1:10001/macros/list" -H "content-type: application/json"
+[http] status=200
+[body] {
+  "items": [
+    {
+      "macro_id": "eu72hl09sb",
+      "name": "type-hello",
+      "steps_count": 2
+    }
+  ]
+}
+[http] curl -sS -X POST "http://127.0.0.1:10001/macros/run" -H "content-type: application/json" -d '{"macro_id":"eu72hl09sb"}'
+[http] status=200
+[body] {
+  "started": true,
+  "run_id": "yz1rbmr9r0"
+}
+[http] curl -sS -X POST "http://127.0.0.1:10001/macros/run" -H "content-type: application/json" -d '{"macro_id":"nope"}'
+[http] status=404
+[body] {
+  "message": "Not Found"
+}
+[http] curl -sS -X DELETE "http://127.0.0.1:10001/macros/eu72hl09sb" -H "content-type: application/json"
+[http] status=200
+[body] {
+  "ok": true
+}
+ PASS  [macros] create/list/delete + run + invalid run  12ms
+──────────────────────────────────────────────────────────────────────────────
+Suite: metrics
+──────────────────────────────────────────────────────────────────────────────
+[http] curl -sS -X GET "http://127.0.0.1:10001/metrics/snapshot" -H "content-type: application/json"
+[http] status=200
+[body] {
+  "cpu_pct": 0,
+  "gpu_pct": 0,
+  "mem": {
+    "used_bytes": 12187107328,
+    "total_bytes": 16776560640
+  },
+  "disk": {
+    "read_bps": 0,
+    "write_bps": 0
+  },
+  "net": {
+    "rx_bps": 0,
+    "tx_bps": 0
+  }
+}
+ PASS  [metrics] snapshot  1ms
+[sse] connect http://127.0.0.1:10001/metrics/stream max=2 timeout=4000
+[sse] data event: data\ndata: {"ts":"2025-08-11T03:05:08.101Z","cpu_pct":0,"gpu_pct":0,"mem":{"used_bytes":12190461952,"total_bytes":16776560640},"disk":{"read_bps":0,"write_bps":0},"net":{"rx_bps":0,"tx_bps":0}}\n\n
+[sse] event {"ts":"2025-08-11T03:05:08.101Z","cpu_pct":0,"gpu_pct":0,"mem":{"used_bytes":12190461952,"total_bytes":16776560640},"disk":{"read_bps":0,"write_bps":0},"net":{"rx_bps":0,"tx_bps":0}}
+[sse] data event: data\ndata: {"ts":"2025-08-11T03:05:09.103Z","cpu_pct":0,"gpu_pct":0,"mem":{"used_bytes":12193042432,"total_bytes":16776560640},"disk":{"read_bps":0,"write_bps":0},"net":{"rx_bps":0,"tx_bps":0}}\n\n
+[sse] event {"ts":"2025-08-11T03:05:09.103Z","cpu_pct":0,"gpu_pct":0,"mem":{"used_bytes":12193042432,"total_bytes":16776560640},"disk":{"read_bps":0,"write_bps":0},"net":{"rx_bps":0,"tx_bps":0}}
+ PASS  [metrics] stream yields  2004ms
+──────────────────────────────────────────────────────────────────────────────
+Suite: network
+──────────────────────────────────────────────────────────────────────────────
+[http] curl -sS -X POST "http://127.0.0.1:10001/network/intercept/rules" -H "content-type: application/json" -d '{"rules":[{"match":{"method":"GET","host_contains":"example.com"},"action":{"type":"block"}}]}'
+[http] status=200
+[body] {
+  "rule_set_id": "5hxuxp8ymc",
+  "applied": true
+}
+[http] curl -sS -X DELETE "http://127.0.0.1:10001/network/intercept/rules/5hxuxp8ymc" -H "content-type: application/json"
+[http] status=200
+[body] {
+  "ok": true
+}
+ PASS  [network] apply/delete intercept rules  9ms
+[http] raw curl -sS -X GET "http://127.0.0.1:10001/network/har/stream"
+ PASS  [network] HAR stream opens  1ms
+──────────────────────────────────────────────────────────────────────────────
+Suite: os
+──────────────────────────────────────────────────────────────────────────────
+[http] curl -sS -X GET "http://127.0.0.1:10001/os/locale" -H "content-type: application/json"
+[http] status=200
+[body] {
+  "locale": "en_US.UTF-8",
+  "keyboard_layout": "us",
+  "timezone": "UTC"
+}
+[http] curl -sS -X POST "http://127.0.0.1:10001/os/locale" -H "content-type: application/json" -d '{"locale":"en_US.UTF-8","timezone":"UTC","keyboard_layout":"us"}'
+[http] status=200
+[body] {
+  "updated": true,
+  "requires_restart": false
+}
+ PASS  [os] locale get/post  6ms
+──────────────────────────────────────────────────────────────────────────────
+Suite: pipe
+──────────────────────────────────────────────────────────────────────────────
+[sse] connect http://127.0.0.1:10001/pipe/recv/stream?channel=x max=1 timeout=4000
+[http] curl -sS -X POST "http://127.0.0.1:10001/pipe/send" -H "content-type: application/json" -d '{"channel":"x","object":{"n":42}}'
+[sse] data event: data\ndata: {"ts":"2025-08-11T03:05:09.125Z","object":{"n":42}}\n\n
+[sse] event {"ts":"2025-08-11T03:05:09.125Z","object":{"n":42}}
+[http] status=200
+[body] {
+  "enqueued": true
+}
+ PASS  [pipe] send/recv  4ms
+──────────────────────────────────────────────────────────────────────────────
+Suite: process
+──────────────────────────────────────────────────────────────────────────────
+[http] curl -sS -X POST "http://127.0.0.1:10001/process/exec" -H "content-type: application/json" -d '{"command":"bash","args":["-lc","printf hi"]}'
+[http] status=200
+[body] {
+  "exit_code": 0,
+  "stdout_b64": "aGk=",
+  "stderr_b64": "",
+  "duration_ms": 0
+}
+ PASS  [process] exec  20ms
+[http] curl -sS -X POST "http://127.0.0.1:10001/process/spawn" -H "content-type: application/json" -d '{"command":"bash","args":["-lc","for i in 1 2 3; do echo $i; sleep 1; done"]}'
+[http] status=200
+[body] {
+  "process_id": "3ijubiskv6",
+  "pid": 320,
+  "started_at": "2025-08-11T03:05:09.150Z"
+}
+[http] curl -sS -X GET "http://127.0.0.1:10001/process/3ijubiskv6/status" -H "content-type: application/json"
+[http] status=200
+[body] {
+  "state": "running",
+  "exit_code": null,
+  "cpu_pct": 0,
+  "mem_bytes": 0
+}
+[sse] connect http://127.0.0.1:10001/process/3ijubiskv6/stdout/stream max=2 timeout=6000
+[sse] data event: data\ndata: {"stream":"stdout","data_b64":"MQo="}\n\n
+[sse] event {"stream":"stdout","data_b64":"MQo="}
+[sse] data event: data\ndata: {"stream":"stdout","data_b64":"Mgo="}\n\n
+[sse] event {"stream":"stdout","data_b64":"Mgo="}
+[http] curl -sS -X POST "http://127.0.0.1:10001/process/3ijubiskv6/kill" -H "content-type: application/json" -d '{"signal":"TERM"}'
+[http] status=200
+[body] {
+  "ok": true
+}
+ PASS  [process] spawn/status/stream/kill  1015ms
+──────────────────────────────────────────────────────────────────────────────
+Suite: recording
+──────────────────────────────────────────────────────────────────────────────
+[http] curl -sS -X POST "http://127.0.0.1:10001/recording/start" -H "content-type: application/json" -d '{"id":"t1","maxDurationInSeconds":1}'
+[http] status=201
+[body] {
+  "ok": true,
+  "id": "t1",
+  "started_at": "2025-08-11T03:05:10.171Z"
+}
+[http] curl -sS -X GET "http://127.0.0.1:10001/recording/list" -H "content-type: application/json"
+[http] status=200
+[body] [
+  {
+    "id": "t1",
+    "isRecording": true,
+    "started_at": "2025-08-11T03:05:10.171Z",
+    "finished_at": null
+  }
+]
+[http] raw curl -sS -X GET "http://127.0.0.1:10001/recording/download?id=t1"
+[http] curl -sS -X POST "http://127.0.0.1:10001/recording/delete" -H "content-type: application/json" -d '{"id":"t1"}'
+[http] status=200
+[body] {
+  "ok": true
+}
+ PASS  [recording] start/list/stop/download/delete  1512ms
+──────────────────────────────────────────────────────────────────────────────
+Suite: screenshot
+──────────────────────────────────────────────────────────────────────────────
+[http] curl -sS -X POST "http://127.0.0.1:10001/screenshot/capture" -H "content-type: application/json" -d '{"format":"png"}'
+[http] status=200
+[body] {
+  "screenshot_id": "s6bbl8652a",
+  "content_type": "image/png",
+  "bytes_b64": "iVBORw0KGgoAAAANSUhEUgAABAAAAAMACAIAAAA12IJaAAAACXBIWXMAAAAAAAAAAQCEeRdzAAAQAElEQVR4nOzdd3QTB7vv+/x7y7nrrvOec9e+++61332S7Dc7/Y1NSyCQQBKSAIEQugOmhg4h9BIgQCBA6ITeQgtgCD30GorpvbrI3ZblIncVS74PDBnGapZk2bKt72c9K0uaGc2MRjJ5fpr2wp1kG0VRFEVRFEVRIVIvBH0NKIqiKIqiKIqqtiIAUBRFURRFUVQIFQGAoiiKoiiKokKoCAAURVEURVEUFUJFAKAoiqIoiqKoECqvAsDjDFuCwZaSY9fn27MKXJeMkgl0hicT+7cqsojMPHt+SZnVVgYEi3z95EsoX0X5QlbmT+u28iDp2WO1HCegKIqiKIqq3qogANxPtaXlum363ZW8RF7o/Uo8TLMVm4Pd9wFOisxl8uX0868rqeIJyAAURVEURVV/eQoAcXp7pvuf/D2XvFBe7s0apOTYbfZgN3qAG/LllK+oD39UFfb9TnU7uTTo/xBQFEVRFBU65TYASPvuX+uvrQozQGoOvT9qgVSfMoDvddv32EBRFEVRFOVfuQ4AD1Jtfv/277Af4IH7Y4Eepdns9P+oDWz2ShwLRFEURVEUVZPKdQDw47h/D+cDuFt2sSXYbR3gtSJzWdD/XCmKoiiKoipfLgLAw3RboLp/pWSGzkuJ03OtH9Qysfoq/oPkQCCKoiiKoqq+XASA+MxAdv9SMkPnpaQbKzj6x1ZUkH/2j4Qfh8V2apTQ6q3HEc100wYU3ThnN5WU1bYjh/Ly8v7+97+npaUFe0VQKR52Z1EURVEURdWWchEAUnICHACSc1wsOK/YfZ9lt5t1j/WLxhom9ymIPmnNNpRmZpjTEovv3zIuniTDTbH3yu... [37917 bytes total]
+ PASS  [screenshot] capture returns image bytes (best-effort)  149ms
+──────────────────────────────────────────────────────────────────────────────
+Suite: scripts
+──────────────────────────────────────────────────────────────────────────────
+[tmp] /tmp/script.sh-rg6vkgvxtx
+[http] raw curl -sS -X POST "http://127.0.0.1:10001/scripts/upload"
+[http] curl -sS -X GET "http://127.0.0.1:10001/scripts/list" -H "content-type: application/json"
+[http] status=200
+[body] {
+  "items": []
+}
+[http] curl -sS -X POST "http://127.0.0.1:10001/scripts/run" -H "content-type: application/json" -d '{"path":"/tmp/script.sh-rg6vkgvxtx"}'
+[http] status=200
+[body] {
+  "exit_code": 0,
+  "stdout_b64": "aGkK",
+  "stderr_b64": "",
+  "duration_ms": 0
+}
+[http] curl -sS -X DELETE "http://127.0.0.1:10001/scripts/delete" -H "content-type: application/json" -d '{"path":"/tmp/script.sh-rg6vkgvxtx"}'
+[http] status=200
+[body] {
+  "ok": true
+}
+ PASS  [scripts] upload/list/run/delete  13ms
+──────────────────────────────────────────────────────────────────────────────
+Suite: stream
+──────────────────────────────────────────────────────────────────────────────
+[http] curl -sS -X POST "http://127.0.0.1:10001/stream/start" -H "content-type: application/json" -d '{"rtmps_url":"rtmps://example.com/live","stream_key":"testkey","fps":1,"audio":{"capture_system":false}}'
+[http] status=200
+[body] {
+  "stream_id": "d7gzvoajxi",
+  "status": "starting",
+  "metrics_endpoint": "/stream/d7gzvoajxi/metrics/stream"
+}
+[sse] connect http://127.0.0.1:10001/stream/d7gzvoajxi/metrics/stream max=1 timeout=5000
+[sse] data event: data\ndata: {"ts":"2025-08-11T03:05:13.875Z"}\n\n
+[sse] event {"ts":"2025-08-11T03:05:13.875Z"}
+[http] curl -sS -X POST "http://127.0.0.1:10001/stream/stop" -H "content-type: application/json" -d '{"stream_id":"d7gzvoajxi"}'
+[http] status=200
+[body] {
+  "stream_id": "d7gzvoajxi",
+  "status": "stopped"
+}
+ PASS  [stream] start metrics stream then stop (best-effort)  2014ms
+──────────────────────────────────────────────────────────────────────────────
+Summary
+──────────────────────────────────────────────────────────────────────────────
+┌──────────────────┐
+│ Total: 27        │
+│ Pass:  25        │
+│ Fail:  2         │
+│ Skip:  0         │
+│ Elapsed: 38394ms │
+│ Coverage: 100%   │
+│ Reliability: 93% │
+└──────────────────┘
+──────────────────────────────────────────────────────────────────────────────
+Failures
+──────────────────────────────────────────────────────────────────────────────
+• [clipboard] stream detects change (best-effort)  30001ms  :: timeout after 30000ms
+• [fs] watch events  8ms  :: watch start failed
\ No newline at end of file
diff --git a/operator-api/tests/browser.test.js b/operator-api/tests/browser.test.js
new file mode 100644
index 00000000..fe45d75b
--- /dev/null
+++ b/operator-api/tests/browser.test.js
@@ -0,0 +1,16 @@
+import { j, readSSE } from './utils.js'
+
+describe('browser HAR sessions', () => {
+  it('start/stream/stop', async () => {
+    const start = await j('/browser/har/start', { method: 'POST', body: JSON.stringify({}) })
+    expect(start.status).toBe(200)
+    const { har_session_id } = start.body
+    // const res = await fetch(`${globalThis.__TEST_BASE_URL__}/browser/har/${har_session_id}/stream`)
+    const res = await fetch(`/browser/har/${har_session_id}/stream`)
+    expect(res.status).toBe(200)
+    const reader = res.body.getReader()
+    await reader.cancel()
+    const stop = await j('/browser/har/stop', { method: 'POST', body: JSON.stringify({ har_session_id }) })
+    expect(stop.status).toBe(200)
+  })
+})
diff --git a/operator-api/tests/browser/_pipe/_bus.test.js b/operator-api/tests/browser/_pipe/_bus.test.js
new file mode 100644
index 00000000..79b54098
--- /dev/null
+++ b/operator-api/tests/browser/_pipe/_bus.test.js
@@ -0,0 +1,30 @@
+
+import { describe, it, expect } from 'vitest'
+
+describe('Browser/Bus/Pipe basic endpoints', () => {
+it('starts browser HAR session', async () => {
+const { app } = await import('../src/app.js')
+const res = await app.request('/browser/har/start', { method: 'POST', body: JSON.stringify({}) })
+expect(res.status).toBe(200)
+const body = await res.json()
+expect(body).toHaveProperty('har\_session\_id')
+})
+
+it('publishes on bus', async () => {
+const { app } = await import('../src/app.js')
+const res = await app.request('/bus/publish', { method: 'POST', body: JSON.stringify({ channel: 'default', type: 't', payload: {} }) })
+expect(res.status).toBe(200)
+const body = await res.json()
+expect(body.delivered).toBe(true)
+})
+
+it('sends on pipe', async () => {
+const { app } = await import('../src/app.js')
+const res = await app.request('/pipe/send', { method: 'POST', body: JSON.stringify({ channel: 'default', object: { a: 1 } }) })
+expect(res.status).toBe(200)
+const body = await res.json()
+expect(body.enqueued).toBe(true)
+})
+})
+
+\================================================
\ No newline at end of file
diff --git a/operator-api/tests/bus.test.js b/operator-api/tests/bus.test.js
new file mode 100644
index 00000000..ebdf9913
--- /dev/null
+++ b/operator-api/tests/bus.test.js
@@ -0,0 +1,12 @@
+import { j, readSSE } from './utils.js'
+
+describe('bus', () => {
+  it('publish/subscribe via SSE', async () => {
+    const eventsPromise = readSSE(`/bus/subscribe?channel=testch`, { max: 1, timeoutMs: 4000 })
+    const pub = await j('/bus/publish', { method: 'POST', body: JSON.stringify({ channel: 'testch', type: 'note', payload: { msg: 'hello' } }) })
+    expect(pub.status).toBe(200)
+    const events = await eventsPromise
+    expect(events.length).toBe(1)
+    expect(events[0].payload.msg).toBe('hello')
+  })
+})
diff --git a/operator-api/tests/clipboard.test.js b/operator-api/tests/clipboard.test.js
new file mode 100644
index 00000000..ce3e9998
--- /dev/null
+++ b/operator-api/tests/clipboard.test.js
@@ -0,0 +1,51 @@
+import { j, raw } from './utils.js'
+
+describe('clipboard', () => {
+  it('GET /clipboard responds even if tooling missing', async () => {
+    const r = await j('/clipboard')
+    expect(r.status).toBe(200)
+    expect(['text', 'image']).toContain(r.body.type)
+  })
+
+  it('GET /clipboard/stream returns SSE stream and detects changes', async () => {
+    // First set a known value to the clipboard
+    const timestamp = Date.now().toString()
+    const testText = `Test clipboard content ${timestamp}`
+    
+    await j('/clipboard', {
+      method: 'POST',
+      body: JSON.stringify({ type: 'text', text: testText })
+    })
+    
+    // Connect to the stream
+    const r = await raw('/clipboard/stream')
+    expect(r.status).toBe(200)
+    expect(r.headers.get('Content-Type')).toBe('text/event-stream')
+    
+    // Read from the stream
+    const reader = r.body.getReader()
+    
+    // We should get at least one event with our test content
+    let foundTestContent = false
+    let attempts = 0
+    
+    while (!foundTestContent && attempts < 5) {
+      const { done, value } = await reader.read()
+      if (done) break
+      
+      const chunk = new TextDecoder().decode(value)
+      if (chunk.includes(timestamp)) {
+        foundTestContent = true
+      }
+      
+      attempts++;
+      // Small delay between reads
+      await new Promise(resolve => setTimeout(resolve, 200))
+    }
+    
+    // Clean up
+    reader.cancel()
+    
+    expect(foundTestContent).toBe(true)
+  })
+})
diff --git a/operator-api/tests/fs-nodelete.test.js b/operator-api/tests/fs-nodelete.test.js
new file mode 100644
index 00000000..d13a4fdc
--- /dev/null
+++ b/operator-api/tests/fs-nodelete.test.js
@@ -0,0 +1,51 @@
+import fs from 'node:fs'
+import path from 'node:path'
+import { j, raw, tmpPath } from './utils.js'
+
+describe('fs-nodelete', () => {
+  it('PUT /fs/create_directory + list + file_info', async () => {
+    const dir = tmpPath('fsdir-nodelete')
+    let r = await j('/fs/create_directory', { method: 'PUT', body: JSON.stringify({ path: dir, mode: '0755' }) })
+    expect(r.status).toBe(201)
+    r = await j(`/fs/list_files?path=${encodeURIComponent(path.dirname(dir))}`)
+    expect(r.status).toBe(200)
+    expect(Array.isArray(r.body)).toBe(true)
+    r = await j(`/fs/file_info?path=${encodeURIComponent(dir)}`)
+    expect(r.status).toBe(200)
+    expect(r.body.is_dir).toBe(true)
+    // No delete operation
+  })
+
+  it('PUT /fs/write_file + GET /fs/read_file + download + move', async () => {
+    const p = tmpPath('fsfile-nodelete.txt')
+    let r = await raw(`/fs/write_file?path=${encodeURIComponent(p)}&mode=0644`, {
+      method: 'PUT',
+      body: Buffer.from('hello world')
+    })
+    expect(r.status).toBe(201)
+
+    r = await raw(`/fs/read_file?path=${encodeURIComponent(p)}`)
+    expect(r.status).toBe(200)
+    expect(await r.text()).toBe('hello world')
+
+    r = await raw(`/fs/download?path=${encodeURIComponent(p)}`)
+    expect(r.status).toBe(200)
+
+    const p2 = tmpPath('fsfile2-nodelete.txt')
+    r = await j('/fs/move', { method: 'PUT', body: JSON.stringify({ src_path: p, dest_path: p2 }) })
+    expect(r.status).toBe(200)
+    // No delete operation
+  })
+
+  it('POST /fs/upload', async () => {
+    const p = tmpPath('upload-nodelete.bin')
+    const data = new TextEncoder().encode('payload')
+    const form = new FormData()
+    form.set('path', p)
+    form.set('file', new Blob([data]), 'file.bin')
+    const r = await raw('/fs/upload', { method: 'POST', body: form })
+    expect(r.status).toBe(200)
+    const st = fs.statSync(p)
+    expect(st.size).toBe(data.length)
+  })
+})
diff --git a/operator-api/tests/fs.test.js b/operator-api/tests/fs.test.js
new file mode 100644
index 00000000..85bde231
--- /dev/null
+++ b/operator-api/tests/fs.test.js
@@ -0,0 +1,172 @@
+import fs from 'node:fs'
+import path from 'node:path'
+import { j, raw, tmpPath } from './utils.js'
+
+describe('fs', () => {
+  it('PUT /fs/create_directory + list + file_info + delete_directory', async () => {
+    const dir = tmpPath('fsdir')
+    let r = await j('/fs/create_directory', { method: 'PUT', body: JSON.stringify({ path: dir, mode: '0755' }) })
+    expect(r.status).toBe(201)
+    r = await j(`/fs/list_files?path=${encodeURIComponent(path.dirname(dir))}`)
+    expect(r.status).toBe(200)
+    expect(Array.isArray(r.body)).toBe(true)
+    r = await j(`/fs/file_info?path=${encodeURIComponent(dir)}`)
+    expect(r.status).toBe(200)
+    expect(r.body.is_dir).toBe(true)
+    r = await j('/fs/delete_directory', { method: 'PUT', body: JSON.stringify({ path: dir }) })
+    expect(r.status).toBe(200)
+  })
+
+  it('PUT /fs/write_file + GET /fs/read_file + download + move + delete_file', async () => {
+    const p = tmpPath('fsfile.txt')
+    let r = await raw(`/fs/write_file?path=${encodeURIComponent(p)}&mode=0644`, {
+      method: 'PUT',
+      body: Buffer.from('hello world')
+    })
+    expect(r.status).toBe(201)
+
+    r = await raw(`/fs/read_file?path=${encodeURIComponent(p)}`)
+    expect(r.status).toBe(200)
+    expect(await r.text()).toBe('hello world')
+
+    r = await raw(`/fs/download?path=${encodeURIComponent(p)}`)
+    expect(r.status).toBe(200)
+
+    const p2 = tmpPath('fsfile2.txt')
+    r = await j('/fs/move', { method: 'PUT', body: JSON.stringify({ src_path: p, dest_path: p2 }) })
+    expect(r.status).toBe(200)
+
+    r = await j('/fs/delete_file', { method: 'PUT', body: JSON.stringify({ path: p2 }) })
+    expect(r.status).toBe(200)
+  })
+
+  it('POST /fs/upload', async () => {
+    const p = tmpPath('upload.bin')
+    const data = new TextEncoder().encode('payload')
+    const form = new FormData()
+    form.set('path', p)
+    form.set('file', new Blob([data]), 'file.bin')
+    const r = await raw('/fs/upload', { method: 'POST', body: form })
+    expect(r.status).toBe(200)
+    const st = fs.statSync(p)
+    expect(st.size).toBe(data.length)
+  })
+
+  it('PUT /fs/set_file_permissions', async () => {
+    const p = tmpPath('permissions.txt')
+    await raw(`/fs/write_file?path=${encodeURIComponent(p)}&mode=0644`, {
+      method: 'PUT',
+      body: Buffer.from('test content')
+    })
+    
+    const r = await j('/fs/set_file_permissions', { 
+      method: 'PUT', 
+      body: JSON.stringify({ path: p, mode: '0755' }) 
+    })
+    expect(r.status).toBe(200)
+    
+    const stats = fs.statSync(p)
+    expect((stats.mode & 0o777).toString(8)).toBe('755')
+    
+    // Clean up
+    fs.unlinkSync(p)
+  })
+
+  it('GET /fs/tail/stream', async () => {
+    const p = tmpPath('tail-test.log')
+    await raw(`/fs/write_file?path=${encodeURIComponent(p)}&mode=0644`, {
+      method: 'PUT',
+      body: Buffer.from('initial line\n')
+    })
+    
+    // Start the tail stream
+    const r = await raw(`/fs/tail/stream?path=${encodeURIComponent(p)}`)
+    expect(r.status).toBe(200)
+    expect(r.headers.get('Content-Type')).toBe('text/event-stream')
+    
+    const reader = r.body.getReader()
+    
+    // Append to the file
+    const testLine = `new line ${Date.now()}\n`
+    fs.appendFileSync(p, testLine)
+    
+    // Read from the stream
+    let foundNewLine = false
+    let attempts = 0
+    
+    while (!foundNewLine && attempts < 5) {
+      const { done, value } = await reader.read()
+      if (done) break
+      
+      const chunk = new TextDecoder().decode(value)
+      if (chunk.includes(testLine.trim())) {
+        foundNewLine = true
+      }
+      
+      attempts++;
+      await new Promise(resolve => setTimeout(resolve, 200))
+    }
+    
+    // Clean up
+    reader.cancel()
+    fs.unlinkSync(p)
+    
+    expect(foundNewLine).toBe(true)
+  })
+
+  it('GET /fs/watch and /fs/watch/{watch_id}/events', async () => {
+    const dir = tmpPath('watch-dir')
+    fs.mkdirSync(dir, { recursive: true })
+    
+    // Start watching the directory
+    let r = await j('/fs/watch', { 
+      method: 'POST', 
+      body: JSON.stringify({ path: dir, recursive: true }) 
+    })
+    expect(r.status).toBe(200)
+    expect(r.body).toHaveProperty('watch_id')
+    
+    const watchId = r.body.watch_id
+    
+    // Connect to the events stream
+    const eventsStream = await raw(`/fs/watch/${watchId}/events`)
+    expect(eventsStream.status).toBe(200)
+    expect(eventsStream.headers.get('Content-Type')).toBe('text/event-stream')
+    
+    const reader = eventsStream.body.getReader()
+    
+    // Create a file in the watched directory
+    const testFile = path.join(dir, `test-${Date.now()}.txt`)
+    fs.writeFileSync(testFile, 'test content')
+    
+    // Check if we receive the event
+    let foundEvent = false
+    let attempts = 0
+    
+    while (!foundEvent && attempts < 5) {
+      const { done, value } = await reader.read()
+      if (done) break
+      
+      const chunk = new TextDecoder().decode(value)
+      if (chunk.includes(path.basename(testFile))) {
+        foundEvent = true
+      }
+      
+      attempts++;
+      await new Promise(resolve => setTimeout(resolve, 200))
+    }
+    
+    // Clean up
+    reader.cancel()
+    
+    // Stop watching
+    r = await j(`/fs/watch/${watchId}`, { method: 'DELETE' })
+    expect(r.status).toBe(200)
+    
+    // Clean up files
+    fs.unlinkSync(testFile)
+    fs.rmdirSync(dir)
+    
+    expect(foundEvent).toBe(true)
+  })
+})
diff --git a/operator-api/tests/globalSetup.mjs b/operator-api/tests/globalSetup.mjs
new file mode 100644
index 00000000..d3173bfd
--- /dev/null
+++ b/operator-api/tests/globalSetup.mjs
@@ -0,0 +1,45 @@
+import { spawn } from 'node:child_process'
+import { setTimeout as delay } from 'node:timers/promises'
+import { request } from 'undici'
+
+const TEST_PORT = Number(process.env.PORT || 10001)
+const BASE_URL = `http://127.0.0.1:${TEST_PORT}`
+
+let child
+
+async function waitForHealth(timeoutMs = 20000) {
+  const start = Date.now()
+  while (Date.now() - start < timeoutMs) {
+    try {
+      const { statusCode } = await request(`${BASE_URL}/health`, { method: 'GET' })
+      if (statusCode === 200) return
+    } catch {}
+    await delay(300)
+  }
+  throw new Error('Server did not become healthy')
+}
+
+export default async function() {
+  child = spawn(process.execPath, ['index.js'], {
+    env: { ...process.env, PORT: String(TEST_PORT) },
+    stdio: ['ignore', 'pipe', 'pipe']
+  })
+
+  // optional log piping to help flakiness diagnosis
+  child.stdout.on('data', () => {})
+  child.stderr.on('data', () => {})
+
+  await waitForHealth()
+
+  // expose to tests
+  globalThis.__TEST_BASE_URL__ = BASE_URL
+
+  return async () => {
+    if (child && !child.killed) {
+      child.kill('SIGINT')
+      // best-effort shutdown
+      await delay(500)
+      if (!child.killed) child.kill('SIGKILL')
+    }
+  }
+}
diff --git a/operator-api/tests/health.test.js b/operator-api/tests/health.test.js
new file mode 100644
index 00000000..5bcfbd1d
--- /dev/null
+++ b/operator-api/tests/health.test.js
@@ -0,0 +1,10 @@
+import { j } from './utils.js'
+
+describe('health', () => {
+  it('GET /health returns ok', async () => {
+    const { status, body } = await j('/health')
+    expect(status).toBe(200)
+    expect(body.status).toBe('ok')
+    expect(typeof body.uptime_sec).toBe('number')
+  })
+})
diff --git a/operator-api/tests/input.test.js b/operator-api/tests/input.test.js
new file mode 100644
index 00000000..48e4aede
--- /dev/null
+++ b/operator-api/tests/input.test.js
@@ -0,0 +1,246 @@
+import { j } from './utils.js'
+
+describe('input', () => {
+  // Mouse endpoints
+  describe('mouse', () => {
+    it('input/mouse/move', async () => {
+      const r = await j('/input/mouse/move', { method: 'POST', body: JSON.stringify({ x: 100, y: 100 }) })
+      expect(r.status).toBe(200)
+      expect(r.body.ok).toBe(true)
+    })
+
+    it('input/mouse/move_relative', async () => {
+      const r = await j('/input/mouse/move_relative', { method: 'POST', body: JSON.stringify({ dx: 10, dy: 10 }) })
+      expect(r.status).toBe(200)
+      expect(r.body.ok).toBe(true)
+    })
+
+    it('input/mouse/click', async () => {
+      const r = await j('/input/mouse/click', { method: 'POST', body: JSON.stringify({ button: 'left', count: 1 }) })
+      expect(r.status).toBe(200)
+      expect(r.body.ok).toBe(true)
+    })
+
+    it('input/mouse/down', async () => {
+      const r = await j('/input/mouse/down', { method: 'POST', body: JSON.stringify({ button: 'left' }) })
+      expect(r.status).toBe(200)
+      expect(r.body.ok).toBe(true)
+    })
+
+    it('input/mouse/up', async () => {
+      const r = await j('/input/mouse/up', { method: 'POST', body: JSON.stringify({ button: 'left' }) })
+      expect(r.status).toBe(200)
+      expect(r.body.ok).toBe(true)
+    })
+
+    it('input/mouse/scroll', async () => {
+      const r = await j('/input/mouse/scroll', { method: 'POST', body: JSON.stringify({ dx: 0, dy: -120 }) })
+      expect(r.status).toBe(200)
+      expect(r.body.ok).toBe(true)
+    })
+
+    it('input/mouse/location', async () => {
+      const r = await j('/input/mouse/location', { method: 'GET' })
+      expect(r.status).toBe(200)
+      expect(r.body.x).toBeDefined()
+      expect(r.body.y).toBeDefined()
+    })
+  })
+
+  // Keyboard endpoints
+  describe('keyboard', () => {
+    it('input/keyboard/type', async () => {
+      const r = await j('/input/keyboard/type', { method: 'POST', body: JSON.stringify({ text: 'test', wpm: 300 }) })
+      expect(r.status).toBe(200)
+      expect(r.body.ok).toBe(true)
+    })
+
+    it('input/keyboard/key', async () => {
+      const r = await j('/input/keyboard/key', { method: 'POST', body: JSON.stringify({ keys: ['Return'] }) })
+      expect(r.status).toBe(200)
+      expect(r.body.ok).toBe(true)
+    })
+
+    it('input/keyboard/key_down', async () => {
+      const r = await j('/input/keyboard/key_down', { method: 'POST', body: JSON.stringify({ key: 'ctrl' }) })
+      expect(r.status).toBe(200)
+      expect(r.body.ok).toBe(true)
+    })
+
+    it('input/keyboard/key_up', async () => {
+      const r = await j('/input/keyboard/key_up', { method: 'POST', body: JSON.stringify({ key: 'ctrl' }) })
+      expect(r.status).toBe(200)
+      expect(r.body.ok).toBe(true)
+    })
+  })
+
+  // Window endpoints
+  describe('window', () => {
+    it('input/window/activate', async () => {
+      const r = await j('/input/window/activate', { method: 'POST', body: JSON.stringify({ match: { name: "chromium" } }) })
+      expect(r.status).toBe(200)
+    })
+
+    it('input/window/focus', async () => {
+      const r = await j('/input/window/focus', { method: 'POST', body: JSON.stringify({ match: { name: "chromium" } }) })
+      expect(r.status).toBe(200)
+    })
+
+    it('input/window/move_resize', async () => {
+      const r = await j('/input/window/move_resize', { 
+        method: 'POST', 
+        body: JSON.stringify({ match: { name: "chromium" }, x: 0, y: 0, width: 800, height: 600 }) 
+      })
+      expect(r.status).toBe(200)
+    })
+
+    it('input/window/raise', async () => {
+      const r = await j('/input/window/raise', { method: 'POST', body: JSON.stringify({ match: { name: "chromium" } }) })
+      expect(r.status).toBe(200)
+    })
+
+    it('input/window/minimize', async () => {
+      const r = await j('/input/window/minimize', { method: 'POST', body: JSON.stringify({ match: { name: "chromium" } }) })
+      expect(r.status).toBe(200)
+    })
+
+    it('input/window/map', async () => {
+      const r = await j('/input/window/map', { method: 'POST', body: JSON.stringify({ match: { name: "chromium" } }) })
+      expect(r.status).toBe(200)
+    })
+
+    it('input/window/unmap', async () => {
+      const r = await j('/input/window/unmap', { method: 'POST', body: JSON.stringify({ match: { name: "chromium" } }) })
+      expect(r.status).toBe(200)
+    })
+
+    it('input/window/close', async () => {
+      // rather not close chromium - tested and works when firefox open
+      const r = await j('/input/window/close', { method: 'POST', body: JSON.stringify({ match: { name: "firefox" } }) })
+      expect(r.status).toBe(200)
+    })
+
+    it('input/window/active', async () => {
+      const r = await j('/input/window/active', { method: 'GET' })
+      expect(r.status).toBe(200)
+      expect(r.body.wid).toBeDefined()
+    })
+
+    it('input/window/focused', async () => {
+      const r = await j('/input/window/focused', { method: 'GET' })
+      expect(r.status).toBe(200)
+      expect(r.body.wid).toBeDefined()
+    })
+
+    it('input/window/name', async () => {
+      // First get active window
+      const active = await j('/input/window/active', { method: 'GET' })
+      const r = await j('/input/window/name', { 
+        method: 'POST', 
+        body: JSON.stringify({ wid: active.body.wid }) 
+      })
+      expect(r.status).toBe(200)
+      expect(r.body.name).toBeDefined()
+    })
+
+    it('input/window/geometry', async () => {
+      // First get active window
+      const active = await j('/input/window/active', { method: 'GET' })
+      const r = await j('/input/window/geometry', { 
+        method: 'POST', 
+        body: JSON.stringify({ wid: active.body.wid }) 
+      })
+      expect(r.status).toBe(200)
+      expect(r.body.width).toBeDefined()
+      expect(r.body.height).toBeDefined()
+    })
+  })
+
+  // Desktop endpoints
+  describe('desktop', () => {
+    it('input/desktop/count', async () => {
+      const r = await j('/input/desktop/count', { method: 'GET' })
+      expect(r.status).toBe(200)
+      expect(r.body.count).toBeDefined()
+    })
+
+    it('input/desktop/current', async () => {
+      const r = await j('/input/desktop/current', { method: 'GET' })
+      expect(r.status).toBe(200)
+      expect(r.body.index).toBeDefined()
+    })
+
+    it('input/desktop/viewport', async () => {
+      const r = await j('/input/desktop/viewport', { method: 'GET' })
+      expect(r.status).toBe(200)
+      expect(r.body.x).toBeDefined()
+      expect(r.body.y).toBeDefined()
+    })
+  })
+
+  // Display endpoints
+  describe('display', () => {
+    it('input/display/geometry', async () => {
+      const r = await j('/input/display/geometry', { method: 'GET' })
+      expect(r.status).toBe(200)
+      expect(r.body.width).toBeDefined()
+      expect(r.body.height).toBeDefined()
+    })
+  })
+
+  // Combo endpoints
+  describe('combo', () => {
+    it('input/combo/activate_and_type', async () => {
+      const r = await j('/input/combo/activate_and_type', { 
+        method: 'POST', 
+        body: JSON.stringify({ match: { name: "chromium" }, text: 'test' }) 
+      })
+      expect(r.status).toBe(200)
+    })
+
+    it('input/combo/activate_and_keys', async () => {
+      const r = await j('/input/combo/activate_and_keys', { 
+        method: 'POST', 
+        body: JSON.stringify({ match: { name: "chromium" }, keys: ['Return'] }) 
+      })
+      expect(r.status).toBe(200)
+    })
+
+    it('input/combo/window/center', async () => {
+      const r = await j('/input/combo/window/center', { 
+        method: 'POST', 
+        body: JSON.stringify({ match: { name: "chromium" }, width: 800, height: 600 }) 
+      })
+      expect(r.status).toBe(200)
+    })
+
+    it('input/combo/window/snap', async () => {
+      const r = await j('/input/combo/window/snap', { 
+        method: 'POST', 
+        body: JSON.stringify({ match: { name: "chromium" }, position: 'left' }) 
+      })
+      expect(r.status).toBe(200)
+    })
+  })
+
+  // System endpoints
+  describe('system', () => {
+    it('input/system/exec', async () => {
+      const r = await j('/input/system/exec', { 
+        method: 'POST', 
+        body: JSON.stringify({ command: 'echo', args: ['hello'] }) 
+      })
+      expect(r.status).toBe(200)
+      expect(r.body.stdout).toBe('hello\n')
+    })
+
+    it('input/system/sleep', async () => {
+      const r = await j('/input/system/sleep', { 
+        method: 'POST', 
+        body: JSON.stringify({ seconds: 0.1 }) 
+      })
+      expect(r.status).toBe(200)
+      expect(r.body.ok).toBe(true)
+    })
+  })
+})
diff --git a/operator-api/tests/logs.test.js b/operator-api/tests/logs.test.js
new file mode 100644
index 00000000..5c9aed97
--- /dev/null
+++ b/operator-api/tests/logs.test.js
@@ -0,0 +1,8 @@
+import { raw } from './utils.js'
+
+describe('logs', () => {
+  it('rejects bad request', async () => {
+    const res = await raw('/logs/stream')
+    expect(res.status).toBe(400)
+  })
+})
diff --git a/operator-api/tests/macros.test.js b/operator-api/tests/macros.test.js
new file mode 100644
index 00000000..2fb5e1d4
--- /dev/null
+++ b/operator-api/tests/macros.test.js
@@ -0,0 +1,57 @@
+import { j, raw } from './utils.js'
+
+describe('macros', () => {
+  it('create/list/delete macro', async () => {
+    const create = await j('/macros/create', {
+      method: 'POST',
+      body: JSON.stringify({
+        name: 'type-hello',
+        steps: [{ action: 'sleep', ms: 10 }, { action: 'keyboard.type', text: 'hello' }]
+      })
+    })
+    expect(create.status).toBe(200)
+    const macro_id = create.body.macro_id
+
+    const list = await j('/macros/list')
+    expect(list.status).toBe(200)
+    expect(list.body.items.find(i => i.macro_id === macro_id)).toBeTruthy()
+
+    const del = await j(`/macros/${macro_id}`, { method: 'DELETE' })
+    expect(del.status).toBe(200)
+  })
+
+  it('handles macro run requests', async () => {
+    // Create a test macro first
+    const create = await j('/macros/create', {
+      method: 'POST',
+      body: JSON.stringify({
+        name: 'test-run-macro',
+        steps: [{ action: 'sleep', ms: 5 }]
+      })
+    })
+    expect(create.status).toBe(200)
+    const macro_id = create.body.macro_id
+
+    // Test run endpoint
+    const run = await j('/macros/run', {
+      method: 'POST',
+      body: JSON.stringify({
+        macro_id
+      })
+    })
+    expect(run.status).toBe(200)
+
+    // Test invalid run request
+    const invalidRun = await j('/macros/run', {
+      method: 'POST',
+      body: JSON.stringify({
+        macro_id: 'non-existent-id'
+      })
+    })
+    expect(invalidRun.status).toBe(404)
+
+    // Clean up
+    await j(`/macros/${macro_id}`, { method: 'DELETE' })
+  })
+
+})
diff --git a/operator-api/tests/metrics.test.js b/operator-api/tests/metrics.test.js
new file mode 100644
index 00000000..37125792
--- /dev/null
+++ b/operator-api/tests/metrics.test.js
@@ -0,0 +1,15 @@
+import { j, readSSE } from './utils.js'
+
+describe('metrics', () => {
+  it('snapshot returns numbers', async () => {
+    const { status, body } = await j('/metrics/snapshot')
+    expect(status).toBe(200)
+    expect(body).toHaveProperty('cpu_pct')
+    expect(body).toHaveProperty('mem')
+  })
+
+  it('stream yields events', async () => {
+    const events = await readSSE('/metrics/stream', { max: 2, timeoutMs: 4000 })
+    expect(events.length).toBeGreaterThanOrEqual(1)
+  })
+})
diff --git a/operator-api/tests/network.test.js b/operator-api/tests/network.test.js
new file mode 100644
index 00000000..d56ded4a
--- /dev/null
+++ b/operator-api/tests/network.test.js
@@ -0,0 +1,32 @@
+import { j } from './utils.js'
+
+describe('network', () => {
+  it('start/stop socks5 proxy', async () => {
+    const start = await j('/network/proxy/socks5/start', { method: 'POST', body: JSON.stringify({ bind_host: '127.0.0.1', bind_port: 0 }) })
+    expect(start.status).toBe(200)
+    expect(start.body).toHaveProperty('proxy_id')
+    const stop = await j('/network/proxy/socks5/stop', { method: 'POST', body: JSON.stringify({ proxy_id: start.body.proxy_id }) })
+    expect(stop.status).toBe(200)
+  })
+
+  it('apply/delete intercept rules', async () => {
+    const rules = {
+      rules: [
+        { match: { method: 'GET', host_contains: 'example.com' }, action: { type: 'block' } }
+      ]
+    }
+    const apply = await j('/network/intercept/rules', { method: 'POST', body: JSON.stringify(rules) })
+    expect(apply.status).toBe(200)
+    const del = await j(`/network/intercept/rules/${apply.body.rule_set_id}`, { method: 'DELETE' })
+    expect(del.status).toBe(200)
+  })
+
+  it('HAR stream opens', async () => {
+    // const res = await fetch(`${globalThis.__TEST_BASE_URL__}/network/har/stream`)
+    const res = await fetch(`/network/har/stream`)
+    expect(res.status).toBe(200)
+    // close immediately
+    const reader = res.body.getReader()
+    await reader.cancel()
+  })
+})
diff --git a/operator-api/tests/os.test.js b/operator-api/tests/os.test.js
new file mode 100644
index 00000000..db98a000
--- /dev/null
+++ b/operator-api/tests/os.test.js
@@ -0,0 +1,20 @@
+import { j } from './utils.js'
+
+describe('os', () => {
+  it('GET /os/locale returns locale info', async () => {
+    const { status, body } = await j('/os/locale')
+    expect(status).toBe(200)
+    expect(body).toHaveProperty('locale')
+    expect(body).toHaveProperty('keyboard_layout')
+    expect(body).toHaveProperty('timezone')
+  })
+
+  it('POST /os/locale updates env', async () => {
+    const { status, body } = await j('/os/locale', {
+      method: 'POST',
+      body: JSON.stringify({ locale: 'en_US.UTF-8', timezone: 'UTC', keyboard_layout: 'us' })
+    })
+    expect(status).toBe(200)
+    expect(body.updated).toBe(true)
+  })
+})
diff --git a/operator-api/tests/pipe.test.js b/operator-api/tests/pipe.test.js
new file mode 100644
index 00000000..9919e794
--- /dev/null
+++ b/operator-api/tests/pipe.test.js
@@ -0,0 +1,11 @@
+import { j, readSSE } from './utils.js'
+
+describe('pipe', () => {
+  it('send/recv over channel', async () => {
+    const recv = readSSE('/pipe/recv/stream?channel=x', { max: 1, timeoutMs: 4000 })
+    const send = await j('/pipe/send', { method: 'POST', body: JSON.stringify({ channel: 'x', object: { n: 42 } }) })
+    expect(send.status).toBe(200)
+    const events = await recv
+    expect(events[0].object.n).toBe(42)
+  })
+})
diff --git a/operator-api/tests/process.test.js b/operator-api/tests/process.test.js
new file mode 100644
index 00000000..886e469b
--- /dev/null
+++ b/operator-api/tests/process.test.js
@@ -0,0 +1,32 @@
+import { j, readSSE } from './utils.js'
+
+describe('process', () => {
+  it('POST /process/exec executes command', async () => {
+    const { status, body } = await j('/process/exec', {
+      method: 'POST',
+      body: JSON.stringify({ command: 'bash', args: ['-lc', 'printf hi'] })
+    })
+    expect(status).toBe(200)
+    const out = Buffer.from(body.stdout_b64, 'base64').toString('utf8')
+    expect(out).toBe('hi')
+  })
+
+  it('spawn -> status -> stream -> kill', async () => {
+    const start = await j('/process/spawn', {
+      method: 'POST',
+      body: JSON.stringify({ command: 'bash', args: ['-lc', 'for i in 1 2 3; do echo $i; sleep 1; done'] })
+    })
+    expect(start.status).toBe(200)
+    const { process_id } = start.body
+
+    const status1 = await j(`/process/${process_id}/status`)
+    expect(status1.status).toBe(200)
+    expect(['running', 'exited']).toContain(status1.body.state)
+
+    const events = await readSSE(`/process/${process_id}/stdout/stream`, { max: 2, timeoutMs: 6000 })
+    expect(events.length).toBeGreaterThanOrEqual(1)
+
+    const kill = await j(`/process/${process_id}/kill`, { method: 'POST', body: JSON.stringify({ signal: 'TERM' }) })
+    expect(kill.status).toBe(200)
+  })
+})
diff --git a/operator-api/tests/recording-nodelete.test.js b/operator-api/tests/recording-nodelete.test.js
new file mode 100644
index 00000000..40c25ecb
--- /dev/null
+++ b/operator-api/tests/recording-nodelete.test.js
@@ -0,0 +1,23 @@
+import { j, readSSE, hasCmd, raw } from './utils.js'
+
+const ffmpegPresent = hasCmd('ffmpeg')
+
+describe('recording-nodelete', () => {
+  it.skipIf?.(!ffmpegPresent)('start/list/stop/download', async () => {
+    let r = await j('/recording/start', { method: 'POST', body: JSON.stringify({ id: 't1', maxDurationInSeconds: 1 }) })
+    expect(r.status).toBe(201)
+
+    r = await j('/recording/list')
+    expect(r.status).toBe(200)
+    const item = r.body.find(i => i.id === 't1')
+    expect(item).toBeTruthy()
+    expect(item.isRecording).toBe(true)
+
+    await new Promise(res => setTimeout(res, 1_500))
+    // Try download after it should have stopped
+    const d = await raw('/recording/download?id=t1')
+    expect([200, 404]).toContain(d.status)
+    
+    // No delete operation
+  })
+})
diff --git a/operator-api/tests/recording.test.js b/operator-api/tests/recording.test.js
new file mode 100644
index 00000000..4bba71ba
--- /dev/null
+++ b/operator-api/tests/recording.test.js
@@ -0,0 +1,24 @@
+import { j, readSSE, hasCmd, raw } from './utils.js'
+
+const ffmpegPresent = hasCmd('ffmpeg')
+
+describe('recording', () => {
+  it.skipIf?.(!ffmpegPresent)('start/list/stop/download/delete', async () => {
+    let r = await j('/recording/start', { method: 'POST', body: JSON.stringify({ id: 't1', maxDurationInSeconds: 1 }) })
+    expect(r.status).toBe(201)
+
+    r = await j('/recording/list')
+    expect(r.status).toBe(200)
+    const item = r.body.find(i => i.id === 't1')
+    expect(item).toBeTruthy()
+    expect(item.isRecording).toBe(true)
+
+    await new Promise(res => setTimeout(res, 1_500))
+    // Try download after it should have stopped
+    const d = await raw('/recording/download?id=t1')
+    expect([200, 404]).toContain(d.status)
+    
+    const del = await j('/recording/delete', { method: 'POST', body: JSON.stringify({ id: 't1' }) })
+    expect([200, 404]).toContain(del.status)
+  })
+})
diff --git a/operator-api/tests/screenshot.test.js b/operator-api/tests/screenshot.test.js
new file mode 100644
index 00000000..a88255ac
--- /dev/null
+++ b/operator-api/tests/screenshot.test.js
@@ -0,0 +1,14 @@
+import { j, hasCmd } from './utils.js'
+
+const ffmpegPresent = hasCmd('ffmpeg') || hasCmd('grim')
+
+describe('screenshot', () => {
+  it.skipIf?.(!ffmpegPresent)('capture returns image bytes', async () => {
+    const r = await j('/screenshot/capture', { method: 'POST', body: JSON.stringify({ format: 'png' }) })
+    expect([200, 500]).toContain(r.status)
+    if (r.status === 200) {
+      expect(r.body).toHaveProperty('bytes_b64')
+      expect(r.body).toHaveProperty('content_type')
+    }
+  })
+})
diff --git a/operator-api/tests/scripts-nodelete.test.js b/operator-api/tests/scripts-nodelete.test.js
new file mode 100644
index 00000000..d48c4edc
--- /dev/null
+++ b/operator-api/tests/scripts-nodelete.test.js
@@ -0,0 +1,27 @@
+import fs from 'node:fs'
+import { j, tmpPath } from './utils.js'
+
+const shebang = '#!/usr/bin/env bash\n'
+
+describe('scripts-nodelete', () => {
+  it('upload + list + run sync', async () => {
+    const scriptPath = tmpPath('script-nodelete.sh')
+    const form = new FormData()
+    form.set('path', scriptPath)
+    form.set('file', new Blob([shebang + 'echo hi']), 'script-nodelete.sh')
+    form.set('executable', 'true')
+    const up = await j(`/scripts/upload`, { method: 'POST', body: form })
+    expect(up.status).toBe(200)
+
+    const list = await j('/scripts/list')
+    expect(list.status).toBe(200)
+    expect(Array.isArray(list.body.items)).toBe(true)
+
+    const run = await j('/scripts/run', { method: 'POST', body: JSON.stringify({ path: scriptPath }) })
+    expect(run.status).toBe(200)
+    const out = Buffer.from(run.body.stdout_b64, 'base64').toString('utf8').trim()
+    expect(out).toBe('hi')
+
+    // No delete operation
+  })
+})
diff --git a/operator-api/tests/scripts.test.js b/operator-api/tests/scripts.test.js
new file mode 100644
index 00000000..ec0a23b9
--- /dev/null
+++ b/operator-api/tests/scripts.test.js
@@ -0,0 +1,29 @@
+import fs from 'node:fs'
+import { j, tmpPath } from './utils.js'
+
+const shebang = '#!/usr/bin/env bash\n'
+
+describe('scripts', () => {
+  it('upload + list + run sync + delete', async () => {
+    const scriptPath = tmpPath('script.sh')
+    const form = new FormData()
+    form.set('path', scriptPath)
+    form.set('file', new Blob([shebang + 'echo hi']), 'script.sh')
+    form.set('executable', 'true')
+    // const up = await fetch(`${globalThis.__TEST_BASE_URL__}/scripts/upload`, { method: 'POST', body: form })
+    const up = await j(`/scripts/upload`, { method: 'POST', body: form })
+    expect(up.status).toBe(200)
+
+    const list = await j('/scripts/list')
+    expect(list.status).toBe(200)
+    expect(Array.isArray(list.body.items)).toBe(true)
+
+    const run = await j('/scripts/run', { method: 'POST', body: JSON.stringify({ path: scriptPath }) })
+    expect(run.status).toBe(200)
+    const out = Buffer.from(run.body.stdout_b64, 'base64').toString('utf8').trim()
+    expect(out).toBe('hi')
+
+    const del = await j('/scripts/delete', { method: 'DELETE', body: JSON.stringify({ path: scriptPath }) })
+    expect(del.status).toBe(200)
+  })
+})
diff --git a/operator-api/tests/stream.test.js b/operator-api/tests/stream.test.js
new file mode 100644
index 00000000..48021a97
--- /dev/null
+++ b/operator-api/tests/stream.test.js
@@ -0,0 +1,17 @@
+import { j, hasCmd, readSSE } from './utils.js'
+
+const ffmpegPresent = hasCmd('ffmpeg')
+
+describe('stream', () => {
+  it.skipIf?.(!ffmpegPresent)('start metrics stream then stop', async () => {
+    const start = await j('/stream/start', { method: 'POST', body: JSON.stringify({ rtmps_url: 'rtmps://example.com/live', stream_key: 'testkey', fps: 1, audio: { capture_system: false } }) })
+    expect([200, 400]).toContain(start.status)
+    if (start.status === 200) {
+      const { stream_id } = start.body
+      const ev = await readSSE(`/stream/${stream_id}/metrics/stream`, { max: 1, timeoutMs: 5000 })
+      expect(Array.isArray(ev)).toBe(true)
+      const stop = await j('/stream/stop', { method: 'POST', body: JSON.stringify({ stream_id }) })
+      expect(stop.status).toBe(200)
+    }
+  })
+})
diff --git a/operator-api/tests/utils.js b/operator-api/tests/utils.js
new file mode 100644
index 00000000..13f714d5
--- /dev/null
+++ b/operator-api/tests/utils.js
@@ -0,0 +1,225 @@
+import { execSync } from 'node:child_process'
+import { request, fetch } from 'undici'
+import { Readable } from 'node:stream'
+import 'dotenv/config'
+import chalk from 'chalk'
+
+// Hardcoded BASE URL using PORT from environment
+export const BASE = () => `http://localhost:${process.env.PORT || '10001'}`
+
+// Debug mode constant
+const DEBUG_MODE = process.env.DEBUG_LOGS === 'true' || process.env.DEBUG_LOGS === true
+
+export function hasCmd(cmd) {
+  try {
+    execSync(`bash -lc "command -v ${cmd} >/dev/null 2>&1"`, { stdio: 'ignore' })
+    return true
+  } catch {
+    return false
+  }
+}
+export async function j(url, init = {}) {
+  const fullUrl = `${BASE()}${url}`
+  
+  if (DEBUG_MODE) {
+    // Generate curl equivalent
+    let curlCmd = `curl -X ${init.method || 'GET'} "${fullUrl}"`
+    
+    // Add headers
+    const headers = { 'content-type': 'application/json', ...(init.headers || {}) }
+    Object.entries(headers).forEach(([key, value]) => {
+      curlCmd += ` -H "${key}: ${value}"`
+    })
+    
+    // Add body if present
+    if (init.body) {
+      curlCmd += ` -d '${init.body}'`
+    }
+    
+    console.log(chalk.cyan('🔍 Request:'), chalk.yellow(curlCmd))
+  }
+  
+  const r = await fetch(fullUrl, {
+    ...init,
+    headers: { 'content-type': 'application/json', ...(init.headers || {}) }
+  })
+  
+  const txt = await r.text()
+  let result
+  
+  try {
+    result = { status: r.status, body: JSON.parse(txt) }
+  } catch {
+    // If it's binary or very large, trim the output
+    const isBinary = /[\x00-\x08\x0E-\x1F]/.test(txt)
+    const isLarge = txt.length > 1000
+    
+    if (isBinary || isLarge) {
+      result = { 
+        status: r.status, 
+        body: `${txt.substring(0, 500)}... [${txt.length} bytes${isBinary ? ', binary content' : ''}]` 
+      }
+    } else {
+      result = { status: r.status, body: txt }
+    }
+  }
+  
+  if (DEBUG_MODE) {
+    console.log(chalk.cyan('📡 Response:'), 
+      chalk.green(`Status: ${r.status}`), 
+      chalk.magenta('\nBody:'), 
+      typeof result.body === 'object' ? 
+        chalk.yellow(JSON.stringify(result.body, null, 2)) : 
+        chalk.yellow(result.body)
+    )
+  }
+  
+  return result
+}
+
+export async function raw(url, init = {}) {
+  const fullUrl = `${BASE()}${url}`
+  
+  if (DEBUG_MODE) {
+    // Generate curl equivalent
+    let curlCmd = `curl -X ${init.method || 'GET'} "${fullUrl}"`
+    
+    // Add headers
+    if (init.headers) {
+      Object.entries(init.headers).forEach(([key, value]) => {
+        curlCmd += ` -H "${key}: ${value}"`
+      })
+    }
+    
+    // Add body if present
+    if (init.body) {
+      curlCmd += ` -d '${init.body}'`
+    }
+    
+    console.log(chalk.cyan('🔍 Raw Request:'), chalk.yellow(curlCmd))
+  }
+  
+  const response = await fetch(fullUrl, init)
+  
+  if (DEBUG_MODE) {
+    console.log(chalk.cyan('📡 Raw Response:'), chalk.green(`Status: ${response.status}`))
+  }
+  
+  return response
+}
+
+// Minimal SSE reader: returns first N events parsed as JSON
+export async function readSSE(path, { max = 1, timeoutMs = 5000, debug = DEBUG_MODE } = {}) {
+  const fullUrl = `${BASE()}${path}`
+  
+  if (debug) {
+    console.log(
+      chalk.cyan('🔌 SSE Connection:'),
+      chalk.yellow(fullUrl),
+      chalk.magenta(`(max: ${max}, timeout: ${timeoutMs}ms)`)
+    )
+  }
+  
+  const res = await fetch(fullUrl)
+  
+  if (!res.ok) {
+    if (debug) {
+      console.error(
+        chalk.red('❌ SSE Connection Failed:'),
+        chalk.yellow(`Status: ${res.status}`)
+      )
+    }
+    throw new Error(`bad status ${res.status}`)
+  }
+  
+  if (debug) {
+    console.log(
+      chalk.green('✅ SSE Connected:'),
+      chalk.yellow(`Status: ${res.status}`),
+      chalk.cyan('Waiting for events...')
+    )
+  }
+  
+  const reader = res.body.getReader()
+  const decoder = new TextDecoder('utf-8')
+  const events = []
+  let buf = ''
+  const start = Date.now()
+
+  while (events.length < max && Date.now() - start < timeoutMs) {
+    const { value, done } = await reader.read()
+    if (done) break
+    
+    const newData = decoder.decode(value, { stream: true })
+    buf += newData
+    
+    if (debug && newData.trim()) {
+      console.log(
+        chalk.blue('📥 SSE Raw Data:'),
+        chalk.gray(newData.replace(/\n/g, '\\n'))
+      )
+    }
+    
+    let idx
+    while ((idx = buf.indexOf('\n\n')) !== -1) {
+      const chunk = buf.slice(0, idx)
+      buf = buf.slice(idx + 2)
+      const dataLine = chunk.split('\n').find(l => l.startsWith('data: '))
+      
+      if (dataLine) {
+        const json = dataLine.slice(6)
+        try { 
+          const parsedEvent = JSON.parse(json)
+          events.push(parsedEvent)
+          
+          if (debug) {
+            console.log(
+              chalk.green('🎯 SSE Event Received:'),
+              chalk.yellow(`[${events.length}/${max}]`),
+              chalk.magenta('\nPayload:'),
+              chalk.cyan(JSON.stringify(parsedEvent, null, 2))
+            )
+          }
+        } catch (err) {
+          if (debug) {
+            console.error(
+              chalk.red('⚠️ SSE Parse Error:'),
+              chalk.yellow(json),
+              chalk.red(err.message)
+            )
+          }
+        }
+      }
+      
+      if (events.length >= max) break
+    }
+  }
+  
+  if (debug) {
+    const duration = Date.now() - start
+    console.log(
+      chalk.cyan('🏁 SSE Complete:'),
+      chalk.yellow(`${events.length} events`),
+      chalk.green(`(${duration}ms)`),
+      events.length < max ? chalk.red('(timed out)') : ''
+    )
+  }
+  
+  try { reader.cancel() } catch {}
+  return events
+}
+
+// helper to create random path under /tmp
+export function tmpPath(name = 'kco') {
+  const id = Math.random().toString(36).slice(2)
+  const path = `/tmp/${name}-${id}`
+  
+  if (DEBUG_MODE) {
+    console.log(
+      chalk.cyan('📁 Temp Path:'),
+      chalk.yellow(path)
+    )
+  }
+  
+  return path
+}
diff --git a/operator-api/vitest.config.mjs b/operator-api/vitest.config.mjs
new file mode 100644
index 00000000..44f852da
--- /dev/null
+++ b/operator-api/vitest.config.mjs
@@ -0,0 +1,13 @@
+import { defineConfig } from 'vitest/config'
+
+export default defineConfig({
+  test: {
+    globals: true,
+    environment: 'node',
+    include: ['tests/**/*.test.js'],
+    globalSetup: './tests/globalSetup.mjs',
+    hookTimeout: 30000,
+    testTimeout: 30000,
+    bail: 0
+  }
+})
diff --git a/shared/build-operator-api.sh b/shared/build-operator-api.sh
new file mode 100644
index 00000000..87945fcc
--- /dev/null
+++ b/shared/build-operator-api.sh
@@ -0,0 +1,48 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# build-operator-api.sh
+# -------------------------
+# Usage:
+#   build-operator-api.sh [dest-dir]
+#
+# Defaults:
+#   dest-dir  → ./bin   (mirror the Go server script behavior)
+#
+# Behavior:
+#   - Runs Bun in Docker from /workspace/operator-api
+#   - Produces artifacts in operator-api/dist:
+#       dist/kernel-operator-api
+#       dist/kernel-operator-test
+#       dist/.kernel-operator.env
+#   - Copies those three into DEST_DIR
+
+DEST_DIR="${1:-./bin}"
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+REPO_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
+MODULE_DIR="$REPO_ROOT/operator-api"
+ART_DIR="$MODULE_DIR/dist"
+
+BUN_IMAGE="${BUN_IMAGE:-oven/bun:1}"
+
+echo "Building kernel-operator-api with ${BUN_IMAGE}"
+docker run --rm \
+  -u "$(id -u):$(id -g)" \
+  -v "$REPO_ROOT":/workspace \
+  -w /workspace/operator-api \
+  "${BUN_IMAGE}" \
+  bash -lc 'bun i && bun run build'
+
+for f in kernel-operator-api kernel-operator-test .env; do
+  [[ -e "$ART_DIR/$f" ]] || { echo "Missing artifact: $ART_DIR/$f" >&2; exit 1; }
+done
+
+mkdir -p "$DEST_DIR"
+cp -f "$ART_DIR/kernel-operator-api" "$DEST_DIR/"
+cp -f "$ART_DIR/kernel-operator-test" "$DEST_DIR/"
+cp -f "$ART_DIR/.kernel-operator.env" "$DEST_DIR/"
+
+chmod +x "$DEST_DIR/kernel-operator-api" "$DEST_DIR/kernel-operator-test" || true
+
+echo "✅ kernel-operator-api (bin) , kernel-operator-test (bin) , .kernel-operator.env copied to $DEST_DIR/..."