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 https://github.com/flashbots/builder-playground/p...

v0.3.2-alpha.10

What's Changed

• Fix Dup2 usage by @canercidam in #415
• Simplify docs by @canercidam in #416

Full Changelog: v0.3.2-alpha.9...v0.3.2-alpha.10

v0.3.2-alpha.9

What's Changed

• 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

New Contributors

• @alessandromazza98 made their first contribution in #406

Full Changelog: v0.3.2-alpha.8...v0.3.2-alpha.9

v0.3.2-alpha.8

What's Changed

• 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

Full Changelog: v0.3.2-alpha.7...v0.3.2-alpha.8

v0.3.2-alpha.7

Highlights

• Enabling env vars for host processes
• Bootnode discovery fix
• Buildernet recipe fixes
• Kubernetes manifest generation for recipes (experimental)

What's Changed

• 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

Full Changelog: v0.3.2-alpha.6...v0.3.2-alpha.7

v0.3.2-alpha.6

What's Changed

• 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

Full Changelog: v0.3.2-alpha.5...v0.3.2-alpha.6

v0.3.2-alpha.5

Highlights

• BuilderNet recipe improvements
• New installation script

What's Changed

• 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

Full Changelog: v0.3.2-alpha.4...v0.3.2-alpha.5

v0.3.2-alpha.4

Highlights

• test command improvements (retries, better timeout handling, insecure with TLS, FlowProxy support)
• Stronger session isolation (ports, dirs, networks) and ability to run multiple playground sessions in parallel
• Improved E2E testing (thanks to above)
• Custom recipe improvements (setup commands, port override, host_path resolution)
• New bootnode component

What's Changed

• 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

Full Changelog: v0.3.2-alpha.3...v0.3.2-alpha.4

v0.3.2-alpha.3

Highlights

• Fixes for the buildernet/mkosi recipe
• Avoiding rbuilder failures with latest changes
• Mentioning the new GitHub action in the README
• Fixing version injection

What's Changed

• 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

Full Changelog: v0.3.2-alpha.2...v0.3.2-alpha.3

v0.3.2-alpha.2

Highlights

• New recipe buildernet/mkosi for running the complete stack locally (partially completed)
• Custom recipe feature improvements
  • New lifecycle_hooks feature (enables a new type of service)
  • Better flag configuration through custom recipes (base recipe flags, replacing service args)
  • Recipe validation, adding CLI flags to custom recipes
  • Three-interrupt forced shutdown
  • Better log file handling
• Stability and concurrency improvements in health checks and start-ups

What's Changed

• 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

New Contributors

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

Full Changelog: v0.3.2-alpha.1...v0.3.2-alpha.2