ipfs/ipfs-companion

IPFS Companion Browser Extension

Use IPFS directly in your browser

---

Maintenance

[!NOTE] This browser extension is currently maintained by the Shipyard team.

Table of contents

• About IPFS Companion
• Features
• Install
• Contribute
• Help & Troubleshooting
• Privacy & Licenses

About IPFS Companion

IPFS Companion connects your browser to your local IPFS Kubo node (either through the IPFS Desktop app or the command-line daemon), running inside your Chromium-based or Firefox browser, with support for ipfs:// addresses, redirecting content-addressed websites and file paths to your local Gateway, easy IPFS file import and sharing, and more.

IPFS is a peer-to-peer hypermedia protocol designed to make the web faster, safer, more resilient, and more open. It enables completely distributed sites and applications that don’t rely on centralized hosting and stay true to the original vision of an open, flat web. Visit the IPFS Project website to learn more.

IPFS Companion features

Automatically detect and redirect IPFS resources

Detect URLs with IPFS paths

IPFS Companion detects requests for IPFS-like paths (such as /ipfs/{cid} or /ipns/{peerid_or_host-with-dnslink}) on any website. If a path is a valid IPFS address, it is redirected to load from your local gateway. The gateway at localhost will also automatically switch to a subdomain gateway to provide a unique origin for each website:

[!NOTE] Path gateway redirect flow:

• Step 1: Public gateway URL detected
  • https://ipfs.io/ipfs/QmbWqxBEKC3P8tqsKc98xmWNzrzDtRLMiMPL8wBuTGsMnR
• Step 2: Redirect to local gateway
  • http://localhost:8080/ipfs/QmbWqxBEKC3P8tqsKc98xmWNzrzDtRLMiMPL8wBuTGsMnR
• Step 3: Automatic upgrade to subdomain with origin isolation
  • http://bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi.ipfs.localhost:8080

[!NOTE] Subdomain gateway redirect flow:

• Step 1: Subdomain gateway URL detected
  • https://bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi.ipfs.dweb.link
• Step 2: Redirect to local subdomain with origin isolation
  • http://bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi.ipfs.localhost:8080

Detect DNSLink-enabled URLs

IPFS Companion detects DNSLink info in the DNS records of websites. If a site uses DNSLink (a few examples are https://docs.ipfs.tech, https://ipld.io, and http://tr.wikipedia-on-ipfs.org), IPFS Companion redirects the HTTP request to your local gateway:

[!NOTE] DNSLink redirect flow:

• Step 1: DNSLink-enabled website detected
  • http://docs.ipfs.tech
• Step 2: Redirect to local gateway
  • http://localhost:8080/ipns/docs.ipfs.tech
• Step 3: Automatic upgrade to subdomain with origin isolation
  • http://docs.ipfs.tech.ipns.localhost:8080/

Efficient DNSLink detection

DNSLink lookups run in the background and are cached, so they don't slow down your browsing. The first time you open a DNSLink website, IPFS Companion upgrades the tab to your local gateway as soon as the record resolves, with no manual refresh. You can turn detection off under "Detect DNSLink Websites" in Preferences. Learn more.

Toggle redirects globally or per site

You can disable and re-enable local gateway redirects by several means:

• Suspend redirects globally in IPFS Companion's preferences
• Suspend redirects per site using the toggle under "Current tab" (illustrated below) or in IPFS Companion's preferences
• Add x-ipfs-companion-no-redirect to the URL as a query parameter (example). You can turn this opt-out off under "Honor ?x-ipfs-companion-no-redirect opt-out" in Preferences.

Access frequently-used IPFS actions from your browser bar

IPFS Companion enables you to quickly and easily access common actions from your browser bar with just a few clicks:

• The cube icon in your browser bar shows your live peer count for quick reference.
• Check your IPFS API and gateway status by clicking the cube icon to reveal the main menu
• Right-click images and other page assets to easily add them to IPFS (including the option to preserve file names)
• Choose the Import option in the main menu for quick drag-and-drop import from a browser tab
• Pin or unpin IPFS resources (via API) directly from the main menu
• Copy shareable public gateway links, IPFS content paths, or CIDs of IPFS resources directly from the main menu
• Launch the IPFS Web UI dashboard from the main menu with a single click
• Toggle gateway redirects or switch all IPFS Companion features on/off quickly and easily from the main menu (illustrations below)

Toggle gateway redirects on a per-website basis

You can toggle redirects for an individual website under the Current Tab section of the main menu. If that site uses DNSLink, toggling off will restore the site's original URL, too.

Switch all IPFS Companion features on/off

To temporarily suspend all IPFS integrations (redirects, API status content scripts, protocol handlers, etc.), use the on/off button at the top of the IPFS Companion menu.

Experiments

IPFS Companion ships with a variety of experimental features. Some are disabled by default, so be sure to check out IPFS Companion's Preferences to see them all.

• Make plaintext IPFS links clickable (demo)
• Re-route requests made via the following experimental protocols to an HTTP gateway (public or custom):
  • ipfs://$cid
  • ipns://$cid_or_fqdn

Install IPFS Companion

Latest stable release

Important! Make sure you have IPFS installed on your computer as well. IPFS Companion requires a local IPFS Kubo node running on your computer to function properly.

It's also possible to grab vendor-specific packages for each release, but these builds are not signed, nor will they automatically update. .zip bundles are meant only to be manually loaded via chrome://extensions (Chromium) or about:debugging (Firefox) for smoke-testing.

Development

To work on IPFS Companion's code, you'll need to install it from source. Quick steps are below, but see the full developer notes for more detailed instructions and tips.

1. Clone https://github.com/ipfs/ipfs-companion.git
2. Run this all-in-one dev build to install dependencies, build, and launch in the browser of your choice:
   • Chromium

     $ npm run dev-build chromium
     

   • Firefox

     $ npm run dev-build firefox    # firefox:nightly works too!
     

Contribute

Contributions are welcome.

• Check out the contribution guide for how to get started as a developer
• Open an issue
• Make sure you read and abide by the IPFS Code of Conduct

Release Process

The release process has been documented here.

Help & troubleshooting

Ask a question

[!TIP] The best place to ask about IPFS Companion (or IPFS in general!) is in the official IPFS Forums, where you can search past discussions for others who may have had the same questions, too.

Common troubleshooting steps

These frequently encountered troubleshooting situations may be helpful:

• Import via right-click does not work in Firefox: See this workaround.
• HTTP-to-HTTPS redirects fail when using Ghostery: Ghostery is known to interfere with HTTP-to-HTTPS redirects, which in some setups breaks websites utilizing public gateways (more details). Until this is fixed upstream, a workaround is to allowlist affected sites.
• NoScript breaks IPFS Companion: By default, NoScript breaks IPFS Companion by blocking assets loaded from an IPFS gateway running on localhost. To fix this, extend the SYSTEM ruleset and prepend it with IPFS whitelist (feel free to modify this, but get familiar with ABE rule syntax first):

# Enable IPFS redirect to LOCAL
Site ^http://127.0.0.1:8080/(ipfs|ipns)*
Anonymize

# Prevent Internet sites from requesting LAN resources.
Site LOCAL
Accept from LOCAL
Deny

Privacy & license info

• IPFS Companion Privacy policy
• The IPFS logo belongs to the IPFS Project and is licensed under a CC-BY-SA 3.0 license
• is-ipfs, js-multihash, and other npm dependencies are under MIT license, unless stated otherwise
• IPFS Companion itself is released under CC0; to the extent possible under law, the author has waived all copyright and related or neighboring rights to this work, effectively placing it in the public domain