ComfyUI-BlueBox Introduction
ComfyUI-BlueBox is a visual image editor and workflow bridge for ComfyUI. It lets you open an image from your workflow, make visual edits, and send the result back into the workflow so generation can continue.
Rather than moving images between ComfyUI and a separate editing application, you can use the built-in editor to:
- Paint and erase masks.
- Add colored sketches or annotations directly onto an image.
- Crop, rotate, or expand the image canvas.
- Adjust colors, brightness, contrast, and other image settings.
- Review your changes against the original image.
- Continue processing from an editable point in the middle of your workflow.
This is useful when you want more hands-on control over an AI image—for example, marking an area for later editing, sketching a visual guide, correcting colors before another processing step, or preparing a larger canvas for an outpainting workflow.
BlueBox provides two nodes:
| Node | Main purpose |
|---|---|
| Load Image (BlueBox) | Load an image and its mask at the beginning of a workflow. |
| Bridge (BlueBox) | Create an editable handoff point between upstream and downstream processing. |
The editor handles visual preparation and editing. Your connected ComfyUI workflow determines what happens afterward, such as inpainting or generating content in an expanded area.
Editor preview
ComfyUI-BlueBox editor main interface
Opening the editor
How to open the ComfyUI-BlueBox editor from a node
How ComfyUI-BlueBox Works
Think of BlueBox as an editing desk inside your image-generation workflow. An image arrives at the desk, you make adjustments, and then you decide when to send it onward.
1. Load an image and prepare its mask
Load Image (BlueBox) produces two outputs:
image: the picture that other image-processing nodes can use.mask: a separate selection map that compatible nodes can use to identify areas for processing.
A mask is not the same as a visible drawing. It carries selection information; how that selection affects the image depends on the downstream node.
BlueBox looks for a mask in this order:
- A mask explicitly supplied through
mask_file. - A matching, same-name sidecar mask file stored alongside the image.
- The image’s alpha channel, which contains transparency information.
- An all-zero mask if no other source is available.
The first available source takes priority. For example, an explicit mask_file takes precedence over transparency in the image.
The node also creates a colored mask preview for display in the interface.
2. Edit an image partway through the workflow
Bridge (BlueBox) receives an upstream image and gives you a place to edit it before further processing.
The distinction between Run and Continue is important:
| Action | What happens |
|---|---|
| Run the workflow | BlueBox refreshes the Bridge from the original upstream image, even if that upstream image has not changed. |
| Continue from the Bridge | BlueBox uses the saved editor result, when available, and lets downstream processing proceed. |
For a Bridge edit, Apply saves the result; Continue sends that result onward.
Running the workflow normally is not a substitute for pressing Continue when you want to use the Bridge’s edited image.
3. Save the editor result back to ComfyUI
When you click Apply, BlueBox saves the edited image, mask, and preview.
The destination depends on the node you opened:
- Load Image (BlueBox): the saved image and mask are written back to the node’s
imageandmask_filefields. - Bridge (BlueBox): the saved file paths are registered with the backend, ready for the next Continue action.
When Continue is pressed, BlueBox requests a fresh execution of the Bridge so ComfyUI can read the saved result. If the saved edited image is unavailable, the Bridge falls back to the upstream original.
ComfyUI-BlueBox Features
Load Image (BlueBox)
This node combines image loading with mask preparation.
Available capabilities:
- Select an image for your workflow.
- Upload an image directly through
image_upload. - Automatically choose a mask using the priority order described above.
- Output both the image and mask.
- Open the image in the BlueBox editor.
Example: Load an image, paint a mask around an area you want to revise, and connect the outputs to a workflow that uses images and masks for selective editing.
Bridge (BlueBox)
The Bridge creates an editable point in an existing image-processing chain.
Example: You can receive an intermediate image, adjust its colors or add a sketch, and then pass the revised image to the remaining workflow.
The block setting controls whether downstream processing must wait:
block value | Behavior | When it is useful |
|---|---|---|
never — default | Does not stop downstream execution. | When you do not need a mandatory review step. |
if_not_continued | Blocks downstream execution until you press Continue. Continue triggers a rerun and releases the result. | When you want to inspect or edit the image before later processing begins. |
Blocking requires a sufficiently recent version of ComfyUI. See Troubleshooting ComfyUI-BlueBox for compatibility details.
Mask tools
The editor includes:
- Brush: paint a mask by hand.
- Rectangle: create rectangular mask regions.
- Circle: create circular mask regions.
- Fill: use the mask fill tool.
- Eraser: remove parts of the mask.
Use freehand painting for irregular outlines and geometric tools for simpler shapes.
Example: A rectangle can quickly mark a broad area, while the brush and eraser let you refine the selection around smaller details.
Drawing tools
The drawing tools add visible marks to the image rather than selection information.
Available tools include:
- Brush.
- Rectangle.
- Circle.
- Fill.
- Eraser.
Drawing supports a 60% semi-transparent mode, allowing you to see underlying image details through your marks.
Example: You can sketch a rough shape or color guide before sending the image into another processing stage. Whether that sketch influences generation depends on your downstream workflow.
Crop, rotate, and expand
- Crop: keep a smaller portion of the image to adjust framing.
- Rotate 90°: change the image orientation in quarter-turn steps.
- Expand the canvas: use
Ctrlwhile dragging, with magnetic snapping to help align the expansion.
Canvas expansion prepares additional space around the image. It does not generate new content by itself; filling that space requires an appropriate downstream workflow.
Color and image adjustments
The editor provides:
| Control | Purpose |
|---|---|
| Texture | An additional texture adjustment control. |
| Auto Color | Apply an automatic color adjustment. |
| Input/Output Levels | Adjust how dark, midtone, and bright values are mapped. |
| Brightness | Make the image lighter or darker overall. |
| Contrast | Change the separation between darker and lighter areas. |
| Saturation | Increase or reduce color intensity. |
| RGB color bias | Shift the balance of red, green, and blue. |
Examples:
- Reduce saturation for a more subdued palette.
- Increase contrast for stronger tonal separation.
- Adjust RGB balance to move the image toward a warmer or cooler appearance.
Use the original-image comparison to check whether an adjustment improves the image without losing important details.
Navigation and editing aids
- Undo and redo: move backward or forward through editing history.
- Original-image comparison: review your edits against the source.
- Zoom and pan: switch between composition-level work and close detail work.
- Alt color picker: sample a color from the image.
- WebGL rendering: the editor uses browser graphics acceleration and supports large images.
Using ComfyUI-BlueBox
Basic workflow
- Add Load Image (BlueBox) and select or upload your image.
- Connect the image to your workflow.
- Add Bridge (BlueBox) wherever you want an editable intermediate stage.
- Connect an upstream
imageoutput to the Bridge. - Make sure the selected node has an image available. A Bridge must first receive its upstream image.
- Right-click the node and choose the 🟦 BLUEBOX editor entry.
- Make your mask, drawing, framing, or color edits.
- Click Apply to save and close the editor.
- If you edited a Bridge, return to ComfyUI and click Continue on that node.
If you instead run the workflow normally, the Bridge refreshes from the upstream original.
Keyboard and mouse shortcuts
| Shortcut | Action |
|---|---|
B | Mask brush |
E | Mask eraser |
R | Rectangle mask |
C | Circle mask |
F | Mask fill |
D | Drawing brush |
X | Drawing eraser |
Shift+R | Drawing rectangle |
Shift+C | Drawing circle |
Shift+F | Drawing fill |
Ctrl + drag | Expand the canvas, with magnetic snapping |
Crop tool + Ctrl + drag from outside the image | Expand the canvas |
Alt | Color picker |
Ctrl+Z | Undo |
Ctrl+Y | Redo |
| Middle mouse button + drag | Pan the view |
Space | Toggle between fit-to-view and 100% zoom |
Esc | Cancel a selection or exit crop/expansion mode |
Troubleshooting ComfyUI-BlueBox
Continue does not send the edited result downstream
- Check the Bridge node’s preview.
- If it still shows a placeholder rather than the edited result, reopen the editor.
- Click Apply again to save the edit.
- Return to ComfyUI and check for the updated preview.
- Click Continue.
A placeholder can indicate that the backend has not yet received the saved editor result.
The editor is blank or says it is waiting for an image
- Check which node you opened.
- For Load Image (BlueBox), make sure an image is selected in the
imagefield. - For Bridge (BlueBox), make sure its upstream image connection is present and has supplied an image.
- Reopen the editor once the image is available.
The editor needs an existing image to work with.
My Bridge edit is replaced when I run the workflow
This is the intended difference between Run and Continue.
- Open the editor and complete your changes.
- Click Apply.
- Click the Bridge’s Continue button to use the edited result.
A normal workflow run refreshes the Bridge from the upstream original, even when that original has not changed.
if_not_continued does not block downstream processing
The blocking feature depends on ComfyUI’s ExecutionBlocker support.
- Check whether you are using an older ComfyUI version.
- Look for a console message indicating that blocking support is unavailable.
- Update ComfyUI to a recent version that includes
comfy_execution.graph.ExecutionBlocker.
On older versions, the extension can still run, but blocking automatically falls back to allowing downstream execution.
Editing snapshots disappear in Safari
The author notes that Safari may automatically clear IndexedDB storage after seven days without access. This can remove editor snapshots stored in the browser.
To reduce the risk:
- Complete and apply your edits promptly.
- Avoid relying on browser snapshots as long-term storage.
- Consider Chrome or Edge, which the author recommends for compatibility.
Which browser should I use?
The editor requires WebGL and IndexedDB. Chrome and Edge are the author’s recommended browsers.
WebGL handles the editor’s graphics rendering; IndexedDB provides browser-side storage.
Why did BlueBox choose a different mask than I expected?
Check the mask sources in priority order:
mask_file.- Matching sidecar mask file.
- Image alpha channel.
- All-zero fallback mask.
A higher-priority source overrides a lower-priority one. For example, a selected mask_file is used before the image’s transparency information.
Does expanding the canvas automatically create new image content?
No. Canvas expansion changes the available image area. Use a suitable downstream generation or outpainting workflow to create content in the added space.
Does BlueBox require separate AI models?
The documented functionality consists of image loading, visual editing, and workflow bridging. No BlueBox-specific model downloads are listed; generation is handled by the models and nodes in your surrounding ComfyUI workflow.
Learn More about ComfyUI-BlueBox
- ComfyUI-BlueBox repository — access the project documentation and source files.
- Editor interface preview — see the editing workspace.
- Opening the editor — see where to access the editor from a node.
- Built-in editor source — the browser-based editor implementation, for readers interested in exploring how it works.
The extension uses ComfyUI’s existing Python dependencies and native browser features. Its frontend does not require external CDN resources.
ComfyUI-BlueBox License
ComfyUI-BlueBox is released under the MIT License.
