# Agregore Browser: a minimal browser built around protocol handlers

> Agregore Browser is an Electron browser whose distinguishing feature is that unusual addresses are first class: hyper and dat links open directly, IPFS and IPNS paths convert, SSB sigils and magnet links are rewritten, and the extensions ship in the box. It is deliberately small, and the AGPL licence and an Electron codebase define its limits.

**AgregoreWeb/agregore-browser** — A minimal browser for the distributed web (Desktop version)

- Repository: https://github.com/AgregoreWeb/agregore-browser
- Website: https://www.youtube.com/watch?v=TnYKvOQB0ts&list=PL7sG5SCUNyeYx8wnfMOUpsh7rM_g0w_cu&index=14
- Stars: 925 · Forks: 95
- Language: JavaScript
- License: AGPL-3.0
- Published: 2026-10-20 · Updated: 2026-10-20 · Language: en
- Canonical page: https://hysenlabs.com/projects/agregoreweb-agregore-browser

## Unusual addresses are the feature, not an add-on

Agregore Browser is described as a minimal web browser for the distributed web, and the repository topics name the protocols it cares about: ipfs, hypercore-protocol, p2p, ssb and decentralization.

What that means concretely is in the feature list. The browser auto-converts SSB sigils, BitTorrent magnet links, /ipfs/Qm paths and /ipns/ paths to proper URLs. So a page that links to an immutable content identifier opens, without a gateway, without a local IPFS daemon configured by hand and without a URL rewriting service in the middle.

The build configuration registers this as operating system level protocol handling rather than a web application convention. The package.json declares file associations for html, md and gemini files, so those documents open in Agregore as viewers, and a protocols entry registers hypercore-protocol with the schemes hyper and dat. The same configuration names the product Agregore Browser with the app id agregore.mauve.moe, which is the identifier the operating system uses when it hands a link to this browser.

That is the architectural commitment. Most browsers treat an ipfs address as a string they do not understand, and the user reaches for a gateway. Agregore treats it as a URL, the same way a browser treats https. The cost of that choice is that you are running a full Chromium based browser to get one protocol handler, which is where the project's own minimalism argument comes in.

## Minimal by design, and the OS takes the rest

The Goals section states the design in five lines: enable people to make and use local first apps using the web, be minimal with fewer built-in features and leave more to the OS, be open to anything p2p, decentralized or local-first, rely on web extensions for extra functionality, and work with mesh networks and Bluetooth Low Energy networks.

Read the second goal as the key to the whole project. A conventional browser is a large application that reimplements things the operating system already does. Agregore inverts that and treats the OS as the provider of the surrounding features, keeping the browser itself to the page rendering and the protocol handling.

The keyboard shortcut table makes the same point. Alt shows the menu bar, F11 is fullscreen, Ctrl+M minimizes, Ctrl+W closes, Ctrl+F is find in page, and Ctrl+Shift+I opens devtools. The configurable ones are the ones that touch navigation and behaviour: new window, forward, back, focus URL bar, reload, hard reload, plus two entries for learning more and opening the extensions folder, and Ctrl+. to edit the config file. The config file is .agregorerc, and one documented property is autoHideMenuBar, which decides whether the menu bar is visible by default.

What is missing is as informative as what is there. There is no built-in bookmark manager, no password manager, no tab strip in the usual sense, and history is managed through a File menu entry rather than a dedicated interface. URL autocomplete comes from history, which is the browser's memory rather than a separate profile system.

## Extensions carry the features Agregore does not

Because the project relies on web extensions for extra functionality, and because it bundles a set of them, the extension list is where the user-visible features actually live.

Shipped in the box are a Markdown, Gemini and JSON rendering extension, a QR code scanner and generator, the uBlock Origin ad blocker, and support for creating web archives via the ArchiveWeb.page project. The QR extension generates a code for the current page, scans a code from the browser action window, and generates a code for a link or image when you right click it. The archive support means a page can be turned into a self-contained web archive rather than a bookmark that will rot.

There is also a local and cloud LLM hook that goes beyond a normal extension API. The README describes using local and cloud LLMs through window.llm.chat({messages}) and window.llm.complete("prompt"). That is a deliberate page-level API: a page, or an extension, can call a model without the browser exposing a general chat interface.

The extension list also has to be maintained. The package.json includes a postinstall hook that runs the postversion script and the download-extensions script, and the README gives the command to fetch the latest versions of ArchiveWeb.page or UBlock Origin yourself:

```bash
npm run download-extensions
```

That arrangement means the browser pulls extension binaries at install time rather than vendoring them in the repository, which keeps the tree small but means a build depends on those upstream downloads succeeding.

## Building it from source with Electron

The README documents the development path in a fixed sequence. You need node.js, at least Node 18, and git, plus Node-gyp and its dependencies for your operating system, because the build compiles native modules. You fork the repository, pull your fork to your machine, load the submodules, install the dependencies and start the browser:

```bash
git submodule update --init --recursive
npm install
npm start
```

When you are ready to submit, you run the lint check, which the README ties to the StandardJS code style, either with standard --fix or with npm run lint. To debug extensions, npm run debug opens devtools for their background pages.

The npm scripts are short and readable. The start script is electron ., the debug script is env NODE_ENV=debug electron --trace-uncaught ., and the test script is npm run lint, which means the test suite is a style check rather than a unit test suite. The builder scripts use electron-builder, with builder running a plain build with --publish never and builder-all adding the -mwl flags for the macOS, Windows and Linux targets. The electron-builder configuration disables npm rebuild and packs the application as an asar archive, unpacking src, node_modules and the icon files.

The build output directory is named release. There is also a rebuild.sh and a .gitmodules file at the top of the tree, which is consistent with the submodule step in the instructions, and an update-versions.js script that the postversion hook runs to keep the extension versions in the tree in step with the downloads.

## A slower maintenance rhythm than the releases suggest

The release list shows v2.24.0 on 2026-04-23, v2.23.1 on 2026-04-03 and v2.23.0 on 2026-03-13. The release titles are informative in the way small project changelogs usually are: 2.23.1 forces dark or light mode in settings, 2.23.0 added DID protocol handlers with small fixes and ARM Linux support, and 2.24.0 reworked the renderer and the download page.

So the project is shipping small, specific changes across a handful of platforms, which is the rhythm of a mature side project rather than a company product.

The maintenance record needs stating carefully. The repository is not archived, and the last push was on 2026-07-13. That is more than three months ago but within six months, and it is later than the most recent tagged release. In other words, work is landing on master after the April release, with no tag to point at yet.

For a browser, the maintenance question is sharper than for a library, because an Electron application inherits the security posture of its Chromium base, and a browser that falls behind on that base has known problems. The README does not say how the Chromium version is tracked, and the repository does not publish a release for every change. Anyone deploying Agregore in front of sensitive data should check what Chromium version the build it installs actually carries rather than assume it tracks current Electron.

## AGPL-3.0 sets the ceiling on commercial reuse

The licence field on the repository says AGPL-3.0, and the LICENSE file sits at the top of the tree.

That is the most consequential single fact for anyone considering the project beyond personal use. The GNU Affero General Public License is copyleft that reaches network use: if you modify the program and let other users interact with it over a network, you must offer them the corresponding source of your modified version. For a distributed web browser whose whole point is that people run their own instance and connect to each other, the AGPL is not an accident of licensing, it is a deliberate choice that keeps forks in the open.

For an individual running the released build, the licence asks nothing of you. For a company that wants to embed Agregore in a product, or to run a modified version as a service, the obligation to publish the modified source is real and needs review by whoever owns licensing in your organisation. That is not legal advice, it is the reason to read the licence before planning around the project.

The project is also, by its own account, deliberately open to anything p2p, decentralized or local-first, and it aims to work over mesh networks and Bluetooth Low Energy. Those goals and the AGPL terms point the same way: the browser is meant to be forked, and the licence is what keeps the forks honest.

## Conclusion

Agregore Browser suits a developer or a privacy-minded user who wants to open content addressed over IPFS, Hypercore and SSB without setting up a gateway, and who is willing to accept an Electron application rather than a native one. It does not suit a general audience that wants built-in tabs, downloads management, bookmarks and a password manager, since the project states that it is minimal and leaves more to the operating system, and it does not suit a commercial product that cannot accept the AGPL-3.0 obligations. Before adopting, install the released build from the GitHub releases page, enable the protocol handlers for your operating system, and confirm the applications you need are available as web extensions.

## FAQ

### What is Agregore Browser and which protocols does it support?

Agregore Browser is a minimal Electron browser for the distributed web. It auto-converts SSB sigils, BitTorrent magnet links, /ipfs/Qm paths and /ipns/ paths to proper URLs, and the build registers the hypercore-protocol handler with the hyper and dat schemes.

### How do I build Agregore Browser from source?

You need node.js at version 18 or later, git and Node-gyp for your operating system. Then load the submodules with git submodule update --init --recursive, run npm install, and start the browser with npm start. The lint check is npm run lint, and npm run debug opens devtools for extension background pages.

### Which extensions ship with Agregore Browser?

The README lists a built-in Markdown, Gemini and JSON rendering extension, a QR code scanner and generator, the uBlock Origin ad blocker, and built-in support for creating web archives via the ArchiveWeb.page project. The package.json postinstall hook downloads the extensions, and npm run download-extensions fetches the latest versions.

### Can I use a local or cloud model from a page in Agregore?

Yes. The README describes using local and cloud LLMs through window.llm.chat({messages}) and window.llm.complete("prompt"), which is a page level API rather than a built-in chat interface.

### What licence does Agregore Browser use?

The licence field on the repository says AGPL-3.0. That is the copyleft licence with the network use clause, so a modified version offered to users over a network has to carry its corresponding source, which matters for anyone embedding it in a product.

## Sources

- [AgregoreWeb/agregore-browser on GitHub](https://github.com/AgregoreWeb/agregore-browser)
- [License: AGPL-3.0](https://github.com/AgregoreWeb/agregore-browser/blob/master/LICENSE)
- [Project website](https://www.youtube.com/watch?v=TnYKvOQB0ts&list=PL7sG5SCUNyeYx8wnfMOUpsh7rM_g0w_cu&index=14)
- [README](https://github.com/AgregoreWeb/agregore-browser/blob/master/README.md)
- [Releases](https://github.com/AgregoreWeb/agregore-browser/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/agregoreweb-agregore-browser