Skip to content
A package and protocol for a global, dispersed sensor network
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.


A decentralized pubsub messaging platform built on IPFS and libp2p


Nomad is a decentralized system for subscribing to, processing, and publishing data in the form of ordered message streams. Nomad is decentralized: there are no message brokers through which messages pass. Nomad uses IPFS to create a peer-to-peer network of nodes that routes messages from publisher to subscriber. Streams are published by nodes which are identified by a public key hash, making Nomad a permissionless system. Anyone can create a new node, subscribe to existing streams, and publish a stream without signing up for any proprietary service.

Why Nomad?

Data is a beautiful thing, but it's too hard to share live data, to process data and share real time insights, or to connect visualizations to live data. Nomad draws from the likes of stream processing systems like Apache Kafka but adds decentralization to create a global system of durable but lightweight data pipes that anyone can build on top of.

Get Started


Nomad uses IPFS under the hood. Head to the IPFS distributions page here and download the binary for your platform.

After downloading, untar the archive and run the included

> tar xvfz go-ipfs.tar.gz
> cd go-ipfs
> ./

Test that IPFS installed successfully:

> ipfs help
  ipfs - Global p2p merkle-dag filesystem.

Install the Nomad npm module:

(If you don't have Node.js, install it first.)

npm install --save nomad-stream

Write some code to subscribe to a stream

Subscribe to an existing nomad stream and log its messages to the console:

const Nomad = require('nomad-stream')
const nomad = new Nomad()

nomad.subscribe(['QmP2akn...'], function(message) {

The string QmP2akn... is the unique id of a publishing Nomad node to which this node is subscribing. The id is the hash of the public key of the node.

Save your code as subscribe.js

Start subscribing

Start IPFS:

> ipfs daemon

In a new terminal window, start subscribing:

> node subscribe.js

It may take a minute or more before you see any messages.


You just created your first node! What's next? Browse the docs for the complete API. Create a node that publishes something interesting to the world.


Not seeing any messages? Make sure you started IPFS:

ipfs daemon

Still having trouble? Kill Node.js, turn on verbose logging, and try again:

> export DEBUG="nomad*"
> node subscribe.js

Full API


Require module and create a new instance:

const Nomad = require('nomad-stream')
const nomad = new Nomad()


Subscribe to one or more nodes' streams:

nomad.subscribe(array, callback)

array is an array of node ids to subscribe to. callback is called once when a new message arrives for any subscribed stream. Callback is passed a single argument which is an object:

{id, link, message}

id is the node id of the node that published the message, link is the hash of the IPFS IPLD object that contains the message data, message is the message string.

Unsubscribe to a node's stream:



Prepare a node to publish:

nomad.prepareToPublish().then(function(n) {
  const nomadInstance = n

Returns a promise that resolves to an instance object used to publish messages.

Publish a root message:


Publishes a root message to subscribers, which is the first message in the stream of messages. The first time a node is run, publish root must be called once before publish is called. Published messages must be a string. To published structured data, data needs to be stringified first using JSON.stringify. Returns a promise.

Publish a message to subscribers:


Publishes a message to subscribers. As with publishRoot the message must be a string. Returns a promise.

Node identity

A running node's id comes from the running instance of ipfs started via ipfs daemon. A new identity can be created by either deleting an existing IPFS repo or setting IPFS_PATH and running ipfs init again. For details see the IPFS command line docs.


Nomad is alpha software and depends on IPFS which is also alpha software. Things may break at any time. Nomad does not currently include features that support node fault tolerance, but they're in the works!


Feel free to dive in! Open an issue or submit PRs.


MIT (c) IDEO CoLab

You can’t perform that action at this time.