How do you start a Holochain app with holochain-runner?

Run the binary with the path to a .happ file, optionally followed by a datastore directory that defaults to databases. Pipe the keystore passphrase in on standard input; there is no password flag. When the app interfaces are ready it logs HOLOCHAIN_RUNNER_IS_READY.

Does it handle keys and app installation for you?

Yes. If the keystore holds no private key it generates one on the first run and uses it to install the app. If a datastore directory already holds conductor configuration, it reuses the recorded admin port, app port, app id and DNAs instead of the values you passed.

Where is an example of it used in a real application?

The electron-holochain project documents running it as the Holochain process behind an Electron app through an initAgent call, which returns a status emitter for progress updates and a shutdown function.

Project · developer-tool

holochain-runner

Name: holochain-runner
Author: lightningrodlabs

Gives a binary providing wrapped Holochain Conductor with Status Update events, and a good SIGTERM kill switch

Explore this project All projects

How you run it: not recorded
Holochain version: 0.4.0
Activity: maintained
Checked: 29 October 2026

What is holochain-runner and what is it for?

holochain-runner is a command-line program that starts a Holochain conductor and installs a Holochain app into it for you. It exists so a developer can get an app running from a single command, instead of setting up the conductor, its keystore and the app installation by hand.

holochain-runner is an alternative Holochain conductor binary, maintained in the Lightning Rod Labs organization on GitHub. Its stated purpose is quick startup: instead of running Holochain's conductor, creating a keystore, generating keys, installing an app and adding app interfaces as separate steps, it wraps them into one program you launch from a terminal with the path to a .happ file. It is a piece of infrastructure that other Holochain apps build on rather than an app someone opens.

Point it at a .happ and a datastore directory and it does the setup work. On a first run it creates the datastore directory, generates a private key when the keystore has none, and installs and enables the app; on later runs it reuses the ports, app id and DNAs recorded in the persisted configuration. It reports progress in named stages, from CreatingKeys through InstallingApp to IsReady, and prints HOLOCHAIN_RUNNER_IS_READY once the app interfaces are listening.

One documented use is inside a desktop application: the electron-holochain project bundles the holochain-runner binary to start and stop Holochain alongside an Electron app, exposing status updates and a shutdown call, and the holochain-runner README points to the Acorn Holochain application for an example that also handles the shutdown signal. Start with the repository README for the options and the keystore passphrase convention.

How to get it

From the command line

Get the holochain-runner binary. The project publishes tagged releases on GitHub, and the related electron-holochain project documents downloading a tagged holochain-runner binary from GitHub during npm install.
Run it with the path to your app file: holochain-runner path/to/my-app.happ. An optional second argument sets the datastore directory; it defaults to databases.
Pipe the keystore passphrase in on standard input. The program reads the passphrase from STDIN and does not take it as a flag.
Watch the console. It logs its configuration and progress stages, and prints HOLOCHAIN_RUNNER_IS_READY once the app interfaces are ready.

Source: https://github.com/lightningrodlabs/holochain-runner

Desktop app

Bundle the holochain-runner binary with a desktop application. The electron-holochain project documents this pattern: it downloads a tagged holochain-runner binary from GitHub during npm install and starts it from the app.
Start it through that project's initAgent call, which returns a status emitter for progress updates and a shutdown function; Holochain and the keystore are shut down when the app quits.

Source: https://github.com/lightningrodlabs/electron-holochain

Questions people ask

How do you start a Holochain app with holochain-runner?: Run the binary with the path to a .happ file, optionally followed by a datastore directory that defaults to databases. Pipe the keystore passphrase in on standard input; there is no password flag. When the app interfaces are ready it logs HOLOCHAIN_RUNNER_IS_READY. source
Does it handle keys and app installation for you?: Yes. If the keystore holds no private key it generates one on the first run and uses it to install the app. If a datastore directory already holds conductor configuration, it reuses the recorded admin port, app port, app id and DNAs instead of the values you passed. source
Where is an example of it used in a real application?: The electron-holochain project documents running it as the Holochain process behind an Electron app through an initAgent call, which returns a status emitter for progress updates and a shutdown function. source

From 4 public sources, checked 23 September 2026.

Try holochain-runner

Code on GitHubOpen on GitHub ↗Last change 17 April 2026.
Releasev0.10.1Published 23 January 2025.
The project's own files do not say how it is run.

Details & sources

Source: lightningrodlabs/holochain-runner

Evidence

Release: github.com/lightningrodlabs/holochain-runner/releases/tag/v0.10.1shipped in a release · seen since 20 October 2026 · github.release@1
Last change: api.github.com/repos/lightningrodlabs/holochain-runnerlisted by a third party · seen since 20 October 2026 · github.repository@1
Activity: api.github.com/repos/lightningrodlabs/holochain-runnerlisted by a third party · seen since 20 October 2026 · liveness@1

Compatibility

hdk: 0.4.0 · Cargo.lock @ 1a30c9f
hdi: 0.5.0 · Cargo.lock @ 1a30c9f
holochain-client: —
happ.yaml: absent
web-happ.yaml: absent

Do you maintain holochain-runner?Add your name to this project’s page.

Claim this page