Spawn IPFS Daemons, JS or Go

ipfsd-ctl, the IPFS Factory

Spawn IPFS daemons using JavaScript!

Lead Maintainer

Hugo Dias


Version 1.0.0 changed a bit the api and the options methods take so please read the documentation below.

Table of Contents


npm install --save ipfsd-ctl

Please ensure your project also has dependencies on ipfs, ipfs-http-clientand go-ipfs-dep.

npm install --save ipfs
npm install --save ipfs-http-client
npm install --save go-ipfs-dep

If you are only going to use the goimplementation of IPFS, you can skip installing the jsimplementation and vice versa, though both will require the ipfs-http-clientmodule.

If you are only using the proctype in-process IPFS node, you can skip installing go-ipfs-depand ipfs-http-client.


Spawning a single IPFS controller: createController

This is a shorthand for simpler use cases where factory is not needed.

// No need to create a factory when only a single controller is needed.
// Use createController to spawn it instead.
const Ctl = require('ipfsd-ctl')
const ipfsd = await Ctl.createController()
const id = await ipfsd.api.id()


await ipfsd.stop()

Manage multiple IPFS controllers: createFactory

Use a factory to spawn multiple controllers based on some common template.

Spawn an IPFS daemon from Node.js

// Create a factory to spawn two test disposable controllers, get access to an IPFS api
// print node ids and clean all the controllers from the factory.
const Ctl = require('ipfsd-ctl')

const factory = Ctl.createFactory({ type: 'js', test: true, disposable: true })
const ipfsd1 = await factory.spawn() // Spawns using options from `createFactory`
const ipfsd2 = await factory.spawn({ type: 'go' }) // Spawns using options from `createFactory` but overrides `type` to spawn a `go` controller

console.log(await ipfsd1.api.id())
console.log(await ipfsd2.api.id())

await factory.clean() // Clean all the controllers created by the factory calling `stop` on all of them.

Spawn an IPFS daemon from the Browser using the provided remote endpoint

// Start a remote disposable node, and get access to the api
// print the node id, and stop the temporary daemon

const Ctl = require('ipfsd-ctl')

const port = 9090
const server = Ctl.createServer(port)
const factory = Ctl.createFactory({ remote: true, endpoint: `http://localhost:${port}` })

await server.start()
const ipfsd = await factory.spawn()
const id = await ipfsd.api.id()


await ipfsd.stop()
await server.stop()

Disposable vs non Disposable nodes

ipfsd-ctlcan spawn disposableand non-disposablenodes.

  • disposable- Disposable nodes are useful for tests or other temporary use cases, by default they create a temporary repo and automatically initialise and start the node, plus they cleanup everything when stopped.
  • non-disposable- Non disposable nodes will by default attach to any nodes running on the default or the supplied repo. Requires the user to initialize and start the node, as well as stop and cleanup afterwards.


createFactory([options], [overrides])

Creates a factory that can spawn multiple controllers and pre-define options for them.

Returns a Factory


Creates a controller.

Returns Promise<Controller>


Create an Endpoint Server. This server is used by a client node to control a remote node. Example: Spawning a go-ipfs node from a browser.

  • options[Object]Factory options. Defaults to: { port: 43134 }
    • portnumberPort to start the server on.

Returns a Server



Controller[]List of all the controllers spawned.


Create a temporary repo to create controllers manually.

Returns Promise<String>- Path to the repo.


Creates a controller for a IPFS node.

Returns Promise<Controller>


Cleans all controllers spawned.

Returns Promise<Factory>


Class controller for a IPFS node.

new Controller(options)


StringRepo path.


StringExecutable path.


ObjectENV object.


BooleanFlag with the current init state.


BooleanFlag with the current start state.


BooleanFlag with the current clean state.


MultiaddrAPI address


MultiaddrGateway address


ObjectIPFS core interface


Initialises controlled node

Returns Promise<Controller>


Starts controlled node.

Returns Promise<IPFS>


Stops controlled node.

Returns Promise<Controller>


Cleans controlled node, a disposable controller calls this automatically.

Returns Promise<Controller>


Get the pid of the controlled node process if aplicable.

Returns Promise<number>


Get the version of the controlled node.

Returns Promise<string>


Type: [Object]


  • js[ControllerOptions]Pre-defined defaults options for JScontrollers these are deep merged with options passed to Factory.spawn(options).
  • go[ControllerOptions]Pre-defined defaults options for Gocontrollers these are deep merged with options passed to Factory.spawn(options).
  • proc[ControllerOptions]Pre-defined defaults options for Proccontrollers these are deep merged with options passed to Factory.spawn(options).


Type: [Object]


  • test[boolean]Flag to activate custom config for tests.
  • remote[boolean]Use remote endpoint to spawn the nodes. Defaults to truewhen not in node.
  • endpoint[string]Endpoint URL to manage remote Controllers. (Defaults: 'http://localhost:43134').
  • disposable[boolean]A new repo is created and initialized for each invocation, as well as cleaned up automatically once the process exits.
  • type[string]The daemon type, see below the options:
    • go - spawn go-ipfs daemon
    • js - spawn js-ipfs daemon
    • proc - spawn in-process js-ipfs node
  • env[Object]Additional environment variables, passed to executing shell. Only applies for Daemon controllers.
  • args[Array]Custom cli args.
  • ipfsHttpModule[Object]Define the ipfs-http-clientpackage to be used by ctl. Both refand pathshould be specified to make sure all node types (daemon, remote daemon, browser in process node, etc) use the correct version.
    • ipfsHttpModule.ref[Object]Reference to a IPFS HTTP Client object. (defaults to the local require(ipfs-http-client))
    • ipfsHttpModule.path[string]Path to a IPFS HTTP Client to be required. (defaults to the local require.resolve('ipfs-http-client'))
  • ipfsModule[Object]Define the ipfspackage to be used by ctl. Both refand pathshould be specified to make sure all node types (daemon, remote daemon, browser in process node, etc) use the correct version.
    • ipfsModule.ref[Object]Reference to a IPFS API object. (defaults to the local require(ipfs))
    • ipfsModule.path[string]Path to a IPFS API implementation to be required. (defaults to the local require.resolve('ipfs'))
  • ipfsBin[string]Path to a IPFS exectutable . (defaults to the local 'js-ipfs/src/bin/cli.js')
  • ipfsOptions[IpfsOptions]Options for the IPFS instance same as https://github.com/ipfs/js-ipfs#ipfs-constructor. procnodes receive these options as is, daemon nodes translate the options as far as possible to cli arguments.
  • forceKill[boolean]- Whether to use SIGKILL to quit a daemon that does not stop after .stop()is called. (default true)
  • forceKillTimeout[Number]- How long to wait before force killing a daemon in ms. (default 5000)

ipfsd-ctl environment variables

In additional to the API described in previous sections, ipfsd-ctlalso supports several environment variables. This are often very useful when running in different environments, such as CI or when doing integration/interop testing.

Environment variables precedence order is as follows. Top to bottom, top entry has highest precedence:

  • command line options/method arguments
  • env variables
  • default values

Meaning that, environment variables override defaults in the configuration file but are superseded by options to df.spawn({...})


An alternative way of specifying the executable path for the js-ipfsor go-ipfsexecutable, respectively.


Feel free to join in. All welcome. Open an issue!

This repository falls under the IPFS Code of Conduct.









  • redisctl

    redisctl A redis client Build Status(https://camo.githubusercontent.com/ff0ad945c2457bf81b41a2f4b...

    6 个月前
  • nodectl

    supervisor script for node.js nodectl A simple CLI tool for ensuring that a given node.js applica...

    10 个月前
  • node-simctl

    Wrapper around Apple's simctl binary nodesimctl NPM version(http://img.shields.io/npm/v/nodesimct...

    5 个月前
  • lodash.isobjectlike

    The lodash method exported as a module. lodash.isobjectlike v4.0.0 The lodash(https://lodash.com...

    1 年前
  • localStorage - use getItem/setItem functions or access object directly?

    Rishikesh AgrawaniDisgruntledGoat(https://stackoverflow.com/users/6615163/rishikeshagrawani)提出了一个问题:...

    2 年前
  • ioctl

    nodejs ioctl wrapper nodeioctl ========== node ioctl wrapper Installation Install with : API...

    4 个月前
  • fs-read-exactly

    Read exactly n bytes of an fd or file fsreadexactly Read exactly n bytes of an fd or file npm st...

    1 年前
  • dnsctl

    A client for dns Build Status(https://travisci.org/hbouvier/dnsctl.png)(https://travisci.org/hbouvi...

    7 个月前
  • brightnessctl

    Small tool for linux to adjust screen brightness brightnessctl Small tool for linux to adjust scr...

    5 个月前
  • altnctl

    supervisor script for node.js altnctl(formally nodectl) A simple CLI tool for ensuring that a giv...

    1 年前


扫码加入 JavaScript 社区