v0.3.3

builder-playground v0.3.3

This stable release graduates custom recipes toward production-ready, ships a unified BuilderNet VM built with mkosi, and hardens session management for faster, more reliable local runs. 🧪 🖥️ ⚡

Highlights

• 🧪 Custom Recipes, leveled up — Flag replacement, directory hierarchies, predeploys, host processes with env vars, host_path mounts, and file as a base reference
• 🖥️ BuilderNet VM — New unified mkosi recipe bundling attested-tls-proxy, HAProxy, and FlowProxy
• ⚡ Faster, safer sessions — Parallelized E2E tests, fixed session port allocation, stronger isolation, graceful shutdown flags, concurrent Docker + host service startup
• 📦 One-line install — New install.sh script, now the recommended installation path
• 🧰 Recipe tooling — validate subcommand for pre-flight checks, and k8s manifest generation from recipes
• 🛰️ Bootnode — New component and template with improved peer discovery
• 🔌 Port subcommand — Query service host ports directly from the CLI

---

🧪 Custom Recipes

The experimental recipe system from v0.3.1 gets substantially more capable in this release. You can now express much richer environments from a single YAML file:

• Directory hierarchy support when including custom recipes
• Predeploys defined from a custom recipe
• Host processes with configurable environment variables
• host_path mounts for pulling in local files
• file as a base reference in YAML recipes
• validate command for pre-flight checks before start
• k8s manifest generation for shipping a recipe to a cluster (experimental)

---

🖥️ BuilderNet mkosi VM

A new unified BuilderNet mkosi recipe lands in this release, bundling the pieces needed to run the stack locally:

Component	Description
attested-tls-proxy	Attested TLS termination
HAProxy	Load balancing, ports forwarded from the VM
FlowProxy	With required headers wired into test
BuilderHub	Updated config with HAProxy/FlowProxy integration

---

⚡ Performance & Reliability

• Stronger session isolation proven with parallel E2E testing
• More forceful stop on three interrupts
• Concurrent startup of Docker and host services
• Process survives detachment so detached sessions exit cleanly

---

🎮 Developer Experience

• port subcommand to query host ports for any service
• --ready-server optional flag exposing readiness on :8123
• Env vars for host processes in recipes
• rbuilder custom recipes updated, with support for new rbuilder releases
• Setup commands now run before image checks

---

📦 Installation

A new install.sh script is now the default installation method!

curl -fsSL https://raw.githubusercontent.com/flashbots/builder-playground/main/install.sh | sh

---

Get Started

Install via the new install script:

curl -fsSL https://raw.githubusercontent.com/flashbots/builder-playground/main/install.sh | sh

Or build from source:

git clone https://github.com/flashbots/builder-playground.git
cd builder-playground
go install .
builder-playground help

Then:

# See available recipes
builder-playground recipes

# Run a recipe, e.g. L1
builder-playground start l1

# Validate a custom recipe
builder-playground validate playground.yaml

# Find a service port in a running session
builder-playground port <service>

What's Changed

• Add port subcommand for querying service host ports by @dvush in #336
• Fix base-overlay entrypoint path: base-reth-node → base-client by @niran in #348
• CI: Restrict Claude Code triggers to users with write-access by @metachris in #349
• Integration tests for Rbuilder by @ferranbt in #335
• Add bootnode template, allow configuring base recipe flags through yaml. by @dvush in #347
• Add validate command for recipe pre-flight checks by @Ruteri in #352
• More forceful session stop on three interrupts by @Ruteri in #356
• CLI flags for custom recipes and graceful shutdown by @Ruteri in #353
• Improve YAML recipe parsing and host service support by @Ruteri in #350
• Add log file fallback for host services by @Ruteri in #351
• Wait for handle.Process to be set before attempting to kill on exits by @canercidam in #355
• Update CODEOWNERS by @canercidam in #361
• Use the directory hierarchy for including custom recipes in the CLI by @canercidam in #358
• Update rbuilder custom recipes by @canercidam in #359
• Start docker and host services concurrently by @canercidam in #364
• Flag replacement for custom recipes by @canercidam in #357
• Add mkosi flashbots-images VM to playground by @fkondej in #302
• Revert "Add mkosi flashbots-images VM to playground" by @canercidam in #365
• Add unified BuilderNet mkosi recipe by @canercidam in #366
• README: add info about CI / GitHub action by @metachris in #368
• Make rbuilder depend on beacon to avoid failures by @canercidam in #369
• Add attested-tls-proxy to buildernet/mkosi recipe by @canercidam in #367
• fix: instance name in builderhub config by @fkondej in #371
• Fix build version injection by @canercidam in #370
• Add workflow to run the playground action with dispatch by @canercidam in #372
• Use always absolute output path by @ferranbt in #344
• Add bootnode component by @ferranbt in #327
• Tests for validating recipes by @canercidam in #373
• feat: add --insecure to test cmd by @fkondej in #375
• feat: add HAProxy and FlowProxy config to BuilderHub and forward HAProxy ports from buildernet VM by @fkondej in #376
• Stronger session isolation and faster E2E tests with parallelization by @canercidam in #374
• feat: add headers required by FlowProxy to test command by @fkondej in #378
• Improve custom recipe experience and testing by @canercidam in #379
• lighthouse 8.0.0-rc2 -> 8.1.0 by @julio4 in #380
• feat: preserve dir structure for custom recipes by @fkondej in #383
• Add install.sh for easy installation and recommend in README.md by @canercidam in #384
• Fix installation explanation by @canercidam in #385
• feat: small improvements to BuilderNet recipe by @fkondej in #386
• fix: display extra data as text instead of hex in test output by @fkondej in #387
• Hiding custom recipes by @canercidam in #390
• Improve buildernet/mkosi readme by @fkondej in #388
• feat: re-add daemonize to start.sh and loop waiting for ./readyz by @fkondej in #391
• feat: make buildernet vm data disk size configurable with env var by @fkondej in #392
• feat: set default BUILDERNET_IMAGE to url and add readyz.sh helper script by @fkondej in #393
• chore: update buildernet image to latest release by @fkondej in #394
• fix: apply default healthcheck intervals for readycheck sidecars by @dvush in #397
• Support predeploys from custom recipe by @canercidam in #400
• feat: enable envs for host process by @julio4 in #398
• fix: improve discovery via bootnode by @dvush in #395
• Remove post-hook feature and move post-hook to mkosi recipe by @canercidam in #402
• Generate k8s manifests for recipes by @canercidam in #404
• Run setup commands before image checks by @canercidam in #405
• fix: session port allocation by @fkondej in #408
• feat: host_path support in recipes by @julio4 in #401
• Introduce a skill with supporting features and bug fixes by @canercidam in #410
• feat: support file as base reference in YAML recipes by @fkondej in #409
• Add optional --ready-server to :8123 by @canercidam in #411
• Keep playground process after detachment by @canercidam in #414
• Remove leftover session dirs by @canercidam in #413
• Support new rbuilder releases by @canercidam in #412
• fix(mac-os): tag extraction for latest release in install.sh by @alessandromazza98 in #406
• Fix Dup2 usage by @canercidam in #415
• Simplify docs by @canercidam in #416

New Contributors

• @Ruteri made their first contribution in #352
• @fkondej made their first contribution in #302
• @alessandromazza98 made their first contribution in #406

Full Changelog: v0.3.1...v0.3.3