# Advanced: Brick Runtime

The Brick Runtime controls how PixieBrix executes bricks, including: passing information between bricks, error handling, and logging.

Whenever we introduce a non-backward compatible change to the runtime, we increment the brick runtime `apiVersion` field, e.g., `v1`, `v2`, `v3`.

We maintain support for bricks written with old versions of the runtime. Bricks built with different versions of the runtime can be used together.

### Specifying the runtime in YAML Brick Definitions

When using YAML-based configuration, the runtime is controlled via the `apiVersion` directive:

```yaml
apiVersion: v3
```

For backward compatibility, apiVersion defaults to `v1`.

### Runtime v3: Release 1.5.0

Runtime v3 introduces the following backward-incompatible changes:

* Support for field-level templates/expressions: `!var`, `!nunjucks`, `!mustache`
* A `!pipeline` and `!defer` expression boundaries (for use in the Document Builder)
* Drops support for the brick-level `templateEngine` directive (the directive is ignored)
* Templates are no longer auto-escaped (because HTML is sanitized prior to rendering). To escape a template:
  * Nunjucks: use the [escape filter](https://mozilla.github.io/nunjucks/templating.html#escape-aliased-as-e)
* Support for the Handlebars template engine has been dropped

Page Editor changes:

* Nunjucks replaces Mustache as the default template engine
* Each field has a toggle to control how to pass data to

#### Migrating from v2 to v3

{% hint style="info" %}
If you’d like assistance migrating your mods from v2 to v3, we’d love to help! Contact us at <support@pixiebrix.com>
{% endhint %}

* **Page Editor:** When you open a mod written with v2 in the Page Editor, the Page Editor will attempt to convert it automatically to a v3 mod. When you save the mod, the Page Editor will save the mod as a v3 mod.
* **Workshop:**
  * Update the API version directive for the brick: `apiVersion: v3`
  * Update each template and variable expression to use `!var`, `!mustache`, or `!nunjucks`

#### Migrating from v1 to v3

* To migrate an mod from v1 to v3, you must use the workshop

### Runtime v2: Release 1.4.0

Runtime v2 introduces the following backward-incompatible changes:

* Bricks must reference data by `@input`or `@outputKey`. Data no longer flows implicitly from one brick to the next

Enhancements:

* Mods now support a `definitions` section that can contain inline starter brick and reader definitions


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.pixiebrix.com/developing-mods/developer-concepts/advanced-brick-runtime.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.