> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bricks.tools/llms.txt
> Use this file to discover all available pages before exploring further.

# Simulator

> Run your BRICKS application in an embedded simulator pane

Run your BRICKS application inside the chat window. The **Simulator** tab in a [panel](/ctor/reference/panels) runs the compiled project as an embedded webview, picks up file changes automatically, and exposes a Chrome DevTools Protocol (CDP) endpoint for the [BRICKS CLI](/cli).

<Note>
  While the [Editor](/ctor/reference/editor) tab has unsaved edits, the Simulator renders those live unsaved edits until you save.
</Note>

## Open the simulator

Add the **Simulator** tab from either [panel](/ctor/reference/panels)'s **+** (New tab) menu, or click the **Simulator** button in the input bar — a play icon that switches to a pulse icon while the simulator is running. The tab starts compiling your project in the background.

When the tab opens, CTOR type-checks (`bun typecheck`) and compiles (`bricks ctor compile`) the project, then loads the application into an embedded webview using the stage from your `application.json` (`production`, `beta`, or `development`).

<Info>
  The Simulator requires `bun` to be installed and available in your `PATH`.
</Info>

## Pane controls

The tab's toolbar has these buttons:

| Button       | Action                                                                                  |
| ------------ | --------------------------------------------------------------------------------------- |
| **Draw**     | Toggle Draw mode                                                                        |
| **Save**     | Composite your annotations onto a screenshot and attach it to the chat (Draw mode only) |
| **DevTools** | Dock the simulator's inspector below the pane                                           |
| **Ask**      | Insert a prompt asking the agent to inspect the running simulator via its CDP endpoint  |
| **Refresh**  | Reload the webview                                                                      |
| **Pop out**  | Open the simulator in a new in-app window                                               |
| **Close**    | Stop the simulator and close the pane (pop-out window only)                             |

Close the simulator with the **×** on its tab in the panel — or, in a pop-out window, its **Close** button; this stops the backend.

## Simulator menu

Open the simulator pane's menu with the **≡** button. It lists:

* **Viewer** — inspect the running application's runtime Data
* **Logs**
* **Debug View**
* **Automations**
* **Mute**
* **Clear Persistent Data**
* **Take Screenshot**
* **Record Events as Automations** — turn a recorded session into a [BRICKS Automation](/foundation/automations) (see [Record interactions as an automation](#record-interactions-as-an-automation))
* **Simulator Settings** — choose which Bricks and Generators use simulated stand-ins (see [Simulated hardware and models](#simulated-hardware-and-models))
* **Compatibility**

## Simulated hardware and models

So the simulator can run without device permissions, API keys, or large model downloads, it substitutes lightweight fallbacks for hardware Bricks and model Generators:

* **Camera** — shows a mock 3D canvas instead of a real camera feed.
* **Maps** — renders free OpenStreetMap tiles, so no map API key is needed.
* **Thermal Printer** — renders a simulated on-screen receipt; it is always simulated.
* **LLM**, **Reranker**, **Speech-to-Text**, **Text-to-Speech**, and **Vector Store** Generators — run tiny local stand-in models.

Generators that are offloaded to [BRICKS Buttress](/buttress) are disabled in the simulator.

A status bubble in the bottom-left corner lists the active simulations and includes a **Simulator Settings** link. Open **Simulator Settings** from that link or the [simulator menu](#simulator-menu) to control which parts run simulated. The panel groups its toggles into **Bricks** and **Generators** sections — uncheck a Brick or Generator to use its real implementation, then click **Apply**. Applying reloads the simulator.

You can inspect simulated thermal-printer output from a terminal in your project directory:

```bash theme={null}
bricks devtools simulator thermal-printer list
bricks devtools simulator thermal-printer print-result -o receipt.png
```

Print history is held in memory — up to 10 receipts per printer — and cleared when the simulator reloads.

## Network security

By default, the simulator blocks insecure `http://` and `ws://` requests; secure `https://` and `wss://` requests are allowed. To test against a host that only serves insecure connections, add it to the project-level `allowedInsecureHosts` setting to whitelist it.

## Dock the simulator's DevTools

Click **DevTools** in the tab's toolbar to dock the simulator's own Chrome DevTools inspector as a resizable panel at the bottom of the tab. Drag the divider to adjust its height; click **DevTools** again to hide it.

The inspector connects to the simulator's local CDP server, so no credential is needed. Opening a device's DevTools from the **Local Devices** panel routes into this dock when that device is the foreground project's simulator; other devices open as their own [DevTools tab](/ctor/reference/panels#devtools) instead.

## Layout in the panel

The simulator shares its [panel](/ctor/reference/panels) with the Diff, Editor, Files, Browser, and DevTools tabs — either the right panel or the bottom panel. Only one tab is visible at a time per panel — switch between them from the tab bar, or with **Cmd+1..9** in the right panel. Drag the handle on the panel's edge to resize it against the chat area.

## Live recompile

The pane watches your project for changes:

* Saving any file under `subspaces/` triggers a debounced rebuild via `bun compile`.
* Changes to `.bricks/build/application-config.json` are pushed into the running webview without a full reload.

## Pop-out window

Click **Pop out** to detach the simulator into its own frameless in-app window. The new window keeps the backend session alive — closing the chat-side pane, switching sessions, or switching projects does not stop a popped-out simulator. Close the pop-out window itself to release the session.

## Agent-driven simulator

The agent uses the same simulator runtime as the **Simulator** tab to take screenshots and run [BRICKS Automation](/foundation/automations) tests, so what the agent sees matches what you see in the tab. If the tab isn't open when the agent needs a screenshot, it spins the simulator up in the background instead of opening it on top of your chat. The input bar's **Simulator** button — showing its pulse icon — surfaces this with the tooltip **Simulator running in background**; click it to bring the simulator tab forward.

Vision-capable models receive each screenshot inline; the image file is also written to the project so non-vision models can reference it by path. With a [fallback vision model](/ctor/reference/settings#fallback-vision-model) set, CTOR also describes each screenshot as text so a non-vision model can act on what it shows.

## Record interactions as an automation

As you interact with the running simulator, CTOR records each step. Open the simulator pane's menu (the **≡** button) and click **Record Events as Automations** to turn the recorded session into a [BRICKS Automation](/foundation/automations) (E2E test).

Rather than write the test silently, CTOR pre-fills the chat input with a request asking the agent to author the automation — review it and press send, the same way [Draw mode](#draw-mode) hands its result to the input bar. The request describes the recording for the agent:

* **Real timings** — each step carries the wall-clock time it fired and the gap from the previous step, so the agent can reproduce realistic timing between steps instead of uniform delays.
* **Named entries** — the subspaces, bricks, generators, and canvases referenced by each step are resolved to their editor alias (falling back to their title), so the request reads in terms of your project instead of opaque ids.
* **Brick Sketch drawings** — a drawing is recorded as the importable state it produces, one step per drawing burst, so replay reproduces the drawn result instead of a noisy stream of per-stroke steps.

Edit the request before sending to trim or reorder steps. The agent writes the automation in the bricks-ctor format, then compiles and runs it in the simulator to confirm it passes.

## Running multiple projects

Each open project keeps its own simulator lifecycle, so a simulator started in one project keeps running while you work in another. Only one simulator pane is visible at a time — whichever project is in the foreground — but background simulators stay alive for agent screenshots, CDP inspection, and pop-out windows.

## Draw mode

Click **Draw** in the pane header to overlay an annotation canvas on top of the running simulator. A toolbar appears at the bottom of the pane with these tools:

| Tool          | Action                                                                            |
| ------------- | --------------------------------------------------------------------------------- |
| **Pen**       | Freehand stroke                                                                   |
| **Arrow**     | Straight arrow from where you start the drag to where you release                 |
| **Rectangle** | Outlined box                                                                      |
| **Text**      | Click to place re-editable, multiline text; double-click existing text to edit it |
| **Erase**     | Drag over shapes to remove them                                                   |

Pick a stroke color from the palette and set the line width with the slider. **Undo** and **Redo** step through your edits — or press **Cmd/Ctrl+Z** to undo and **Cmd/Ctrl+Shift+Z** (or **Cmd/Ctrl+Y**) to redo. **Clear** removes everything.

Annotate directly on the simulator content — circle a misaligned element, mark a target area, or jot a quick note — then click **Save** to composite your strokes onto a simulator screenshot and attach the single image to the chat input.

Draw mode works in both the inline pane and the popped-out simulator window. From a popped-out window the saved image is forwarded to the main window's chat input automatically.

Because **Save** produces an image attachment, the **Draw** button is disabled when the selected chat model has no vision support — unless you've set a [fallback vision model](/ctor/reference/settings#fallback-vision-model), which describes the annotated screenshot as text.

## CDP and `bricks devtools`

While the simulator is running, CTOR starts a CDP server and writes discovery info to `.bricks/devtools.json` in your project directory. The [BRICKS CLI](/cli) reads this file to inspect the running simulator from a terminal.

From inside the project directory:

```bash theme={null}
bricks devtools scan        # auto-discover the local simulator
bricks devtools brick tree  # walk the brick component tree
```

Run `bricks devtools --help` for the full subcommand list (`brick`, `input`, `network`, `runtime`, `screenshot`, `storage`).

The discovery file is removed when you close the pane.

## Session switching

Switching to a different chat session hides the simulator pane if it belongs to another project or session, but does **not** stop the underlying simulator. The pane reappears when you return to the project and session that owns it. Use the pane's **Close** button to stop the simulator when you no longer need it running.