nukebg

KO | EN

gitlite — search

#javascript #python #hacktoberfest #react #ai #typescript #llm #go #golang #android #machine-learning #rust #deep-learning #linux

★ 21 Open GitHub ↗

Nuke backgrounds from any image. 100% client-side, zero uploads.

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# NUKEBG

> Nuke backgrounds from any image. 100% client-side. Zero uploads. Zero BS.

[![Version](https://img.shields.io/badge/version-2.12.0-brightgreen.svg)](https://github.com/yocreoquesi/nukebg/releases)
[![License: GPL-3.0](https://img.shields.io/badge/License-GPL%20v3-blue.svg)](https://www.gnu.org/licenses/gpl-3.0)
[![Client-Side](https://img.shields.io/badge/Processing-100%25%20Client--Side-green.svg)](https://raw.githubusercontent.com/yocreoquesi/nukebg/main/)

[Use NukeBG](https://nukebg.app) | [GitHub](https://github.com/yocreoquesi/nukebg) | [Reactor — costs & runtime](https://nukebg.app/#reactor)

---

## > what_is_this

```
$ nukebg --explain

Background removal tools are everywhere. Most of them suck at AI-generated images:
painted checkerboard patterns, baked-in watermarks, fake transparency.

NukeBG handles all of it. In your browser. On your device.
No uploads. No accounts. No tracking. Nothing leaves your machine.

Drop. Nuke. Download. That's it.
```

## > features

```
[+] ML BACKGROUND REMOVAL       RMBG-1.4 for segmentation with auto-classification.
                                  Photos, signatures, icons. Each optimized.

[+] CHECKERBOARD OBLITERATION    Detects and classifies painted checkerboard backgrounds.
                                  Any grid size, any generator.

[+] WATERMARK REMOVAL            Auto-detects Gemini sparkle + DALL-E color bar watermarks.
                                  Telea FMM reconstruction -- no blurry patches.

[+] 100% CLIENT-SIDE             Zero server uploads. Your images NEVER leave your device.
                                  First load fetches the ML model (HuggingFace) and the
                                  ONNX runtime (jsDelivr) once, then cached — no pixels
                                  go anywhere. Verify it yourself in DevTools.

[+] OFFLINE MODE                 After first visit, app + model weights are cached.
                                  Process images without internet.

[+] TERMINAL THEME               JetBrains Mono, CRT effects, easter eggs everywhere.
                                  Slider with 4 visual modes. Type 'help' in the prompt.

[+] i18n                         EN, ES, FR, DE, PT, ZH. Auto-detects browser language.

[+] OPEN SOURCE (GPL-3.0)        Audit the code. Fork it. Improve it.
```

## > quick_start

**Use it now at [nukebg.app](https://nukebg.app) -- no install needed.**

```
$ open https://nukebg.app
```

**Run locally (Node):**

```bash
$ git clone https://github.com/yocreoquesi/nukebg.git
$ cd nukebg
$ npm install
$ npm run dev        # dev server at localhost:5173
$ npm test           # run tests
$ npm run build      # production build -> dist/
```

**Run locally (Docker):**

Mirrors the production setup — multi-stage build, nginx alpine, same CSP and
security headers as the deployed site. Useful to validate nginx config before
shipping, or to self-host.

```bash
$ git clone https://github.com/yocreoquesi/nukebg.git
$ cd nukebg
$ docker compose up -d --build    # build + run detached
$ open http://localhost:8080      # -> nukebg served via nginx
$ docker compose logs -f          # follow logs
$ docker compose down             # stop and remove
```

No environment variables needed — NukeBG is 100% client-side, no server
config, no secrets, no database. The container serves static assets with
nginx on port 8080 (mapped 1:1 on the host). Change the left side of
`"8080:8080"` in `docker-compose.yml` to publish on a different host port.

The image is built as the non-root `nukebg` user and exposes only port 8080.
Includes an HTTP healthcheck (`wget --spider` every 30s).

Deploy `dist/` to any static host: Cloudflare Pages, GitHub Pages, Netlify, Vercel.

## > how_it_works

```
  INPUT (PNG, JPG, WebP)
    |
    v
  [1. CLASSIFY + SCAN] ---------- auto-detect content type + background (CV, instant)
    |                              PHOTO / SIGNATURE / ICON
    |
    +-- SIGNATURE? -------------> [CV threshold] Otsu + Sauvola (<50ms) --> DONE
    |
    +-- ICON? ------------------> [RMBG threshold 0.3] skip watermark --> DONE
    |
    +-- PHOTO? -----------------> continue
    |
    v
  [2. WATERMARK DETECTION] ------ Gemini sparkle + DALL-E color bar (CV, instant)
    |
    +-- Watermark found? -------> [3. INPAINT] Telea FMM reconstruction (CV, instant)
    +-- No watermark? ----------> skip
    |
    v
  [4. BACKGROUND REMOVAL] ------- RMBG-1.4 segmentation (ML)
    |                              WebGPU/WASM via Transformers.js
    v
  CLEAN RGBA PNG w/ REAL TRANSPARENCY
```

The ML model is lazy-loaded on first use, then cached by the Service Worker for offline access.

## > monorepo_map

This repo is an npm workspaces monorepo with three packages:

| Package | Path | What it is | Published? |
| --- | --- | --- | --- |
| `nukebg-app` | [`packages/nukebg-app`](packages/nukebg-app) | The browser app described above — Vite + Web Components, deployed to [nukebg.app](https://nukebg.app). | No (`private`) |
| `nukebg-core` | [`packages/nukebg-core`](packages/nukebg-core) | Runtime-agnostic CV/ML pipeline. Zero runtime dependencies. Used by both other packages. | Yes — [`nukebg-core` README](packages/nukebg-core/README.md) |
| `nukebg-cli` | [`packages/nukebg-cli`](packages/nukebg-cli) | Node CLI for background removal from the terminal/CI. | Yes — [`nukebg-cli` README](packages/nukebg-cli/README.md) |

**Want the CLI?** Read the [`nukebg-cli` README](packages/nukebg-cli/README.md) —
it covers install, every flag, exit codes, and the RMBG-1.4 license gate
(CC-BY-NC-4.0, non-commercial use only).

**Want to embed background removal in your own Node app?** Read the
[`nukebg-core` README](packages/nukebg-core/README.md) for the public API and
a programmatic embedding example.

Everything below this section documents the browser app (`nukebg-app`).

## > tech_stack

| Layer      | Technology                                                       |
| ---------- | ---------------------------------------------------------------- |
| Language   | Vanilla TypeScript (no framework)                                |
| UI         | Web Components (`<ar-dropzone>`, `<ar-viewer>`, `<ar-progress>`) |
| Build      | Vite 6                                                           |
| Testing    | Vitest                                                           |
| ML Runtime | Transformers.js (ONNX Runtime Web)                               |
| ML Models  | RMBG-1.4 INT8 (~45MB)                                            |
| GPU        | WASM (WebGPU reserved for future)                                |
| Processing | Canvas API + OffscreenCanvas in Web Workers                      |
| Caching    | Service Worker + Cache API                                       |
| Styling    | Custom CSS (JetBrains Mono, zero dependencies)                   |
| i18n       | Lightweight custom system (EN/ES/FR/DE/PT/ZH)                    |

## > privacy

```
$ nukebg --privacy

NO server processing.    All image editing happens locally in Web Workers.
NO uploads.              Images never leave your device.
NO cookies.              Nothing is collected.
NO tracking.             No analytics. No telemetry.
NO accounts.             No sign-up required.
OFFLINE capable.         Works without internet after first visit.
OPEN SOURCE.             Don't trust us -- verify.

What actually goes over the network (first load only, then cached):
  - briaai/RMBG-1.4 weights from huggingface.co
  - onnxruntime-web WASM runtime from cdn.jsdelivr.net (needed for LaMa inpainting)
  - opencv/inpainting_lama weights from huggingface.co (first watermark inpaint only)
Open DevTools > Network while you process an image: the only requests
you should see after the first warmup are the initial page load.
```

## > comparison

| Feature                             | NukeBG        | remove.bg         | backgroundless.io | Photoshop   |
| ----------------------------------- | ------------- | ----------------- | ----------------- | ----------- |
| ML background removal (RMBG-1.4)    | Yes           | Yes (proprietary) | Yes               | Yes         |
| Auto content-type detection         | Yes           | No                | No                | No          |
| Checkerboard detection              | Yes           | No                | No                | Manual      |
| Watermark removal (Gemini + DALL-E) | Yes           | No                | No                | Manual      |
| Client-side (private)               | Yes           | No                | Yes               | N/A         |
| Free and unlimited                  | Yes           | No (credits)      | Yes               | No ($22/mo) |
| Open source                         | Yes (GPL-3.0) | No                | No                | No          |
| Works offline                       | Yes           | No                | No                | Yes         |

## > license_compliance

NukeBG itself is GPL-3.0 (see [LICENSE](LICENSE)), but it ships with third-party
artifacts whose licenses carry independent obligations:

| Component                                         | License                                                                        | Notes                                                                                                                                                                                                                                                                                                             |
| ------------------------------------------------- | ------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| RMBG-1.4 ML model (BRIA AI)                       | [bria-rmbg-1.4 license](https://huggingface.co/briaai/RMBG-1.4) — CC-BY-NC-4.0 | **Non-commercial use only**. Commercial deployments — paid products, paid APIs, paid SaaS, ad-supported products — require a commercial agreement with BRIA AI, or swapping to a different model. The GPL-3.0 license of NukeBG's code does not override this. Donations to cover hosting / maintenance are fine. |
| MobileSAM ML models (Acly/MobileSAM)              | [MIT](https://huggingface.co/Acly/MobileSAM)                                   | Used by the advanced editor for interactive click-to-segment. Commercial use OK. Encoder + decoder fetched from Hugging Face at runtime; not bundled.                                                                                                                                                             |
| LaMa inpainting ML model (opencv/inpainting_lama) | [Apache-2.0](https://huggingface.co/opencv/inpainting_lama)                    | Used by the watermark-removal pipeline for content-aware reconstruction. Commercial use OK. Single FP32 ONNX (~95 MB) fetched from Hugging Face at runtime; not bundled.                                                                                                                                          |
| JetBrains Mono font                               | [SIL Open Font License 1.1](public/fonts/OFL.txt)                              | Bundled self-hosted. Attribution preserved in `public/fonts/OFL.txt`.                                                                                                                                                                                                                                             |
| Transformers.js, ONNX Runtime Web                 | Apache-2.0 / MIT                                                               | Compatible.                                                                                                                                                                                                                                                                                                       |

If you fork NukeBG and host it commercially, you are responsible for complying
with the RMBG-1.4 model license. The project does not bundle the model weights —
they are fetched at runtime from Hugging Face — but that does not change the
downstream obligation.

## > contributing

```
$ cat CONTRIBUTING.md
```

Contributions welcome. Read the [Contributing Guide](CONTRIBUTING.md) before submitting a PR.

[Report Bug](https://github.com/yocreoquesi/nukebg/issues/new?template=bug_report.md) | [Request Feature](https://github.com/yocreoquesi/nukebg/issues/new?template=feature_request.md)

## > support

If NukeBG saves you time, consider keeping the reactor running:

[![Sponsor on GitHub](https://img.shields.io/badge/Sponsor-GitHub%20Sponsors-ea4aaa?logo=github-sponsors&logoColor=white&style=for-the-badge)](https://github.com/sponsors/yocreoquesi)

[![Ko-fi](https://ko-fi.com/img/githubbutton_sm.svg)](https://ko-fi.com/yocreoquesi)

See where the time and money go: [/#reactor](https://nukebg.app/#reactor) — public sunk-cost + monthly burn breakdown.

---

**Built for creators who are done dealing with garbage backgrounds. Open source forever.**

_Built with the assistance of AI agents ([Claude](https://www.anthropic.com/claude) by Anthropic)._

nukebg

오늘의 추천 프로젝트

Was this content helpful?

Recent Feedback

nukebg

오늘의 추천 프로젝트

Was this content helpful?

Recent Feedback

Download README