The AI assistant

FolderSkin can generate a skin from a description, in one of two ways:

• The Local Model paints on your own computer, for free. Set it up once (FLUX.2 [klein] 4B, a 4.6 GB download on a Mac and 5.2 GB elsewhere), and it works offline with no key and nothing sent anywhere. It runs on Apple silicon Macs with macOS 14 or later, and on Windows and Linux PCs.
• Bring your own key: you paste an API key from a provider you already have an account with, the key is saved in a private file on your computer, and FolderSkin talks to that provider directly from your machine.

Settings → AI Provider is where you choose. A tick shows the Local Model is set up, or that a provider has a key.

There is no FolderSkin server, no proxy, no bundled key and no free tier to subsidise. With a key, nothing is sent anywhere until you press Generate, and what is sent is the prompt FolderSkin writes from your words, the size the shape needs, and the pictures that go with it: for a whole folder, FolderSkin's own blank template of that folder, and after it any reference pictures you added.

Where the key lives

Encrypted, in FolderSkin's own folder, readable only by your user account:

macOS	~/Library/Application Support/app.folderskin.desktop/keys.json
Windows	%APPDATA%\app.folderskin.desktop\keys.json
Linux	~/.config/app.folderskin.desktop/keys.json

The keys are sealed with AES-256-GCM before they are written. The encryption key is derived (HKDF-SHA256) from a random secret in keys.secret, beside keys.json, and from this computer's hardware id, so keys.json on its own gives nothing away and the two files copied to another computer don't open there: enter the keys again on the new one. Both files are created with owner-only permissions (0600) and written atomically. What no file can do is keep out a program already running as you, which could read both. Only the system keychain could, with the password prompts below.

Why not the system keychain: macOS ties a saved keychain item to the exact signature of the app that saved it. Open-source builds are usually unsigned or ad-hoc signed, so every rebuild or update would read as a different app and ask for your login password again. A password prompt from an app you just downloaded looks like exactly the thing it isn't, so FolderSkin doesn't use the keychain at all.

The key is read at the moment of a request, never included in an error message, and never returned to the app's window. Remove key in the provider dialog deletes it from the file, and deleting keys.json removes them all.

What a picture is for

Every picture is made for a shape. The chip beside the model's name, under the prompt box, shows which one with a small picture of it. Click it, or type @ in the box, to pick another:

• Mac folder: FolderSkin's folder, as Finder shows it.
• Windows folder: the folder Windows draws.
• Linux folder: the folder GNOME and KDE draw.
• A drive: every drive each system shows, from the Mac's startup disk to a Linux USB stick or RAID set, drawn as FolderSkin draws it (DRIVES.md). The picture goes on that drive and with the drive skins in the library.
• Free icon: one thing on its own, such as a mascot, an object or a character, with no folder around it. It goes on any folder as it is.

After @, type part of a name (@win) and press Return or Tab, or click one. The chip changes and the @ word leaves the box. A new chat starts on the drive the folder panel shows, when it shows one, and otherwise on the folder it shows skins on.

The shape belongs to the chat. Each picture is made for the shape that was picked when it was sent, an older chat opens on the shape of its last picture, and the skin is saved as made for that shape. The shape decides the prompt, the template, the size and how the result is cut out, with every provider and with the Local Model.

Just the art or the whole folder

For a folder, this is the choice that matters most, and it is not about quality. A drive has the same choice, as Just the art and Whole drive.

Just the art asks the model for a flat picture in the folder's own proportions (1024 × 960 for the Mac's folder, 1024 × 800 for Windows'), and FolderSkin wraps it onto its own folder, exactly like a photo you add. The geometry is ours, so every skin lines up with every other, at every icon size. Any provider can do this, including the ones with no transparency support. This is the default and the right answer most of the time.

Whole folder asks the model to paint the folder itself, and that image becomes the icon directly, bypassing the compositor. You give up pixel-exact geometry and gain artwork that can sit in real relief and break over the folder's top edge.

When the model can work from a picture (OpenAI, Grok, Gemini and FLUX.2, and the Local Model), FolderSkin sends its own blank template of the folder as the first picture: the folder painted flat light grey, centred on a flat key colour, in the folder's own proportions and at most 1024 pixels on its longer side (Base::blank). The prompt tells the model to repaint that exact folder, keeping its outline, its tab, the parts that make it that folder, its size and its position, and to leave the backdrop as it is. The key colour is never named, because a model told about magenta paints with it. FolderSkin then cuts the painting out along the folder's own outline, so the result keeps FolderSkin's silhouette and keeps the painting's colours right up to its edge. Models rarely keep the backdrop flat: it drifts to a dusty pink that brightens towards a corner, or to a dark grey behind a night scene. So the backdrop is measured as the colour it has at every pixel, from the edge of the frame inward (backdrop.rs), and the painted folder is found against it. The outline counts as kept when paint spills past it, or backdrop shows inside it (which counts twice), on less than half a percent of the folder. Only backdrop as plain as the backdrop itself, reaching in from outside, counts as showing, so a painting that shares the backdrop's colours, like a sunset's clouds, isn't mistaken for it. Where the model's edge sits a few pixels inside FolderSkin's, the backdrop between the two is painted over with the paint beside it. A painting that moved or reshaped the folder is cut out by its key colour instead. Reference pictures you add go after the template, each with the job you gave it, as many as the model takes.

A drive works the same way. Its art is asked for in the shape of its face (a USB stick's label is tall, a Windows drive's top is wide), and its template is the drive with its face in the template's grey and the rest of it, its connector, its strip or its lights, as FolderSkin draws it, so a whole drive keeps them. Its outline is judged only near where the template put the drive, since a narrow drive leaves wide margins where the backdrop can drift.

A Free icon is always painted whole: one subject, complete, in the middle of a square, on a transparent backdrop or on a key colour, and cut out.

How transparency is handled

FolderSkin picks the right route for the model you chose:

• Native alpha. The request asks for a transparent background and the returned PNG already has one. FolderSkin only trims the transparent margin. GPT Image 2.5 Flare and Sunburst work this way.
• No alpha. The prompt asks for the folder alone on a flat key colour. FolderSkin then removes that colour, removes the key that bled into the soft edge (the step that stops a cutout looking like it has a coloured halo), and trims. A missing backdrop is detectable: if the border is not the key colour, the model ignored the instruction, and FolderSkin keeps the picture as artwork for its own folder instead of applying a broken icon. Recraft is also told the colour as a parameter (controls.background_color), so its backdrop comes out flat whatever style you ask for.

The key is magenta, #FF00FF, because it almost never appears in folder art. It is green, #00FF00, for Gemini, which leaves a dark reddish rim around a subject on magenta, and for anything that is meant to be pink or violet, which a magenta cut would eat: the Neon, 70s airbrush, Pop art and Synthwave styles, and any idea that names pink or violet in one of FolderSkin's languages (pink, lilac, rose, rosa, morado, ピンク, 보라, 粉红 and the like). Green does belong in folder art, in every leaf and field, so a green backdrop is only taken away where it reaches the edge of the picture, starting from the shade of green actually painted, and the greens painted on the folder stay (matte::cutout_connected).

Models keep the key clean about half the time. The Local Model often turns it into a lavender or rose studio sweep, with a glow where its light falls and a soft floor, and no colour key can tell that sweep from a white robot lit lavender by it or a grey camera in a fox's paws. So when the key isn't clean, a free icon is lifted off its backdrop by the system instead, where it can: on macOS 14 and later, with Vision's foreground instance mask, the lifting Preview and Photos do (lift.rs). It knows a subject by what it is rather than its colour, and it drops the shadow the model painted under it. Along the lifted edge, the backdrop's share of each pixel is taken back out of its colour (matte::cut_by_mask), so no lavender or pink rim is left.

Where Vision isn't there (Windows, Linux and Macs before macOS 14), FolderSkin lifts the subject itself (crates/folderskin-core/src/segment/), with a graph cut as GrabCut makes one: every pixel is labelled subject or backdrop at the least total cost. Labelling a pixel backdrop is cheap where the backdrop measured from the frame's edge, or the colours learned from it, explain it, and where it is that backdrop darkened by a shadow the frame's edge reaches without crossing an edge. A black beak or a grey camera behind the subject's edge stays with the subject however dark it is. Labelling it subject is cheap where the subject's own colours explain it, and a change of label between neighbours costs what their likeness makes unlikely, so the cut follows the subject's edges. It is made at 384 px while the colours are learned, then the edge is cut again at full size and softened, and matte::cut_by_mask takes it from there. On 26 of the Local Model's pictures it agrees with Vision to within a few pixels of edge, and the same pictures sent as JPEGs down to quality 20 come out the same. A shadow painted on the backdrop, darker than it and no more colourful, goes with the backdrop too, as the grey wash under a watercolour pot does. On a free icon, a neon sign's tubes come off the dark wall they hang on, the wall inside them included: an enclosed stretch of the wall's own colour is the wall showing through, and the glow around it is the wall's. A whole folder is solid, so a night sky painted on one stays. Where no subject stands out from a plain backdrop, a free icon on a flat colour is cut from the edge in, as a green one is.

A whole folder painted on FolderSkin's template takes neither route. It is cut along the template's own outline, as described above. When the model changed the folder's shape, it is lifted off a plain backdrop along its own outline, and only falls back to the key where it can't be.

The keying code is in crates/folderskin-core/src/matte.rs and is unit-tested, including the case of a genuinely pink subject on a magenta backdrop.

Prompts

Your words are never rewritten. crates/folderskin-ai/src/recipe.rs gathers what a picture needs into one recipe: your idea, the shape and what it keeps, the style, any lettering, your pictures and the job each one does, and what goes around the subject. prompts.rs then writes that recipe out the way each family of models reads best, always in the same order: what to paint, how it looks, how it is framed, the pictures, the lettering, and what to leave out.

• OpenAI and Gemini get labelled lines (Style, Composition, Lettering, Constraints), with the pictures called image 1, image 2 and so on.
• Grok gets the same, with the pictures called <IMAGE_0>, <IMAGE_1> as Grok names them.
• FLUX (Black Forest Labs and the Local Model) gets plain prose with the subject first and no instructions about what not to draw, because FLUX has no negative prompt and paints what it is told to avoid. The Local Model's prompt stays inside the 400 tokens its text encoder reads, shortening the style to its medium when it has to.
• Ideogram and Recraft get a short design brief, with the lettering early.
• Stability gets a short list. It and Ideogram get what to leave out as their negative prompt (below).

The parts that do the work are structural rather than stylistic:

• Just-the-art prompts ask for one continuous picture that fills the frame, with the subject large and in the middle, and keep the band the folder's tab hides for sky or texture, because the template crops or curves it away. Windows' and the Linux folder keep their upper-left corner clear too. A drive has no tab, so its art asks only for a little open space around the subject.
• Whole-folder prompts name the folder's parts, back to front, and what stays as it is: the Mac's single tab and its pale paper strip, or the curved step on Windows' folder. Without that, models reliably produce stacked folders and double tabs. A drive is named by its own parts, such as a USB stick's plug, blue body and ring hole.
• Free-icon prompts ask for one complete object, centred and uncropped in a square, with no floor, scenery or frame around it.
• Reference pictures are named by number and job. A subject is kept recognisably the same, a style picture gives its medium, palette, light and texture and none of its content, and a colours picture gives only its colours.
• What to leave out is written for the shape and the style: borders, frames, watermarks and signatures always, text unless you asked for some, the style's own clichés (such as Mount Fuji for a woodblock print) unless your idea asks for them, and clip-art looks for a realistic style.
• None of them state a size. Models don't paint to a pixel count they read, so the size goes in the request's own parameters (below).

Tests assert the load-bearing phrases for every family and every shape, and the recipe is versioned (RECIPE_VERSION) so a skin can say which one made it.

Styles

Type / in the prompt box for thirty styles, in five groups: Photo and 3D, Materials and craft, Painting and drawing, Print, and Digital and graphic. Type part of a name to narrow the list. A style goes in its own slot beside the box, never into your words, so the idea stays word for word and the style is added after it. Click the slot's x to take it off.

Each style is one row of crates/folderskin-ai/src/styles.json, which the app, the command line (folderskin ai styles lists them) and the prompt writer all read. A row has the style's name, a one-line description, the words the prompt uses for it (the medium, then its technique, light, colour and texture, and never a name of an artist), how it letters words, what it tends to add unasked, three checks a result should pass, and each provider's own preset for it where one exists (Stability's style preset, and Ideogram's style preset or style type). Old style names from earlier versions still work: travel is now Travel poster (screenprint), ukiyoe is Woodblock print and diorama is Tilt-shift miniature.

The same menu has Ideas to start from (a subject each, with no style) and Your prompts. The style buttons under a new chat work the same way: each click fills the box with another idea and puts the button's style in the slot.

Lettering

Put the words you want on the skin in quotes: a fox reading a map, with the word "ESCAPE". FolderSkin letters exactly what is quoted, spelled out letter by letter for the models that read instructions, once, in the style's own lettering, placed for the shape: across the middle of the front panel for a folder, and on the object or beneath it for a free icon. Without quotes, the prompt asks for no text at all. Keep it to one or two short words, because long text still comes out garbled.

Your prompts

Save as a prompt, in the / menu, keeps what is in the box, with its style, under a name you give it. It is listed under Your prompts from then on: pick it and the box and the style slot fill in again. Typing a name that is taken replaces that prompt, after saying so. The x beside one of yours removes it, with Undo for a few seconds after.

Saved prompts are kept in skills.json, beside the skins folder (ARCHITECTURE.md says where that is), as skills in the folderskin.skill/1 format that crates/folderskin-ai/src/skill.rs describes. A skill keeps what a picture shows (idea) apart from how it looks (base_style, or its own treatment, palette and light), so one saved look can go with any idea. Every skill is checked before it is written: it needs a name of up to 60 characters and something to save, its style must be one FolderSkin has, its own treatment is 8 to 60 words and tells the model what to do rather than what not to, and the whole skill fits in 4 KB. A prompt that names someone as its style ("in the style of" a name, or "by" one) is saved after a word, because describing the technique works better.

Reference pictures

A picture added to a prompt is used for its Subject unless you say otherwise. Click its chip to make it the Style (a look to match, taking none of what it shows) or the Colours (its palette and nothing else). The pictures go to the model in that order, after the template, and the prompt names each one by number and job.

What each provider is sent

crates/folderskin-ai/src/request.rs builds every request exactly as its provider's API reference documents it, checked against the provider's own SDK where it has one, and its tests check each one field by field. A test in crates/folderskin-ai/tests/providers.rs also sends every request to a stand-in server on your computer that answers the way the provider's documentation says, so the method, the address, the key's header, the content type and every field are checked on the wire.

Settings go in each provider's own parameters, never in the words. The size is the shape's (1024 × 960 for the Mac's artwork, 1024 × 800 for Windows', a whole folder in its own shape and a free icon square), sent exactly where a provider takes any size and as the nearest size or aspect ratio it offers where it doesn't:

Provider	Request	Size	Also sent
OpenAI	JSON to images/generations, or a form with each picture as image[] to images/edits	exact, on a 16-pixel grid (1024 × 960)	quality: high for Flare, max for Sunburst, medium for GPT Image 2, so the price is known beforehand
xAI Grok	JSON only, pictures included as data URLs (image, or images for several)	nearest aspect_ratio, or the template's own frame
Google Gemini	JSON to generateContent	generationConfig.imageConfig: 1K, nearest aspectRatio, or the template's frame	responseModalities: ["IMAGE"]
Black Forest Labs	JSON, pictures as input_image, input_image_2 and so on	exact, within one megapixel (FLUX.2 bills by the started megapixel)	prompt rewriting off (disable_pup, or prompt_upsampling: false on flex)
Recraft	JSON	the nearest size in V4.1's list	PNG output, and the key colour as controls.background_color
Stability AI	a form	nearest aspect_ratio	a negative prompt, and a style preset when the style has one
Ideogram	a form	the nearest of 3.0's resolutions (1024 × 960)	Magic Prompt off, a negative prompt, and a style type or preset

The negative prompt keeps out text (unless lettering is asked for), watermarks and signatures, plus whatever the chosen style tends to add. OpenAI, Gemini and Grok have no negative prompt, so their prompt says the same in words.

Models that were taken out

A choice saved while a model was on offer moves to the model that took its place, and a skin keeps the name of the model that made it.

Was	Now	Why
OpenAI GPT Image 1	GPT Image 2	OpenAI shuts it down on 23 October 2026
Gemini 2.5 Flash Image	Gemini 3.1 Flash Image	Google shuts it down on 2 October 2026
FLUX 1.1 Pro	FLUX.2 pro	the previous generation, which took no pictures
Recraft V3	Recraft V4.1	the previous generation, whose prompts stop at 1,000 characters, fewer than FolderSkin's own instructions take

Ideogram 4.0 isn't offered yet: it rewrites every prompt written as words, and FolderSkin keeps the idea exactly as you wrote it.

Cost

Every request is billed to your own account by your provider. The Generate view shows the model's rough price before you press the button, taken from the provider's pricing page at the settings FolderSkin sends. A whole folder costs a little more on the providers that bill for the pictures they are sent as well (xAI, Black Forest Labs). Details, under each picture, shows what the provider said the request cost (xAI, Black Forest Labs, Recraft) or used (OpenAI, Gemini).

FolderSkin makes exactly one request per press and never retries on its own. That holds when a provider finishes without a picture, too, as Gemini sometimes does (NO_IMAGE): the chat says so and offers Try again, and only your press sends the request again.

Building and cross-compiling

The provider layer uses rustls for TLS, whose crypto backend (aws-lc-sys) compiles C. That builds cleanly on each platform's own CI runner, which is how FolderSkin's releases are made. Cross-compiling it from one desktop to another (for example cargo check --target x86_64-pc-windows-msvc on a Mac) needs a C cross-toolchain for the target and will otherwise fail in aws-lc-sys's build script. The rest of the workspace cross-checks without one.

Failure messages you may see

Message	What happened
"add your … API key first"	No key saved for that provider
"that key was rejected by …"	The provider turned the key down
"… is rate limiting you right now"	429, so wait and try again
"… finished without painting a picture"	The provider answered without a picture and without saying why (Gemini's NO_IMAGE), so try again or reword the idea
"… declined that prompt: its filter blocked the picture"	The provider's safety filter stopped the prompt or the picture, such as Stability's blurred picture or Ideogram's safety check, so reword it
"… said: … (error 400)"	The provider's own words, shown as they came. Worth reporting if it names a field FolderSkin sent
"the model drew a scene instead of a folder on a plain backdrop"	Whole-folder mode with no keyable background, so try again or switch to Just the art. The app keeps such a picture as artwork for its own folder, or for the drive it was painted for, and a free icon as the square picture it is, and says so.
"the provider returned something that is not an image"	A malformed or non-image response

Folders made in a chat assistant

You can also paint a whole folder in ChatGPT, Grok or any other chat assistant and bring it in with Add your photo. Ask for the folder on a solid #FF00FF background, or on a transparent one. FolderSkin recognises either and uses the picture as the icon as it is, cut out and trimmed, instead of wrapping it in its own folder a second time. Any other picture is treated as artwork for the template. ARCHITECTURE.md has the exact rules, including why a photo of something on magenta paper stays a picture.

Keeping a generated skin

Every generated skin is saved the moment it arrives, like an imported picture, together with the provider, the model, your prompt and the shape it was made for. It is in the gallery under Yours after a restart, and deleting it there removes it from disk. ARCHITECTURE.md says where the files live. If the write fails (a full disk, say), the skin stays for the rest of the session rather than being lost.

It also keeps what it was made from, under recipe in the skins' index, so a result can be traced to its prompt and made again: the prompt exactly as it was sent, the negative prompt for the providers that take one, the style, the words it letters, each picture's job and a hash of it, the template and its version (mac-folder/1), the key colour, and the recipe's version.

The chat keeps its words and pictures while you look at other views, including a picture that is still being made, and a new one starts when FolderSkin opens again. Earlier chats are in the chat list, each on the shape it was for.

To share generated skins with everyone, put them in a community pack: tag them and use Share with community in the app, or turn a folder of saved renders into a pack with folderskin-tools packs make. PACKS.md has both, and SKINS.md says how a picture lands on the folder.