Running a test net node

This guide will walk you through the process of setting up your node to join Symbol’s public test network.

The test network mirrors the same technology and features of the future main public network. You can use the test net to experiment with the offered Symbol’s transaction set in a live network without the loss of valuable assets.


The network might be offline or replaced without notice because it is used extensively for testing purposes. To work in a private environment network, install a local network for learning and development purposes.

Hardware requirements

Symbol nodes have been tested on computers with the following minimum requirements.

  • CPU: 2 cores or more
  • Memory: 4GB or more
  • HD: 20GB or more


Although you might be able to run the software in less powerful instances, you might encounter some issues while installing or running the node.

Environment requirements

The setup scripts are available for Linux and Mac OS and automated using docker. To run a test net node, you will need to have installed the following docker tools:


The release images target modern x86 architectures. It has been reported that errors are experienced on some older machines provided. If you run into any related issues, please report in the slack group (#help).

Port requirements

Make sure that the server’s host is accessible from the internet and that the following ports are open and available:

  • The port 7900 is used by catapult-server to communicate between nodes.
  • The port 3000 is used by the REST Gateway to expose the endpoints to interact with the node.


The package symbol-testnet-bootstrap contains both assemblies ready to be installed.

  1. Download the latest release of the package, or clone the repository directly using Git.
git clone
  1. Choose the assembly distribution you want to install.

In short, if you want to be able to interact with your node, you need to run the API assembly. On the other hand, if you want a node dedicated exclusively confirm transactions, deploy the Peer assembly.

cd symbol-testnet-bootstrap/api-harvest-assembly


cd symbol-testnet-bootstrap/peer-assembly
  1. Run the node with docker-compose.
sudo docker-compose up --build --detach

You should see docker downloading the container images for the first time. Then it should run the setup and finally startup the service.

To stop all the running services, run sudo docker-compose down in the same directory you executed the up command.

Peer assembly

You can verify that the node is running by running with the command docker-compose ps peer-node in the same peer-assembly folder. The command’s output looks like:

Name                       Command                    State   Ports
peerassembly_peer-node_1   bash -c /bin-mount/wait    Up>7900/tcp

The node is running if the state for peerassembly_peer-node_1 is set to “Up”.

API harvest assembly

The API harvest assembly will set up a dual-purpose API and Peer node, as well as the Rest gateway that transactions can be submitted to and data read from.

API nodes take up more memory and storage than Peer nodes. If you have memory or storage constraints and you are running into issues, it is recommended you switch to running a Peer only node instead.

You can verify that the node is running by opening a new browser tab with the following URL: localhost:3000/chain/height.


The software should expose the port 3000 by default. If you cannot access the REST Gateway from outside, it might mean that the port is closed by default by your machine or hosting provider. If so, you will have to open it in order to access it from outside the machine.

Configuring node properties

After running the node for the first time, you can change a set of properties such as the public name or the harvesting configuration of the node.

To edit the node properties, follow the next steps:

  1. If the node service is running, run sudo docker-compose down under the same directory you executed the up command.
  2. Edit the properties file config-input.yaml with a text editor.
  3. Save and apply the changes with the command sudo docker-compose up --build --detach.

Interacting with the test network

To interact with your node, create first an account and acquire test symbol.xym.

Then, read and write data from the network with the following tools:

On this portal you can find information about Symbol’s features and self-paced guides on how to use the software development kits.