Chris Hager
Programming, Technology & More

How to run a private network of the NEO blockchain

Please take a look at the updated post here:

Also, make sure to check out

Running a private network of the NEO blockchain is an integral part of working with the blockchain, in particular for writing and testing dApps and smart contracts. A private network is a complete NEO blockchain for yourself, isolated from the public networks. You can spin it up quickly, claim the initial 100 million NEO, and experiment with all aspects of it.

This post is a step-by-step guide on setting up a private chain with Docker and Python on Mac and Linux and Windows, and an introduction to neo-python and neo-privatenet-docker.

Note for Windows users: neo-python does not currently support Windows, because LevelDB only works on OSX and Linux. You can still run the private network with the Docker container, but to create wallets and extract NEO and GAS you’ll need to follow the official NEO private chain docs beginning with step 5.

NEO itself and the native tooling is primarily developed with C# using Windows. The official NEO documentation on private chains gives a good overview how to setup a private network with a Windows toolchain and 4 Windows virtual machines as consensus nodes.

Thanks to the monumental efforts of the City of Zion community (CoZ), running a private chain is possible on any platform with Docker and Python, with minimal system requirements. The two specific projects we are going to use are neo-python and neo-privatenet-docker:

At this point I also want to mention neo-js, a NEO node implementation in JavaScript, with several features in the pipeline. neo-js is not quite as mature as neo-python, but already supports all RPC calls, and you can run a full local node, saving the blockchain data into a MongoDB database.


Setting up a private NEO chain, step-by-step

The steps are the following: Docker setup → neo-privatenet-dockerneo-python → connect to the private net and create a wallet → claim the initial 100,000,000 NEO:

At this point you now have a private NEO chain up and running and full control over the initial funds. Happy hacking!

How to claim an initial GAS


How to restart and reset the private network

The Docker container does not persist any state. If it stops or restarts, all state is lost and the whole blockchain will be newly created at the next start.

It’s important to remove the old chain files from neo-python (Chains/privnet), else you’ll run into problems running the old database against another chain.

neo-python$ rm -rf Chains/privnet/

You can manually restart the private-net container by running ./ This stops the neo-privnet container if it is running, and starts a fresh one:

$ ./
Stopping container named neo-privnet
Removing container named neo-privnet
Starting container...

Docker Tips & Tricks

Here are a few often-used Docker commands:




neo-python is an amazing project, a community effort to re-implement the original C# NEO project in Python! It has come a long way and already supports the following functionality:

neo-python has been forked from a “very” preliminary Python SDK, but development really started in July 2017, with constant contributions since then:

As of November 3, 2017, neo-python has 18 contributors, and is spearheaded by localhuman.

If you want to work with the NEO blockchain on a platform other than Windows, you’ll most certainly interact with neo-python in one way or the other. It’s an integral part of the cross-platform development toolchain, actively developed, and just overall a great project.

I just want to send a big thank-you to all the individuals who contributed to making this possible! ♥️ I’m excited about the bright future of this project and it’s further development.



Let’s take a closer look at neo-privatenet-docker, which allows us to easily run a private NEO blockchain within an Ubuntu Docker image. A private chain requires at least 4 consensus nodes, which are all running inside this single Docker container. The main contributors are hal0x2328 and phetter.

Let’s start with the Dockerfile:

FROM ubuntu:16.04
MAINTAINER hal0x2328

ENV DEBIAN_FRONTEND noninteractive

RUN apt-get update && apt-get upgrade -y
RUN apt-get install -y apt-utils
RUN apt-get install -y mininet netcat curl wget unzip less python screen
RUN apt-get install -y ca-certificates apt-transport-https
RUN apt-get install -y libleveldb-dev sqlite3 libsqlite3-dev
RUN apt-get install -y expect

RUN curl | gpg --dearmor > /etc/apt/trusted.gpg.d/microsoft.gpg
RUN echo "deb [arch=amd64] xenial main" > /etc/apt/sources.list.d/dotnetdev.list

RUN apt-get update && apt-get install -y dotnet-sdk-2.0.0

RUN wget -O /opt/

That’s pretty much the whole setup. After this, neo-cli is extracted 4 times (once for each consensus node), and the private chain startup files are copied:

RUN unzip -d /opt/node1 /opt/
RUN unzip -d /opt/node2 /opt/
RUN unzip -d /opt/node3 /opt/
RUN unzip -d /opt/node4 /opt/

ADD ./scripts/ /opt/
ADD ./scripts/ /opt/

When you run the Docker container with, it starts the container with 4 open ports (20333-20336, mapped to the host), and invokes the script:

docker run -d --name neo-privnet -p 20333-20336:20333-20336/tcp -h neo-privnet neo-privnet /bin/bash /opt/ /opt/ in turn starts 4 NEO nodes by executing four times:

#!/usr/bin/expect -f
set dnpath [lindex $argv 0]
set wallet [lindex $argv 1]
set password [lindex $argv 2]
set timeout -1
cd $dnpath
spawn dotnet neo-cli.dll
expect "neo>"
send "open wallet $wallet\n"
expect "password:"
send "$password\n"
expect "neo>"
send "start consensus\n"
expect "OnStart"

This code sets a few variables from the arguments (dnpath, wallet, password), runs dotnet neo-cli.dll, opens the initial node wallet and calls start consensus in order for the nodes to start working. At this point, blocks in the private chain are being created.

That’s pretty much it! And even though it doesn’t look like much code, it’s a life-saver for getting started with NEO blockchain development and running a private chain, because it makes it just so easy and accessible. Again a big thank-you to the developers driving this project!

I would suggest that you try it out right now! Just follow the getting started guide above and you will have your own private NEO chain running in no time.


If you have feedback or comments, please reach out to me via @metachris.