Skip to main content
Run your BRICKS application inside the chat window. The Simulator tab in a panel 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.
While the Editor tab has unsaved edits, the Simulator renders those live unsaved edits until you save.

​
Open the simulator

Add the Simulator tab from either panel’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).
The Simulator requires bun to be installed and available in your PATH.

​
Pane controls

The tab’s toolbar has these buttons: 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:

​
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 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 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:
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 instead.

​
Layout in the panel

The simulator shares its panel 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 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 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 (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 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: 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, 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 reads this file to inspect the running simulator from a terminal. From inside the project directory:
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.