Improve buildernet/mkosi readme

custom-recipes/buildernet/mkosi/README.md

@@ -8,10 +8,10 @@ Run a BuilderNet VM alongside builder-playground's L1 network. The playground ma
 
 - **Linux with KVM** (macOS is not supported)
 - **Docker** (for the L1 network stack)
-- **QEMU** with KVM support (`qemu-system-x86_64`)
+- **QEMU** with KVM support (`qemu-system-x86_64`, `qemu-utils`)
 - **UEFI firmware** (`edk2-ovmf` or equivalent)
 - **socat** (for VM console access)
-- **jq**, **curl**
+- **jq**, **curl**, **unzip**
 
 Verify KVM is available:
 
@@ -29,39 +29,42 @@ curl -sSfL https://raw.githubusercontent.com/flashbots/builder-playground/main/i
 mkdir buildernet-dev && cd buildernet-dev
 builder-playground generate buildernet/mkosi
 
-# 3. Point to the VM image binary
-#    - alternatively you can edit playground.yaml
-#    - you can point to local disk or URL
-export BUILDERNET_IMAGE=flashbots-images/path/buildernet-playground.qcow2
+# 3. Point to the VM image
+#    - you can point to a local file or URL
+#    - alternatively you can set this in playground.yaml (see below)
+export BUILDERNET_IMAGE=/path/to/buildernet-qemu.qcow2
 
-# 4. Start
+# 4. Start (runs L1 Docker stack + VM in the background)
 builder-playground start playground.yaml --bind-external --detached
 
-# 5. Verify by sending transaction
+# 5. Wait for the VM to boot (~60-90s) then check readiness
+./scripts/operator-api-health.sh    # repeat until you see "OK"
+
+# 6. Verify by sending a transaction
 builder-playground test --rpc http://localhost:18645 --el-rpc http://localhost:8545
 ```
 
 If the test transaction is included in a block, the full pipeline is working: transaction reaches rbuilder inside the VM, rbuilder builds a block, and it lands on the L1 chain.
 
-## Using Your Own Image
-
-For developers working on [flashbots-images](https://github.com/flashbots/flashbots-images) who want to test VM changes against a local network.
-
-Build the image in your flashbots-images checkout using the **playground** mkosi profile, then point `BUILDERNET_IMAGE` to it:
+You can also set `BUILDERNET_IMAGE` in `playground.yaml` instead of using an environment variable:
 
 ```yaml
 # In playground.yaml, under builder > env:
 env:
-  BUILDERNET_IMAGE: "/path/to/buildernet-qemu_latest.qcow2"
+  BUILDERNET_IMAGE: "/path/to/buildernet-qemu.qcow2"
 ```
 
-Or override via environment variable:
+## Building Your Own Image
+
+For developers working on [flashbots-images](https://github.com/flashbots/flashbots-images) who want to test VM changes against a local network.
+
+Build the image in your flashbots-images checkout using the **playground** mkosi profile, then point `BUILDERNET_IMAGE` to the output:
 
 ```bash
-export BUILDERNET_IMAGE=/path/to/buildernet-qemu_latest.qcow2
+export BUILDERNET_IMAGE=/path/to/flashbots-images/mkosi.output/buildernet-qemu_latest.qcow2
 ```
 
-See the [flashbots-images](https://github.com/flashbots/flashbots-images) repository for build environment setup, available profiles, and customization options.
+See the [flashbots-images](https://github.com/flashbots/flashbots-images) repository for build environment setup, available profiles, and customization options. You can also look at [`./scripts/build.sh`](scripts/build.sh) for a reference on how to clone and build the image.
 
 ## VM Management
 
@@ -79,6 +82,22 @@ See the [flashbots-images](https://github.com/flashbots/flashbots-images) reposi
 ./scripts/console.sh    # Serial console (exit: Ctrl+])
 ```
 
+### Logs
+
+VM serial output (kernel, systemd, service logs) is captured to `.runtime/console.log`:
+
+```bash
+tail -f .runtime/console.log
+```
+
+For operator-api event logs (rbuilder lifecycle, config fetches, etc.):
+
+```bash
+./scripts/operator-api-logs.sh
+```
+
+For Docker service logs (Reth, Lighthouse, mev-boost-relay, etc.), use `builder-playground logs`.
+
 ### Environment Variables
 
 | Variable | Default | Description |
@@ -108,16 +127,14 @@ Available actions: `reboot`, `rbuilder_restart`, `rbuilder_stop`, `fetch_config`
 # Stop just the VM (Docker keeps running)
 ./scripts/stop.sh
 
-# Stop everything
+# Stop everything (use `builder-playground list` to find the session name)
 builder-playground stop <session-name>
 
 # Full cleanup
 builder-playground clean <session-name>
 ./scripts/clean.sh
 ```
 
-Use `builder-playground list` to find the session name.
-
 ## Ports
 
 ### VM (QEMU host forwarding)

custom-recipes/buildernet/mkosi/scripts/build.sh

@@ -1,15 +1,32 @@
 #!/usr/bin/env bash
-# Build the BuilderNet VM image
+# Clone flashbots-images (if needed) and build the BuilderNet VM image
 set -eu -o pipefail
 
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 PROJECT_DIR="${SCRIPT_DIR}/.."
 
 FLASHBOTS_IMAGES_DIR="${PROJECT_DIR}/.flashbots-images"
+FLASHBOTS_IMAGES_REPO="https://github.com/flashbots/flashbots-images.git"
+FLASHBOTS_IMAGES_BRANCH="${FLASHBOTS_IMAGES_BRANCH:-main}"
 
 if [[ ! -d "${FLASHBOTS_IMAGES_DIR}" ]]; then
-    echo "Error: flashbots-images not found. Run ./scripts/sync.sh first."
-    exit 1
+    echo "Cloning flashbots-images (branch: ${FLASHBOTS_IMAGES_BRANCH})..."
+    git clone --branch "${FLASHBOTS_IMAGES_BRANCH}" "${FLASHBOTS_IMAGES_REPO}" "${FLASHBOTS_IMAGES_DIR}"
 fi
 
-make -C "${FLASHBOTS_IMAGES_DIR}" build-playground
+# Setup mkosi if needed
+MKOSI_COMMIT=$(cat "${FLASHBOTS_IMAGES_DIR}/.mkosi_version")
+VENV="${FLASHBOTS_IMAGES_DIR}/.venv"
+MKOSI="${VENV}/bin/mkosi"
+
+if [[ ! -x "${MKOSI}" ]]; then
+    echo "Setting up mkosi (commit: ${MKOSI_COMMIT})..."
+    python3 -m venv "${VENV}"
+    "${VENV}/bin/pip" install -q --upgrade pip
+    "${VENV}/bin/pip" install -q "git+https://github.com/systemd/mkosi.git@${MKOSI_COMMIT}"
+    echo "Installed: $(${MKOSI} --version)"
+fi
+
+echo "Building playground image..."
+cd "${FLASHBOTS_IMAGES_DIR}"
+${MKOSI} --force -I buildernet.conf --profile="devtools,playground"