IconForge

Icons on demand for humans and the AI coding agents building beside them. Describe it, get an on-brand, transparent PNG, generated and durably stored on Backblaze B2 in seconds.

Comment

IconForge

Inspiration

AI coding tools have changed how software gets built.

Platforms like Lovable now help people create thousands of new applications every day. An idea can become a working product in minutes. AI can write the frontend, connect a database, create an API, and deploy the application.

But there is one part of the process that still feels surprisingly limited.

The moment an AI agent needs an icon, it has to search through an existing library.

That is why so many AI built products use the same icons. Different applications, different audiences, and different brands still end up sharing the same small set of symbols.

The problem is not that icon libraries are bad. The problem is that they were designed for selection, not creation.

AI can build a completely original product, but it cannot create the visual assets that give that product its identity.

We built IconForge to change that.

Our goal was to give both people and AI coding agents the ability to create original, brand specific icons whenever they need them.

What it does

IconForge generates custom icons for a specific product and brand.

Users can create a project and define its visual system, including its color palette, personality, style, and design rules. Every icon generated inside that project follows the same brand direction automatically.

This means users are not simply recoloring a stock icon. Each asset is created for the product from the beginning.

Icons are generated on a clean background so they can be processed by a dedicated machine learning segmentation pipeline. The background is removed and the result is delivered as a transparent PNG with clean edges.

Every generated asset is stored immediately in Backblaze B2. This includes the original image, transparent versions, thumbnails, exports, and provenance information.

IconForge is also designed for AI coding agents.

Through the IconForge MCP server, an agent can search a project’s existing icon library, retrieve an asset, or generate a completely new icon using a single tool call.

An agent building an application no longer has to stop, search through a generic icon library, and settle for something close enough. It can request the exact asset the product needs.

How we built it

The IconForge frontend is built with React 18, Vite, and TypeScript.

The backend uses FastAPI, SQLAlchemy, and Python 3.12. Image generation and background removal run through a background job queue so longer tasks do not block normal API requests.

Google Gemini is the primary image generation engine. Gemini requests are routed through a Genblaze Pipeline using the official genblaze-google provider.

Using Genblaze as the main generation path gives each asset a structured provenance manifest. The manifest records information such as the model, provider, prompt, and asset hashes.

Genblaze also connects IconForge to models hosted by GMI Cloud, including FLUX Kontext Pro and Seedream. Qwen through DashScope provides another fallback option.

If the Genblaze pipeline cannot complete a request, IconForge automatically falls back to a direct provider call. The user does not need to restart the generation or switch providers manually.

For background removal, we use real machine learning segmentation models rather than removing a single background color. The pipeline supports rembg with U² Net, BiRefNet, and ISNet, along with multiple processing stages and edge refinement.

Every asset is uploaded to Backblaze B2 through a small boto3 storage layer.

The B2 bucket is private. Files are never exposed through permanent public links. Every download, including assets returned through the MCP server, uses a temporary presigned URL.

The MCP server is built with Node and TypeScript. We also created a forge command line tool that can install IconForge into Claude Code, Codex CLI, Claude Desktop, and Cursor.

The application is deployed using Google Cloud Run, with Cloud SQL for PostgreSQL.

How we use Backblaze B2

Backblaze B2 is the storage foundation of IconForge.

As soon as an icon is generated, the original image, thumbnail, and provenance manifest are uploaded to B2. Transparent versions, exports, and usage logs follow the same process.

This keeps generated assets separate from temporary application storage and ensures they remain available even when Cloud Run instances scale down.

Because the bucket is private, every file is accessed through a temporary presigned URL. This applies to both human users and AI agents using the MCP server.

B2 allows IconForge to treat generated icons as permanent product assets rather than temporary model outputs.

How we use Genblaze

Genblaze is the main orchestration layer for image generation.

Every Gemini generation is first attempted through a Genblaze Pipeline using GeminiImageProvider. This wraps the normal Gemini generation process while also creating a structured, tamper evident provenance record.

That provenance record is stored in Backblaze B2 beside the image it describes.

Genblaze also powers our alternate generation path through GMI Cloud. This gives users access to models such as FLUX Kontext Pro and Seedream without changing the rest of the IconForge workflow.

Using Genblaze allows us to support multiple providers while keeping generation results and provenance information consistent.

Challenges we ran into

One challenge was resolving a dependency conflict between genblaze-google and the version of google-genai already used by IconForge.

The Genblaze provider required google-genai version 1, while our project had resolved to version 2.

We pinned the dependency to a compatible version and tested it against a real installation. We verified that the API methods we rely on, including generate_content, generate_images, and GenerateContentConfig, still worked correctly.

We also discovered an issue in the Genblaze failure path.

When a generation step failed, the asset list was empty. Our code still tried to access the first asset, which produced a generic IndexError. That error hid the actual cause of the failure, such as a rate limit, provider error, or content policy response.

We fixed this by checking the Genblaze step status and error before reading the asset list. The original provider error is now preserved and easier to diagnose.

Another issue involved provenance serialization.

Genblaze manifests contain datetime values. A normal model_dump() call kept those values as Python objects, which caused JSON serialization to fail later in the generation process.

The image itself had already been created, but the serialization failure caused the full job to be marked as unsuccessful.

We fixed the issue by using model_dump(mode="json").

We found both of these problems through live generation testing rather than code review.

We also discovered that the first account created on a new database was automatically given administrator access. This could have accidentally given a judge account access to shared credentials.

We corrected the account setup process before sharing the project.

Accomplishments that we are proud of

We are especially proud that Genblaze is not a secondary integration.

Our primary Gemini generation flow runs through a real Genblaze Pipeline. Every successful generation creates a genuine provenance record that is stored alongside the final asset.

We are also proud that IconForge is useful to both humans and AI agents.

A designer can create and manage a branded icon library through the web application. An AI coding agent can use that same library through MCP without needing access to the server’s local filesystem.

The agent can search, generate, and retrieve an icon without leaving its development workflow.

Most importantly, IconForge turns icons from something an AI agent can only choose into something it can actually create.

What we learned

We learned that the reliability of an AI generation pipeline depends heavily on what happens when something goes wrong.

The most important bugs we found did not happen during successful generations. They appeared when providers failed, returned incomplete results, or produced data that could not be serialized.

We also learned that asset generation is only one part of the problem.

A useful system also needs consistent branding, secure storage, transparent file output, provenance, and a practical way for development agents to access the result.

Creating the image is only the beginning. The real value comes from making that image usable inside the product being built.

What is next for IconForge

Our next step is to connect the deterministic quality scoring system to the Gemini Vision review flow that already exists in the codebase.

This will allow IconForge to evaluate generated icons automatically and reject results that do not meet the project’s visual or technical standards.

We also plan to turn Genblaze provenance manifests into a full asset history view. Users will be able to see how an icon was created, which provider and model generated it, and which processing steps were applied afterward.

Finally, we want to expand IconForge with organization support so teams can share brand systems, icon libraries, permissions, and generation history.

The long term goal is simple.

AI should not only be able to build the product.

It should be able to create the visual identity that makes the product recognizable.

Built With

Share this project:

Updates