node package manager



Hyperdrive is a secure, real time distributed file system

npm install hyperdrive


Hyperdrive aims to implement the same API as Node.js' core fs module.

var hyperdrive = require('hyperdrive')
var archive = hyperdrive('./my-first-hyperdrive') // content will be stored in this folder
archive.writeFile('/hello.txt', 'world', function (err) {
  if (err) throw err
  archive.readdir('/', function (err, list) {
    if (err) throw err
    console.log(list) // prints ['hello.txt']
    archive.readFile('/hello.txt', 'utf-8', function (err, data) {
      if (err) throw err
      console.log(data) // prints 'world'

A big difference is that you can replicate the file system to other computers! All you need is a stream.

var net = require('net')
// ... on one machine
var server = net.createServer(function (socket) {
// ... on another
var clonedArchive = hyperdrive('./my-cloned-hyperdrive', origKey)
var socket = net.connect(10000)

It also comes with build in versioning and real time replication. See more below.


var archive = hyperdrive(storage, [key], [options])

Create a new hyperdrive. Storage should be a function or a string.

If storage is a string content will be stored inside that folder.

If storage is a function it is called with a string name for each abstract-random-access instance that is needed to store the archive.

Options include:

  sparse: true // only download data when it is read first time

var stream = archive.replicate([options])

Replicate this archive. Options include

  live: false, // keep replicating
  download: true, // download data from peers?
  upload: true // upload data to peers?


Get the current version of the archive (incrementing number).


The public key identifying the archive.


A key derived from the public key that can be used to discovery other peers sharing this archive.


A boolean indicating whether the archive is writable.


Emitted when the archive is fully ready and all properties has been populated.

archive.on('error', err)

Emitted when a critical error during load happened.

var oldDrive = archive.checkout(version)

Checkout a readonly copy of the archive at an old version.

var stream = archive.history([options])

Get a stream of all changes and their versions from this archive.

var stream = archive.createReadStream(name, [options])

Read a file out as a stream. Similar to fs.createReadStream.

Options include:

  start: optionalByteOffset, // similar to fs
  end: optionalInclusiveByteEndOffset, // similar to fs
  length: optionalByteLength

archive.readFile(name, [encoding], callback)

Read an entire file into memory. Similar to fs.readFile.

var stream = archive.createWriteStream(name, [options])

Write a file as a stream. Similar to fs.createWriteStream.

archive.writeFile(name, buffer, [options], [callback])

Write a file from a single buffer. Similar to fs.writeFile.

archive.unlink(name, [callback])

Unlinks (deletes) a file. Similar to fs.unlink.

archive.mkdir(name, [options], [callback])

Explictly create an directory. Similar to fs.mkdir

archive.rmdir(name, [callback])

Delete an empty directory. Similar to fs.rmdir.

archive.readdir(name, [options], [callback])

Lists a directory. Similar to fs.readdir.

Options include:

    cached: true|false, // default: false

If cached is set to true, this function returns results from the local version of the archive’s append-tree. Default behavior is to fetch the latest remote version of the archive before returning list of directories.

archive.stat(name, callback)

Stat an entry. Similar to fs.stat. Sample output:

Stat {
  dev: 0,
  nlink: 1,
  rdev: 0,
  blksize: 0,
  ino: 0,
  mode: 16877,
  uid: 0,
  gid: 0,
  size: 0,
  offset: 0,
  blocks: 0,
  atime: 2017-04-10T18:59:00.147Z,
  mtime: 2017-04-10T18:59:00.147Z,
  ctime: 2017-04-10T18:59:00.147Z,
  linkname: undefined }

The output object includes methods similar to fs.stat:

var stat = archive.stat('/hello.txt')

archive.lstat(name, callback)

Stat an entry but do not follow symlinks. Similar to fs.lstat.

archive.access(name, callback)

Similar to fs.access.


Closes all open resources used by the archive. The archive should no longer be used after calling this.