Skip to main content


Fleek Network incentivizes participation by rewarding its node providers. A node is identifiable by an identity, which the reward mechanism uses to identify the node to reward it!

We'll use the term identity to describe the key store declared in the configuration file, in our case a PEM. Remember to keep this file secret πŸ™!

The key store is in the file system and the location is defined in the Fleek Network config.toml, as a private key stored in an identity named PEM file (by default default.pem).

This is interesting, as you may want to move to a new server setup and persist the identity you had originally from another server, let's say!

The following will guide you through some of the fundamentals to help understand how to manage the key store at the very basics, and help you persist the key store identity, in any supported system you're migrating to.


To follow the guide, you will need the following:

  • Familiarity with the command-line interface

πŸ€– As Fleek Network's repositories are in constant development and change, you should consider that the following guide was checked in to commit 5a33b7. While we try our best to update documentation and guides during development, there might be breaking changes that might take some time to reflect in our docs. To avoid disappointment, feel free to check into commit 5a33b7 or contribute by getting in touch with us, or sending a PR in the relevant context. Learn how to checkout a commit in our repository history here πŸ™.

Configuration file​

Locating the file​

The Ursa CLI has a configuration file in the home directory of the user, which is located in the path $HOME/.ursa or ~/.ursa under the name config.toml.

πŸ’‘ The Tilda in ~/.ursa represents $HOME which is simpler, but we'll use $HOME to make it easy to follow.

If you log in with root user that'll be:


If you log in with another user, let's say fleek this means:


At any time, you can check which user you are logged in with by running the command:


Here's an example of our user fleek, which for the command above outputs:


Now that you know where to locate the configuration file for any given user you are logged in with, learn about the Configuration sections.

Configuration sections​

The Fleek Network node configuration settings are located in the path $HOME/.ursa/config.toml, and it's organized by configuration sections.

At the time of writing, we have the following sections:

  • Network config
  • Provider config
  • Server config

Each of the sections holds several property names and values. If you are accustomed to the JSON or YAML formats, you'll find the TOML format a bit similar (if you'd like to learn more about the TOML file format, read about it here).

By default, the Ursa CLI configuration file (config.toml) is similar to:

mdns = false
relay_server = true
autonat = true
relay_client = true
bootstrapper = false
swarm_addr = "/ip4/"
bootstrap_nodes = ["/ip4/", "/ip4/"]
database_path = "/root/.ursa/data/ursa_db"
identity = "default"
keystore_path = "/root/.ursa/keystore"

local_address = ""
port = 8070
domain = ""
indexer_url = ""
database_path = "/root/.ursa/data/index_provider_db"

port = 4069
addr = ""

⚠️ Beware that the configuration file might look a bit different depending on the version you're running and the current development features in place by the Fleek Network dev team.

Some advanced use cases might require dealing with the host and port number binding, depending on the service provider's needs and customization. We'll keep things simple and assume the default settings!

In this guide, we are interested in the network_config section settings for the keystore_path which defaults to /root/.ursa/keystore.

πŸ’‘ The identity is a text description for the Keystore and at the time of writing we have not yet implemented multiple identity management via the CLI. Thereupon, the identity value serves to find the filename match in the keystore_path. This might change as we progress with development. Check the Identity selection to learn more about it!

Identity selection​

Multiple identity management is yet to be implemented but in any case, some users might find it trivial to keep multiple identities and switch between them referencing them by name.

Let's suppose that we've recently moved to a new server setup and copied our previous server keystore as old-server-keystore.pem and renamed the $HOME/.ursa/keystore/default.pem to new-server-keystore.pem.

Here's an example of how our $HOME/.ursa/keystore directory would look like:

β”œβ”€β”€ new-server-keystore.pem
└── old-server-keystore.pem

0 directories, 2 file

The old-server-keystore.pem is the original Keystore and new-server-keystore.pem a brand new identity we got when completed setting up the node in the new system.

As we have our network_config -> identity set as default and network_config -> keystore_path defined as /root/.ursa/keystore, we have to change it! We can switch to an existing identity by providing the filename before the node initialization!

Set the identity name in the network_config -> identity to a matching PEM file that exists in the keystore_path. For our example, that'd be new-server-keystore or old-server-keystore.

πŸ’‘ Name the PEM files as you wish, we have used the naming above to make it as clear as possible.


When you run a node, there's a private key that is used to compute a public key that your node is identified with.

If another party holds the private key, they can control the identity, e.g. have access to the rewards. For this reason, it's important to have at the very least a basic understanding of how identity works in Fleek Network.

Type of keys​

There are two types of keys related to the identity your node is configured to run with, the private and public keys!

πŸ’‘ The public-key cryptography curve used for our key store is the ed25519

The public key is open to anybody to see and it represents a unique node in the Fleek Network, a bit like a bank account number. On the other hand, the private key is secret and the operator is responsible to store it privately!

The Fleek Network relies on cryptography, thus the Fleek Network team can't access, compromise or manipulate the secrets of an identity. On the other hand, the public key can be used by anyone, Fleek Network included, to identify a node or send rewards to the address without jeopardizing identity security!

Key privacy​

If you don’t keep your private key a secret, you have your node compromised.

Here are a few examples of what you should not do:

  • Share your $HOME/.ursa/keystore directory files publicly
  • Track the $HOME/.ursa/keystore directory files in a version control repository e.g. git
  • Have poor "rights" permissions in UNIX systems e.g. everyone can read, delete, modify $HOME/.ursa, etc
  • Allow anyone to access the node provider physically without any access control to the operating and file systems
  • Get rid of a hard drive unformatted or blind erased by selling to somebody or dumping in the bin, which contains $HOME/.ursa/keystore

There are many other ways of getting compromised, but hopefully, the ones put above give you a good starting idea!

Remember, the node provider is the only one responsible when managing the key store! Neither Fleek Network nor the most sophisticated AI system presently can compromise the cryptography in use to help you out.


We've walked through most basics of where the configuration file is located, the configuration settings we use to set up and run the node, the different configuration sections we have, and most importantly the identity section.

Additionally, a brief guide on the identity, more specifically an introduction to the type of keys and key privacy, which we find important to understand for anyone seriously interested in running a node by hinting into some system administration and security principles.

In the future, we'll introduce more advanced topics that will help you improve the knowledge you get from this, but we are glad that you followed this guide and got some comprehension to help you manage the key store.

While we do our best to provide the clearest instructions, there's always space for improvement, therefore feel free to make any contributions by messaging us on our Discord or by opening a PR in any of our repositories πŸ™.

Discover more about the project by watching/contributing on Github, following us on Twitter, and joining our community Discord for all the best updates!

Helder Oliveira
Helder OliveiraSoftware Developer + DXGot questions? Find us on Discord!