Blueprints

A blueprint is a guide for adding an integration or a runnable agent example to your B4.run app. b4 add <name> fetches the guide and prints it. You hand it to your coding agent (Claude Code, Cursor, and so on), and the agent applies it to your project: it installs dependencies, creates files, and wires them in.

Blueprints are Markdown files served from b4.run, and your agent applies them as ordinary code in your app. They cover external integrations and complete agent examples built from B4.run routes and tools. For framework patterns, like writing a tool or typing state, see Recipes.

Using b4 add#Copy link to section: Using b4 add

b4 add                 # list available blueprints, grouped by category
b4 add pgvector        # print the pgvector blueprint for your agent to apply
b4 add code-fixer      # install a runnable developer-agent example
b4 add <url>           # apply a third-party blueprint from any URL

Pipe the output to your coding agent, or paste it in. b4 add only prints the guide. Your agent makes the changes, and you review them.

To use a self-hosted catalog (or a local dev server), set B4_BLUEPRINTS_URL.

Code-fixer agent example#Copy link to section: Code-fixer agent example

b4 add code-fixer prints a guide for installing the example from a pinned source commit with B4.run 0.11.0 packages. The agent repairs a real, historical CLI defect in a Docker workspace, verifies the patch independently, and asks for your approval before exporting it locally. You'll need Docker, Git, and Node 24. The verification tests use scripted model responses, so you don't need a model API key.

If your app's sandbox or permission settings conflict with the example, the guide installs it into a sibling app. It keeps your edits and records where the installation came from. Read the installation guide for setup and verification.

Authoring a blueprint#Copy link to section: Authoring a blueprint

Blueprints live under apps/web/content/blueprints/<category>/<name>.md in the B4.run repo. The filename is the blueprint's name (b4 add <name>), and the directory is its category (agents, observability, retrieval, deploy). The category is used for listing only, never in the command.

Only description is required in the frontmatter:

---
description: Add OpenTelemetry tracing to a B4.run app.   # required, written for an LLM
website: https://opentelemetry.io                        # optional
version: 1                                               # optional (default 1)
tags: [tracing, otel]                                    # optional
source: official                                         # optional: official | maintainer | community
---

The body is a guide written for an agent. Open with the intent and scope ("you are adding X, and it does Y"). Then cover the prerequisites, inspecting the project, installing dependencies, creating the file(s), wiring them in, configuring the environment, and verifying. Mark the first line of the main generated file with the blueprint and version that produced it:

// b4-blueprint: opentelemetry@1

Keep guides adaptive. Have the agent detect the package manager, read b4.config.ts and AGENTS.md, reuse existing dependencies, and follow the project's env conventions rather than assume them.