# Understand node types in IPFS Companion

There are four available node types in IPFS Companion:

  1. External
  2. Embedded
  3. Embedded + chrome.sockets
  4. Public

Screenshot of node type switch

When in doubt, use the External node type running on your localhost. Some options for doing so:

  • Use the IPFS Desktop GUI app (for Windows/Linux/Mac), which installs and manages a local IPFS node for you
  • If you prefer a more hands-on approach:
  • If you are using Brave, feel you may want to experiment with embedded + chrome.sockets (see below); you can always switch back to External with local IPFS Desktop

# External

An external node can be any instance of an IPFS daemon that runs outside of a web browser process and exposes Gateway and writable API over HTTP at TCP ports.

At this time, the go-ipfs daemon is the preferred implementation. It is easier on CPU, and provides dhtclient mode, which
decreases ambient bandwidth use and smaller battery drain (key characteristics of something that is expected to run in the background all the time).

A good practice is to run it on localhost (, as it provides:

  • Increased security (native IPFS used as end-to-end transport)
  • Better UX in the browser (no mixed-content warnings)
  • Improved performance (local loopback is used, no network overhead)

Don't know where to start? See the command line quick-start guide.

# Embedded

An embedded node is a js-ipfs instance running in the browser (in-memory), without the need for any external software. It is a work in progress, but can be used for development and experimentation (e.g. for testing a dApp that uses window.ipfs without having to install and start up your own IPFS daemon).

Power users can provide custom config (e.g. to enable experimental pubsub) via the IPFS Companion Preferences

Note: At present, embedded js-ipfs running within webextension (browser context) comes with some limitations:

  • Can't act as an HTTP gateway (extension uses public one as a fallback)
  • Known to be CPU-hungry
    (#450, ipfs/js-ipfs#1190) over time, which may drain your battery
  • Missing DHT (js-ipfs/#856)
  • Default transports limited to websockets (js-ipfs/#1088)
  • An embedded node does not run when external node is selected.; every time you switch back to the embedded node, a new instance is created on-demand, and it can take a few seconds for a brand new node to find peers

When in doubt, run go-ipfs as an external node instead.

# Embedded + chrome.sockets

This node type replaces the regular embedded type if the browser vendor grants us access to chrome.sockets APIs. These powerful APIs enable embedded js-ipfs to provide a true p2p experience without the need for an external daemon:

# HTTP gateway

  • Access IPFS resources over HTTP without relying on a public gateway
  • Automatically pick a free localhost port

# TCP transport

  • Embedded js-ipfs is able to connect to go-ipfs
  • go-ipfs is able to connect to embedded js-ipfs

# Local discovery (mDNS/DNS-SD)

  • Embedded node discovers go-ipfs in the LAN and automatically connects to it

Note: This is still a work in progress. see Embedded JS-IPFS in Brave for the current status.

# Public

A public node is not a part of the toggle UI. It is used as an implicit fallback for its gateway functionality when an external node is offline or an embedded node is used. It does not expose the API port.