ipfs-companion: the browser extension that reroutes the web through your own Kubo node

Why a browser extension sits between you and the public gateway

IPFS Companion connects your browser to your local IPFS Kubo node, whether that node is the IPFS Desktop app or the command-line daemon, and runs inside Chromium-based browsers and Firefox. Its stated features include support for `ipfs://` addresses, redirecting content-addressed websites and file paths to your local Gateway, and file import and sharing.

That redirect is the whole point, and it is worth being precise about what it saves. Content addressed data is identified by its CID, so a `https://ipfs.io/ipfs/QmSomeCid` URL is a lookup of that CID on somebody else's machine. Fetching from your own node means the request either comes from your machine or is answered by a peer your node already talks to. Neither path goes through a gateway operator's logs. Neither path breaks when that gateway goes down.

What you give up in exchange is the network. A page you load locally may depend on things the extension cannot see, such as a script fetched from a public CDN, and a locally resolved site fails entirely when your node is not running. The extension's badge exists because of that dependency: the state of your node is visible at a glance, and v3.3.0 specifically fixed cases where Chrome's dormant service worker left a stale online indicator on screen while the node was actually offline.

Three redirect flows the README spells out step by step

The documentation is unusually concrete here, with three named flows, each given as a numbered sequence of URLs. Reading them tells you more about the design than any feature bullet would.

The first is a path gateway. A public URL such as `https://ipfs.io/ipfs/QmbWqxBEKC3P8tqsKc98xmWNzrzDtRLMiMPL8wBuTGsMnR` is detected anywhere on the web, because the extension looks for IPFS-like paths such as `/ipfs/{cid}` or `/ipns/{peerid_or_host-with-dnslink}` on any website. If the path is a valid IPFS address, it redirects to `http://localhost:8080/ipfs/QmbWqxBEKC3P8tqsKc98xmWNzrzDtRLMiMPL8wBuTGsMnR`.

Then both flows upgrade to a subdomain. The `localhost` gateway automatically switches to a subdomain gateway, so that same address becomes `http://bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi.ipfs.localhost:8080`. The README gives the reason: a unique origin for each website. Without that step every site you visit would share one origin at `localhost:8080`, and web storage and cookies would leak between unrelated sites. The same three step shape applies when a subdomain gateway URL is already the input, with `https://bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi.ipfs.dweb.link` going straight to the local subdomain.

The third flow is DNSLink, where the signal is in DNS rather than in the URL. The extension detects DNSLink info in a site's DNS records, and the README names `docs.ipfs.tech`, `ipld.io` and `tr.wikipedia-on-ipfs.org` as examples. So `http://docs.ipfs.tech` becomes `http://localhost:8080/ipns/docs.ipfs.tech`, then `http://docs.ipfs.tech.ipns.localhost:8080/`. A human-readable name, resolved through IPNS instead of a CID, ending up with the same origin isolation guarantee.

DNSLink lookups, offline behaviour and what changed in v3.3.0

Doing a DNS lookup on every navigation would be a bad trade, and the README addresses performance head on: DNSLink lookups run in the background and are cached so they do not slow down browsing. v3.3.0, published on 2025-09-27, made that mechanism cheaper and more private in two specific ways.

It deduplicated concurrent lookups for the same domain, cutting redundant requests from two to four down to one. Multiple tabs or frames resolving the same name at the same moment no longer each pay for the lookup. And it removed the fallback that leaked browsing patterns. Previously, when your local node was not running, DNSLink lookups would fall back to `ipfs.io`, which meant an external service saw which names you were trying to resolve. The release notes say the extension now detects offline status and skips external lookups entirely, keeping your DNS browsing patterns inside the resolvers configured in your local IPFS node. For a tool whose entire argument is that you do not want a third party watching, that fallback was the kind of detail that undermines the premise, and removing it was the right call.

The same release fixed a browser rather than a protocol problem. Chrome and Edge park service workers when idle, which left the extension unable to update its badge or node status. The fix uses Chrome's alarms API for hybrid polling, so status updates stay reliable without draining battery. If you have run this extension in Chrome and seen it claim a node was online when it was not, that is the bug this release addressed.

Broken ipfs addresses stop at an explainer instead of forwarding

The v3.4.0 release, published on 2026-07-21, is the one with a visible behaviour change for users, and it comes from issue #1380.

Some `ipfs://` addresses were never going to resolve. A website name belongs under `ipns://`, not `ipfs://`. A `Qm...` CID that has been lowercased is no longer the same CID, since the encoding is case sensitive. A typo is a typo. The old behaviour was to rewrite or forward them silently, and the result was that broken links kept spreading, because nothing ever told the person who clicked one that the address itself was malformed.

Now each broken address stops on a page that says what is wrong and, where it can, offers one click to the corrected address. Valid addresses are untouched, in any CID base or IPNS form. This is a small change with a disproportionate effect on how bad links spread through chat apps and social posts, and it is the kind of fix that only matters because someone filed a specific issue about it rather than discovering it in the abstract.

The release notes also carry the project's forward-looking news, and it is not good news for planning purposes. v3.4.0 is described as the last Kubo release with new features from the Shipyard team. Their IPFS work ends on 2026-09-30, after which security and bug fix releases ship only if any are needed, and after that date no one at Shipyard maintains the extension. The notes point readers to an announcement and ask that transition questions be sent before the end of September.

A maintenance notice that belongs in any adoption decision

The Maintenance section of the README is the most consequential text in the repository, and it is placed before the table of contents rather than buried near the end.

It says there is no dedicated maintainer at the moment. After the Protocol Labs nucleation, the Shipyard team maintained this project across 2024, 2025 and 2026, and Shipyard's IPFS maintenance work ended on 2026-09-30. Support and transition questions are directed to the community forum at `discuss.ipfs.tech` rather than to an issue tracker or a maintainer address.

The repository metadata tells a consistent story. The last push to the default branch was on 2026-09-28, the repository is not archived, and 138 issues are open. Those facts together describe a project that is alive in the sense that commits still land and issues still exist, and that has no owner in the sense that nobody is paid or designated to keep shipping features. The distinction matters more than a star count, and the README does not pretend otherwise.

There is precedent for how this plays out in the IPFS ecosystem, though not a comfortable one: the v3.4.0 notes describe Shipyard's IPFS work as ending, and the same team shipped the last feature release of an extension that had been their responsibility for years. If you are standardising this extension across a team, the realistic questions are whether your Kubo gateway behaviour depends on anything Shipyard-specific, and who takes over when a security fix is needed after the maintenance window closes.

How the extension is built, bundled and tested

The build setup is the part of the repository that tells you what kind of engineering this is. `package.json` names the project `ipfs-companion`, sets version 3.4.0, declares `CC0-1.0`, marks the module as ESM with `type: module`, and lists Marcin Rataj as lead maintainer in the package metadata.

Bundling runs through rspack, with `build:js:rspack` invoking `rspack build --mode production`. The build is split into two platform bundles, `bundle:chromium` and `bundle:firefox`, each of which first merges a manifest for its target and then runs `web-ext build`. A separate `build:minimize-dist` step removes `add-on/dist/lib` and `add-on/dist/contentScripts` from the packaged output, so unused build artefacts do not ship to the store. Task orchestration uses `run-s` for sequential scripts and `run-p` for parallel ones, which is the usual pattern for this kind of multi stage build, and `shx` provides the cross platform file operations.

Tests are split across two runners. `vitest.config.js` sits at the root for unit level work, while `playwright.config.js` and `docker-compose.e2e.yml` together indicate end-to-end tests that run against real browser binaries in containers. That arrangement is expensive and it is the right call for an extension whose core behaviour is a redirect the test harness cannot easily simulate, since the whole product is what the browser does with a URL. The v3.2.0 release notes reference updated end-to-end tests to match the refactoring in that release, which suggests the suite is maintained rather than left to rot.

Release tooling is `release-please` with a manifest and a config file, so version bumps and changelog entries are derived from commit messages rather than edited by hand. Translation work goes through a Transifex configuration in `.tx/`, with a localization notes document linked from the README badges. The tree also carries `AGENTS.md`, `PRIVACY-POLICY.md` and `SECURITY.md`, and the development container is defined by a `Dockerfile` that pins a specific Node.js image and installs dependencies as a non-root user:

FROM node:22.19.0
RUN npm run ci:install
ENV PATH="/home/node/app/node_modules/.bin:${PATH}"

The privacy posture is consistent with the v3.2.0 release, which removed telemetry collection outright in PR #1327, replacing telemetry functions with no-ops that only log debug messages.

Editorial conclusion

ipfs-companion is a small idea executed for years: sit in the browser, notice when a page is really an IPFS address, and load it from `localhost` instead of a gateway you do not control. The redirect flows in the README show the design carrying its weight, since path gateways, subdomain gateways and DNSLink names all converge on a subdomain form that gives each site its own origin. The v3.4.0 change is the one to know about, because broken `ipfs://` addresses now stop on a page explaining what is wrong instead of being rewritten and forwarded, which ends a quiet source of dead links that spread through chat and social posts. What weighs against all of this is the maintenance notice at the top of the README. There is no dedicated maintainer, the Shipyard team that carried the work through 2024, 2025 and 2026 ended its IPFS maintenance on 2026-09-30, and the release notes for v3.4.0 call it the last one with new features, promising only security and bug fixes after that date. Transition questions are pointed at the community forum. If you are deciding whether to standardise on this extension inside a team, that notice matters more than the feature list.

Frequently asked questions

Official sources

1. ipfs/ipfs-companion on GitHub
2. License: CC0-1.0
3. Project website
4. README
5. Releases