Running a Secure Symbol node

The Running a Symbol node guide explains how to easily create a node using Symbol Bootstrap. In that guide, the setup process is conducted on the same machine that will host the node, meaning that private keys are generated on a machine connected to the Internet. If you need a hardened level of security you can follow this guide instead, at the cost of a more involved setup process.

The summary of it is that the symbol-bootstrap start command is split into a config phase run offline, which generates a configuration folder, and the rest of the start command is then run on the destination online machine that will host the node. The main account’s private key never leaves the offline machine.

Machine Function
  • Online to install software, then offline.
  • Creates configuration files.
  • Prepares setup transactions.
  • Permanently online.
  • Runs the node.
  • Announces the setup transactions.

A node can also be setup in such a way that all harvesting rewards go to an external account without requiring this account’s private key. This is known as a non-custodial setup and must be configured once the node is up and running, so a pointer to the appropriate guide is given at the end of this page.

Configuration machine


On the Configuration machine, while still online:

  • Install Symbol Bootstrap as instructed in the Using Symbol Bootstrap guide. Make sure you read also the Configuration section of that guide to get acquainted with presets and assemblies.

  • Install Symbol CLI as instructed in the symbol-cli guide. You just need to run:

     npm install --global symbol-cli
  • Run Symbol Bootstrap a first time, so that it can download the required Docker images:

     symbol-bootstrap config -p mainnet -a <assembly> --noPassword
    rm -rf target

    The output of this first run is irrelevant, that’s why --noPassword is used and the target folder is removed.

  • Disconnect the Configuration machine from the Internet since private keys will be generated on this machine from this point.

Create configuration


Create the main account profile. This is the account that will receive all harvesting fees and whose importance score will be used when harvesting.

The purpose of this guide is making sure that this account’s private key is never used on an online machine.

This step will create a symbol-cli profile to hold the main account and sign transactions using its private key. The machine is offline now, so you need to provide some network-related data.


The commands below assume you want to create a new main account and use the profile create command. If you already have an account that you would like to use as main use the profile import command instead.

 symbol-cli profile create --profile offline-main --default 
   --url http://localhost:3000 --network MAIN_NET 
   --generation-hash 57F7DA205008026C776CB6AED843393F04CD458E0AA2D9F1D5F31A402072B2D6 
   --namespace-id symbol.xym --divisibility 6 
   --epoch-adjustment 1615853185
 symbol-cli profile create --profile offline-test --default 
   --url http://localhost:3000 --network TEST_NET 
   --generation-hash 45FBCF2F0EA36EFA7923C9BC923D6503169651F7FA4EFC46A8EAF5AE09057EBD 
   --namespace-id symbol.xym --divisibility 6 
   --epoch-adjustment 1573430400

When prompted, enter a password to secure your profile and select the PrivateKey import type:

 Enter your wallet password: … *********
Select an import type: › PrivateKey
│ PropertyValue                                                                │
│ Address       │ NCCE5O-BMZHWM-IYZKR6-4WZKFD-4P7DTS-IRXJZ2-3LI                        │
│ Public Key    │ 51C2CB98B61D666A993FA9B25EEBCB48DE5F0B1B7D8B79ECB7AFCB1E5E601108     │
│ Private Key   │ ●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●     │
│ Password      │ ●●●●●●●●●                                                            │
SUCCESS Stored offline-main profile

symbol-cli is now ready to be used later on. All transactions will be signed by your main account so make sure it has some funds to pay for the Fees.

Take note of the main account’s private key and keep it in a safe place.


Create a custom preset file for Symbol Bootstrap and name it custom.yml. It must include, at least, these lines:

 privateKeySecurityMode: PROMPT_MAIN
  mainPrivateKey: ●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●

You can read more about these properties in the security mode section in Symbol Bootstrap’s documentation.

If you have customizations to make, like enabling voting or enrolling in a Reward Program, you can provide them too:

 privateKeySecurityMode: PROMPT_MAIN
  mainPrivateKey: ●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●
  voting: true
  rewardProgram: SuperNode
  host: # Could also be an IP address


Run Symbol Bootstrap again, this time with all required parameters:

 symbol-bootstrap config -p mainnet -a <assembly> -c custom.yml

You will be asked for the password to use to encrypt the configuration files.

 ? Enter password to use to encrypt and decrypt custom presets, addresses.yml,
  and preset.yml files. When providing a password, private keys will be
  encrypted. Keep this password in a secure place! ******
info     Password has been provided
info     Generating config from preset testnet
info     Assembly preset dual
info     Generating Main account...
info     Generating Transport account...
info     Generating Remote account...
info     Generating VRF account...
info     User for docker resolved: 1000:1000
info     Running image using Exec: symbolplatform/symbol-server:tools-gcc- bash
info     Certificate for node api-node created
info     Generating api-node server configuration
info     Generating api-broker broker configuration
info     Non-voting node api-node.
info     Configuration generated.

This generates a target directory containing an addresses.yml file and multiple configuration files.

The main account’s private key is not present in any of these files.

It is worth noting that Symbol Bootstrap enables Remote harvesting by default, meaning that the main private key is never available in a plain text file in the client. Only the remote key is, which acts as a proxy between the node and its main account.

Copy configuration

  • Open custom.yml and remove the line containing mainPrivateKey.

    Now that Symbol Bootstrap has already used it in the config stage, there is no need for such a sensitive key to be lying around in a plain text file.

  • Copy the whole target directory to a pen drive (or other non-networked support) to be used later.

Prepare transactions

Still in the offline Configuration machine, you are now going to prepare a series of link transactions manually. These transactions will be created by symbol-cli, signed by your main account, and will be moved to an online machine to be announced later on.

The following commands all use --max-fee 1000000 which means that 1 XYM will be paid for each transaction. Feel free to use a different number after reading the fees documentation.

Concerning deadlines

All transactions have a deadline, meaning that they must be announced (and confirmed) before the deadline expires.

There is currently a limitation in symbol-cli which sets this deadline to 2 hours after transaction creation, for all non-multisig transactions.

This is a known limitation which is being tracked.

Copy payloads

Copy payloads.txt to the pen drive where you previously copied the target folder.

Online machine

Move now to the online machine, the one that is permanently connected to the Internet and will host the node. Plug in the pen drive with the node configuration.


  • Install Symbol Bootstrap as instructed in the Using Symbol Bootstrap guide.

  • Install Symbol CLI as instructed in the symbol-cli guide. You just need to run:

     npm install --global symbol-cli
  • Create an announcer profile for symbol-cli. This is only a temporary account used to announce the payloads; it does not require funds:

     symbol-cli profile create --profile announcer --default 
       --network MAIN_NET 
     symbol-cli profile create --profile announcer --default 
       --network TEST_NET 

    When prompted, enter a password to secure your profile, and select the PrivateKey import type:

     Enter your wallet password: ... *********
    Select an import type: » PrivateKey
    SUCCESS Stored announcer profile

Start the node

If all key link transactions were confirmed the node is now configured and you can finally launch it.

Go to the directory containing the target directory copied from the Configuration machine and start the node:

 symbol-bootstrap start

No other parameters are required, the configuration is already present in the target directory and Symbol Bootstrap will use it.

The node should start and a lot of debug output should appear on the screen.

 info     Password has been provided
info     The generated preset target/preset.yml already exist, ignoring configuration. (run -r to reset or --upgrade to upgrade)

Your node should now be up and running and its main private key has never left the configuration (offline) machine.

For added security, you can now turn the node’s main account into a Multisig Account. This is useful, for example, for node providers that work in a non-custodial manner. Read about this process in the Non-custodial node setup guide.

Did you find what you were looking for? Give us your feedback.