logo

Intro

KAGOME is a Polkadot Host (former Polkadot Runtime Environment) developed by Quadrivium and funded by a Web3 Foundation grant and Treasury proposals ( 1, 2), 3.

Status

kagome-components-Host drawio-light

More details of KAGOME development can be found within the supported features section and in projects board

Getting Started

Build

Prerequisites

If you are using a Debian Linux system, the following command allows you to build KAGOME:

git clone https://github.com/qdrvm/kagome
cd kagome
sudo chmod +x scripts/init.sh scripts/build.sh

sudo ./scripts/init.sh
./scripts/build.sh

You will get KAGOME binary in the build/node/ folder

Other make commands are:

make docker
make command args="gcc --version"
make release
make release_docker
make debug_docker
make clear

Installation from APT Package

To install KAGOME releases using the provided package repository, follow these steps (tested on Ubuntu 24.04.1 LTS (Noble Numbat)):

Update your package lists and install necessary utilities:

apt update && apt install -y gpg curl

Add the repository’s GPG signing key:

curl -fsSL https://europe-north1-apt.pkg.dev/doc/repo-signing-key.gpg | gpg --dearmor -o /usr/share/keyrings/europe-north-1-apt-archive-keyring.gpg

Add the KAGOME package repository to your sources list:

echo "deb [signed-by=/usr/share/keyrings/europe-north-1-apt-archive-keyring.gpg] https://europe-north1-apt.pkg.dev/projects/kagome-408211 kagome main" > /etc/apt/sources.list.d/kagome.list

Update the package lists and install KAGOME:

apt update && apt install -y kagome

Using KAGOME

Obtaining database snapshot (optional)

In order to avoid syncing from scratch we are maintaining the most recent snapshot of Polkadot network for KAGOME node available for anyone here: https://drive.google.com/drive/folders/1pAZ1ongWB3_zVPKXvgOo-4aBB7ybmKy5?usp=sharing

After downloading the snapshot you can extract it in the folder where the node will be running:

unzip polkadot-node-1.zip

Execute KAGOME Polkadot full syncing node

You can synchronize with Polkadot using KAGOME and obtain an archive node that can be used to query the Polkadot network at any state.

To launch KAGOME Polkadot syncing node execute:

cd examples/polkadot/
PATH=$PATH:../../build/node/
kagome --chain polkadot.json --base-path polkadot-node-1

Note: If you start KAGOME for the first time, you can add the --sync Fast flag to synchronize using Fast sync

After this command KAGOME will connect with other nodes in the network and start importing blocks. You may play with your local node using polkadot js apps: https://polkadot.js.org/apps/?rpc=ws%3A%2F%2F127.0.0.1%3A9944#/explorer

You will also be able to see your node on https://telemetry.polkadot.io/. If you need to identify it more easily you can add --name <node-name> flag to node's execution command and find your node in telemetry by typing its name.

Run kagome --help to explore other CLI flags.

Execute KAGOME block_validator node in development mode

The easiest way to get started with KAGOME is to run it in development mode, which is a single node network:

kagome --dev

That executes node with default accounts Alice and Bob. You can read about these accounts here.

To launch with wiping existing data you can do:

kagome --dev-with-wipe

Run KAGOME node in validator mode

To start the KAGOME validator:

cd examples/first_kagome_chain
PATH=$PATH:../../build/node/
kagome --validator --chain localchain.json --base-path base_path

This command executes a KAGOME full node with an authority role.

Running KAGOME as a Service

You can run KAGOME as a service using a systemd service file. Below is an example of a service file to launch KAGOME Kusama validator:

[Unit]
Description=Kagome Node

[Service]
User=kagome
Group=kagome
LimitCORE=infinity
LimitNOFILE=65536
ExecStart=kagome \ # should be in path
  --name kagome-validator \
  --base-path /home/kagome/dev/kagome-fun/kusama-node-1 \
  --public-addr=/ip4/212.11.12.32/tcp/30334 \ # Address should be publicly accessible
  --validator \
  --listen-addr=/ip4/0.0.0.0/tcp/30334 \
  --chain kusama \
  --prometheus-port=9615 \
  --prometheus-external \
  --wasm-execution Compiled \
  --telemetry-url 'wss://telemetry.polkadot.io/submit/ 1' \
  --rpc-port=9944 \
  --node-key 63808171009b35fc218f207442e355b0634561c84e0aec2093e3515113475624

Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target
Adding the Service File
  1. Copy the service file content into a new file named kagome.service.
  2. Move the file to the systemd directory:

sudo mv kagome.service /etc/systemd/system/

Starting the Kagome Node

To start the Kagome node using systemd:

  1. Reload the systemd manager configuration:
sudo systemctl daemon-reload
  1. (Optionally) Enable the Kagome service to start on boot:
sudo systemctl enable kagome
  1. Start the Kagome service:
sudo systemctl start kagome
  1. Check the status of the Kagome service:
sudo systemctl status kagome

Run KAGOME with collator

Read this tutorial

Contributing Guides

Please refer to the Contributor Documentation.

Modules

You can find more information about the components by checking reference documentation. Check out tutorials and more examples in the official documentation: https://kagome.readthedocs.io/

KAGOME in media