Scumble manual

Scumble is a normal desktop app. Download the installer from the latest release on GitHub, run it, and it is in your start menu. There is no account, no sign-up and no server of mine in between: the app talks to your own ComfyUI, or to the API provider whose key you gave it, and to GitHub when it looks for an update.

The installer is not code-signed yet, so Windows shows "Windows protected your PC" the first time. That is the warning Windows gives every unsigned program, not a verdict about this one. Click More info, then Run anyway. Updates after that are downloaded by the app itself and do not go through SmartScreen again. Proper signing is planned through the SignPath Foundation, which is free for open-source projects but wants a project with a public release and some use behind it first.

On Linux the same release carries an AppImage and a .deb. Fair warning: they are built by CI and have not been run by me, because I have no Linux machine here. If you try one, tell me what breaks. macOS is prepared but not released.

The app alone can do a great deal — open, paint, select, layer, filter, export — but it generates nothing until it has somewhere to render. That is the next chapter.

Scumble does not generate anything itself. It sends your selection somewhere and puts the answer back as a layer. That somewhere is either your own ComfyUI, or a model provider you have an API key for. You can have both and switch per run; the recipe picker in the top bar decides which one a run uses.

Your own ComfyUI is free to run, keeps every pixel on your machine, and gives you the models you already downloaded. It needs the node pack ComfyUI-InpaintCanvas installed there, and the models the recipe asks for. Type the server's address into the top bar — http://127.0.0.1:8188 for a local one, or the address of a rented box, RunPod included — and press Connect. If the node pack is missing, Scumble notices and offers to install it through the ComfyUI Manager.

An API provider needs no server at all. Put a key into Settings › API providers and the models behind it appear in the recipe picker: Google's Nano Banana, OpenAI's GPT Image, Black Forest Labs' FLUX.2, ByteDance's Seedream, Qwen Image Edit, and the same models through aggregators like fal.ai, Replicate, WaveSpeedAI, ToAPIs, Comfy Cloud, Comfy Router and OpenRouter. You pay that provider directly; Scumble takes no cut and sees no invoice. Comfy Router has no key row of its own: it runs on the Comfy Cloud key, with credits and without a paid Comfy plan. The same key runs HY Image 3.5 through Comfy's Partner API.

Keys are stored in the operating system's own credential store through Electron's safeStorage, never in a settings file you might share by accident. On Linux that is the desktop keyring; if the system has none, the settings say so in plain words rather than pretending the key is encrypted when it is only obfuscated.

The same key rows also feed two other things: the assistant, and prompt upsampling. If you already have an OpenRouter key, one key covers a lot of ground at once.

The loop is always the same, whatever the model behind it: select an area, write what should be in it, press Generate. What comes back is a layer sitting over the selection, not a new picture — which is the point of the whole app. If you do not like it, you delete the layer and the original is untouched underneath.

Open a picture with Ctrl+O, by dropping it on the window, or by pasting from the clipboard. PNG, JPEG and WebP, and since 0.1.25 also PSD and ORA files with their layers intact. Then paint over the thing you want changed with the selection brush — the default tool, size with the bracket keys, Alt to erase what you painted too much of.

The prompt goes into the Generate tab on the right. Describe what should be in the selected area, not what is there now: "a red leather handbag" and not "change the bag to red leather". Then Generate, or Ctrl+Enter. A run on a local ComfyUI takes as long as your card needs; an API run is usually ten to thirty seconds. While it runs you can keep working, even in another tab.

The result arrives as a layer over the selection, and the layer row has a Match slider. That slider is the small feature that saves most results: it matches the colours of the generated patch to what surrounds it, so the piece stops looking pasted in. Start at 100 %, pull it back when the model's own tone is worth keeping.

Happy with it? Ctrl+S saves the visible picture. Not happy? Press Generate again — a new seed, a new layer, and you can compare the two by toggling their eyes.

The selection is the most important thing in an inpainting editor, so Scumble gives it seven routes. The brush is the honest one: paint, Alt to subtract, done. Rectangle, ellipse and lasso are there for the shapes that painting gets wrong. The magic wand takes everything of a similar colour from where you clicked, which is what you want for skies and flat backgrounds.

Object hover is the one people like: move the pointer over the picture and Scumble outlines the object under it, click to select it. That is SAM2 running inside the app through ONNX Runtime, on your GPU on Windows and on the processor on Linux. Nothing leaves your machine, and the model file is downloaded once or read from a ComfyUI models folder you point at.

Selection by text is the other one: type "the handbag" or "her sunglasses" into the Selection panel and press Go. That route runs on your connected ComfyUI (SAM3 there), so it needs a server, unlike object hover.

Once you have a selection, the Selection panel does the rest: grow and shrink it by a pixel count, feather its edge, invert it, take it from a layer's transparency, or save it under a name to come back to later. Selections survive a restart with the document.

A recipe is Scumble's answer to the node graph. It names a model — "FLUX.2 [max]", "Nano Banana 2", "Upscale model (ComfyUI)" — and, for models that several services host, the provider it should go to. Picking one from the top bar is the whole configuration; the settings the model actually has (steps, guidance, seed, resolution) appear in the Settings panel of the Generate tab, with sensible defaults.

Local recipes are ComfyUI workflows in API format with an Inpaint Canvas node in them. The shipped ones cover FLUX.2 Klein, SDXL inpainting, Qwen Image Edit and an upscale-model chain. You can import your own: Settings › Recipes, Import, pick your exported workflow. If it holds an Inpaint Canvas node, Scumble fills that node with your canvas and queues the rest exactly as you built it.

Provider recipes go out over HTTPS with your key. Scumble crops the selection with context, sends it at a size the provider really accepts — the Highres fix setting picks the tier — and stitches the answer back at full resolution with the surrounding pixels preserved. Models that take a mask get one; models that do not get an instruction edit and Scumble's own composite mask does the blending afterwards. Reference layers are sent along for the models that take references.

Generate new makes the base picture from the prompt alone, locally or through a provider, when you want to start from nothing rather than from a photo. And prompt upsampling turns a short prompt into a long one through a language model — your own key, an OpenRouter or ToAPIs key, or a local Ollama or LM Studio that needs no key at all. Your own prompt-writing rules can be stored as Markdown templates, so upsampling follows your house style and not a generic one.

Scumble is a layered editor that happens to generate, not a generator with an undo button. Every result, every paint stroke, every piece of text and every filter is a layer with an opacity, a blend mode, a mask and a name. You can reorder them, duplicate them, merge them down, hide them, erase into them and copy them between tabs. Flatten is a command you give, not something that happens to you.

Colour match is the feature I would keep if I had to throw the rest away. A generated patch almost always comes back a little off: a shade cooler, a touch brighter, a different contrast to its surroundings. The Match slider in the layer row corrects that by matching the layer's statistics to what lies around it — or to what lies below it, your choice in the same row — and it is non-destructive, so you can move it any time.

Masks do the rest of the fitting. Every layer can have one, painted with the normal brush; erasing into a result layer with the eraser writes the mask, not the pixels, so an over-eager erase is one Ctrl+Z away. For photographic repairs there are clone, heal and smudge tools that work like the ones you know.

Around all this sit transform (move, scale, rotate, flip, with a perspective mesh), crop, and extend canvas — which is how outpainting starts: extend the canvas, select the new empty part, prompt, generate.

A filter in Scumble is a layer, not a one-way change to your pixels. Add one and everything below it is filtered; drag it up or down and it filters more or less; set its opacity, give it a mask, or switch it off. Its settings stay editable a week later.

The built-in set covers the photographic basics: grain with film presets, curves, levels, colour balance, HSL, exposure and contrast, sharpen, blur, normalise, vignette, and LUTs from .cube files. They run on the GPU through WebGL2, so they stay interactive on large pictures, with a processor path as a fallback.

The film pack is a plugin that ships with the app and goes further: film looks with real film names, halation, glow, bleach bypass, cross processing, split toning, light leaks, frames, and control points that steer a look locally. The names are there so you know what a look is after; the values are Scumble's own approximations, not licensed manufacturer data, and the tooltip and the About dialog say so.

Text is a layer that stays text: font, size, colour, spacing, alignment and a few effects, editable after the fact, exported into PSD as its own layer. The bundled fonts are open-licensed, and the ones installed on your system are offered too.

The shape tool draws rectangles, ellipses, polygons, Bezier paths and freehand paths, filled, outlined or both, with a corner radius, clipped to the selection if there is one. Each shape is one undo step.

Brushes can be loaded from Photoshop .abr files, which means the brush set you already own works here for painting and for masking.

And there are 3D objects: drop a .glb file in, and it is placed into the picture as a layer you can rotate, scale and light. It is a niche feature with a clear use — a product, a prop or a reference shape put into a scene in the right perspective before you let a model paint over it.

The Upscale button sits next to Generate new and opens a small dialog: which upscaler, then the selection or the whole picture, then the factor. Which of the two you pick changes what happens more than it sounds.

The selection goes out at its own size and comes back sharper at the document's resolution — a detail pass on a face, a label, a piece of texture, landing as a layer like any other result. The whole picture goes out alone and the answer becomes the new base: the document is resized, layers, masks and the selection scale with it, and that is one undo step.

Through a provider you get Topaz (Precision, Bloom, Wonder), Clarity, SeedVR2, Recraft and Magnific (Precision and Creative), each on its own key or through fal. Times differ wildly and the status line warns you about the slow ones — Magnific Precision took five minutes for a small box in my own test, Topaz about twenty-five seconds for the same kind of job.

On your own ComfyUI, the Upscale model recipe runs any model in your server's upscale_models folder — ESRGAN, UltraSharp, DAT, whatever you have. That route works on the selection only. Two of the upscalers, Clarity and Magnific Creative, also take a prompt; since 0.1.27 the dialog shows a prompt field for those, filled from the Generate tab but sent separately.

Ctrl+S saves the visible picture. The Export panel does the rest: PNG, JPEG or WebP for a flat result, PSD or OpenRaster when you want the layers, masks and selections to survive into Photoshop, Krita or GIMP. You can export at a percentage, at a pixel size, or into a frame of a given size with a background of your choosing, and a single layer or the mask on its own.

The AI label panel writes the EU AI Act's disclosure into the file's metadata, for the day you need to say in the file itself that a model was involved.

Every document is a tab, and tabs come back. The session is autosaved and restored at the next start, with no server needed for it, because every image the editor sends or receives is kept locally under %APPDATA%/Scumble/files/ in folders that mirror ComfyUI's own input and output. That is also why a restarted or freshly rented ComfyUI just works: before a run the app uploads what the server does not have.

Ctrl+Shift+A opens a chat column next to the canvas. Tell it what you want — "remove the bollard on the left and match it to its surroundings" — and it does it by calling the same commands an external agent would: select, prompt, generate, match, layer by layer. Every call is a card you can open to see exactly what it did.

It runs on your own API key. Anthropic, OpenAI and Google directly, or anything OpenAI-compatible: OpenRouter, DeepSeek, Moonshot, Z.ai, ToAPIs, WaveSpeed, or a local server that needs no key at all. The picker groups models by provider and greys out the ones you have no key for. Your own model ids can be added in Settings › Language models, so a model released after this version of Scumble still works.

It asks before it does anything expensive or irreversible: generating, upscaling, selecting by text, anything that queues on your ComfyUI or costs a provider call, anything that clears the undo stack, anything that touches a layer that is not its own. The question card shows the reason, the file, the recipe and the old and new values, and neither button is the default one.

And it can be taken back. Ctrl+Z undoes its steps one at a time like your own, and Undo this turn puts every document the turn touched back to where it was before — even when the turn was longer than the undo stack. Chats are saved with their screenshots and can be reopened; Settings › Assistant deletes everything it ever stored, your keys excepted.

F1, the Help button in the top bar or Help › Scumble help opens this manual in a column beside the canvas. It is the same text as on the website, shipped with the app, so it works offline and describes the version you are running. Type into the search field and the chapters narrow down to the ones that mention every word you typed, with the words marked; Enter jumps to the first of them.

Above the manual sits a chat. Ask it how to do something, "how do I take a piece out of a selection?", and it answers from this manual and from nothing else, and ends with the chapter it took the answer from; a click on that line opens the chapter. When the manual does not cover a question, it is told to say so and point you to the docs on GitHub instead of inventing a menu item.

The chat runs on any model you have a key for, including small text-only ones: it needs no eyes and no tools. It cannot change anything in the app, which is the assistant's job (Ctrl+Shift+A). Without any key the panel is simply the manual.

Underneath the interface, everything the editor can do is a named command with documented parameters. The assistant uses them. So can you: Help › Copy MCP registration puts the line for your MCP client on the clipboard, and after that Claude Code, Claude Desktop or any other MCP client drives Scumble directly — open a picture, select the handbag, generate, export. For scripts there are --headless and --cmd, which run the app without a window.

Plugins are JavaScript. A plugin folder with a plugin.json can add filters (with a GPU and a processor path), panels, menu actions, tools and commands of its own. The film pack, the 3D object tool and the AI label panel are plugins themselves, which is the honest test of whether an extension point is good enough.

The same editor also lives on as the ComfyUI node Inpaint Canvas, built from this repository. If you work inside ComfyUI, you get the same canvas there.

Scumble keeps the picture, every layer and every mask in tiles rather than in one big canvas, and the pixel work — flood fill, grow and shrink, blur, blending, the match — runs as compiled Rust in worker threads. That is the reason a 15,000 by 10,000 document paints, selects, filters and exports without the window locking up, and why export and selection work happens off the main thread.

The tile engine is on by default. Settings › Rendering has the switch back to the old canvas path, which exists as an escape hatch if something ever looks wrong on your hardware; the app is slower and hungrier that way, but it is there.

Above the browser's canvas limit — beyond about 268 megapixels — pictures are opened and written in strips instead, which is how PNGs up to 65,535 pixels a side and about a gigapixel work at all.

Every inpainting model has a size it works at, and it is small: around one megapixel, four at the very top end. Your picture is not. A 6000 by 4000 photo is 24 megapixels, and the thing you selected in it might be 300 pixels across. That gap is the whole problem of inpainting at photo resolution, and everything in this chapter exists to close it.

The naive answer — scale the picture down, let the model paint, scale it back up — ruins everything outside the selection and gives you a soft patch inside it. Scumble does the other thing: it cuts a box around your selection, sends only that, and puts the answer back at the document's own resolution. Nothing outside the box is ever touched, because nothing outside the box ever leaves your machine.

The box is not the selection. Around it goes context — the surroundings the model needs to match light, texture and perspective — and Scumble works out how much from the selection's own size: roughly a tenth of its diagonal as the feather, a little more as padding, and never a box smaller than 512 pixels. A tiny selection therefore still goes out as a workable picture instead of a postage stamp. You can override all of it in the Crop panel, and Context is the one worth touching: too little and the model has nothing to match, too much and your selection becomes a detail the model stops caring about.

Then comes the part with the odd name. The box gets sent at the size the chosen model actually takes, and that is usually larger than the box's own pixels. Select a 300-pixel bag in a photo and the crop goes out at 1440 or 2048 or 3840, depending on the model: the model paints far more detail than that area of your picture holds, and the answer is scaled back down into the box. The detail survives the scaling down; it would not have survived being invented at 300 pixels. That is the Highres fix, and it is why an inpaint in a big photo does not come back looking like a blurred sticker.

The Highres fix select in the Generate tab decides how far to push it. Maximum, the default, uses everything the model allows. 2x crop and 4x crop send the box at twice or four times its own resolution, still under the model's ceiling — cheaper, faster, and enough when the selection is already large. Target size keeps the number in the node parameters, and Off sends the crop exactly as it is. The ceiling itself is not a guess: every provider variant carries the size rules of its endpoint, the longest side, the rounding step, the smallest side, a pixel budget and a floor, and a crop steeper than the model's allowed aspect gets more context on its short side rather than being refused.

Coming back, the answer is scaled to the box and blended in, not pasted. Scumble builds a composite mask from your selection — grown by a few pixels, then blurred by the feather — so the patch writes at full strength in the middle, fades out at the edge and does not touch a pixel you did not select. This matters most for the models that take no mask at all: GPT Image, Nano Banana, FLUX.2, Seedream and the rest get the crop and an instruction, they hand back a whole repainted box, and it is this mask that keeps the repaint inside your selection. Then colour match runs if it is on, matching the patch's per-channel mean and spread to the ring of picture around it, and the result lands as a layer at the box's position at full resolution.

On your own ComfyUI none of the size machinery applies: there the Inpaint Canvas node does the cropping and stitching on the server, the recipe's Target size rules, and the app sends the canvas and the mask rather than a finished crop.

Scumble is built to be used with one hand on the keyboard. A tool is one letter, the brush size is two brackets, and the things you do a hundred times a day — undo, deselect, fit the view, generate — are one chord each. Nothing here has to be learned first; the status line under the canvas says what the current tool does.

Two of them are worth knowing before the rest. Hold the backslash key to peek at the picture underneath everything you have added, which is how you judge a result in a second. And press F to fit the picture back into the window when you have zoomed yourself into a corner.

Ctrl+, opens the settings: the ComfyUI server and its authentication, API providers, language models, recipes, helper models, the assistant, plugins, local files, rendering and updates. Most of it you set once.

Updates come from GitHub releases. The app checks, downloads, and shows you the release notes before you restart into the new version. Nothing is installed while you are working.

When something misbehaves: Ctrl+Shift+L opens the log, which is also written to a file. The status line under the canvas carries the last thing that happened, including the reason a run was refused — a missing key, a server that did not answer, a size a provider would not take. And the changelog says what changed in the version you are on, which is often the answer by itself.

Scumble is at 0.1.x and it says so. Not every path has been tested end to end; the API providers in particular are written from their documentation and only some have run against the live service. Keep backups of pictures you care about, and report what breaks in the issues — a bug with a picture and a version number attached is a bug that gets fixed.