ift-docs/docs/blockchain/get-started/run-a-logos-blockchain-node-from-cli.md

title, doc_type, product, topics, steps_layout, authors, owner, doc_version, slug

title	doc_type	product	topics	steps_layout	authors	owner	doc_version	slug
Run a Logos Blockchain node on the public testnet from the CLI	procedure	blockchain	blockchain	sectioned	kashepavadan, davidrusu	logos	1	run-a-logos-blockchain-node-from-cli

Run a Logos Blockchain node on the public testnet from the CLI

Start a node and verify runtime and consensus signals.

With this tutorial, you will install the Logos Blockchain node, connect to the public testnet, and verify that your node is running. The Logos Blockchain is the blockchain module of the Logos technology stack, providing a privacy-preserving and censorship-resistant framework for decentralised applications. This procedure is for node operators setting up a node for the first time.

There is currently no dynamic wallet key management. To add new keys you must manually edit user_config.yaml and restart the node. If the node is restarted while bootstrapping, it does not save sync progress and restarts from the beginning.

Before you start, ensure you have:

• Linux x86_64, macOS, or a Raspberry Pi 5 with Raspberry Pi OS installed
• glibc version 2.39 or later (Linux only)
• At least 64 GB of storage

What to expect

• You can install the node binary and ZK circuits, generate a configuration, and join the public testnet.
• You can verify that your node is syncing and connected to peers using the local API.
• You can receive test tokens from the faucet and automatically participate in the consensus lottery once your stake matures.

Step 1: Install the node binary and ZK circuits

The node requires zero-knowledge circuit files for cryptographic operations. Download the node binary and circuits archive from the Logos Blockchain Node releases page, then install both before running the node.

{% hint style="info" %}

The wallet used here is the node's internal key store, not a general-purpose user wallet. It holds the staking keys that give your node the right to participate in the consensus lottery.

{% endhint %}

1. Download the latest node binary and circuits archive for your device's architecture.

   • The node filename begins with logos-blockchain-node-.
   • The circuits filename begins with logos-blockchain-circuits-.

   For example, to download release 0.1.2 on Linux x86_64 with wget:

   wget https://github.com/logos-blockchain/logos-blockchain/releases/download/0.1.3-rc.1/logos-blockchain-circuits-v0.4.2-linux-x86_64.tar.gz
   wget https://github.com/logos-blockchain/logos-blockchain/releases/download/0.1.2/logos-blockchain-node-linux-x86_64-0.1.2.tar.gz
   

   On macOS (aarch64):

   wget https://github.com/logos-blockchain/logos-blockchain/releases/download/0.1.2/logos-blockchain-circuits-v0.4.2-macos-aarch64.tar.gz
   wget https://github.com/logos-blockchain/logos-blockchain/releases/download/0.1.2/logos-blockchain-node-macos-aarch64-0.1.2.tar.gz
   

   On a Raspberry Pi (aarch64):

   wget https://github.com/logos-blockchain/logos-blockchain/releases/download/0.1.2/logos-blockchain-circuits-v0.4.2-linux-aarch64.tar.gz
   wget https://github.com/logos-blockchain/logos-blockchain/releases/download/0.1.2/logos-blockchain-node-linux-aarch64-0.1.2.tar.gz
   

2. Extract the downloaded archives:

   tar -xf logos-blockchain-circuits-*.tar.gz
   tar -xf logos-blockchain-node-*.tar.gz
   

3. Move the extracted circuits folder to ~/.logos-blockchain-circuits, the default location the node searches:

   mv logos-blockchain-circuits-*/ ~/.logos-blockchain-circuits
   

   • To store circuits elsewhere, move them to your preferred path and set export LOGOS_BLOCKCHAIN_CIRCUITS=/path/to/your/circuits.

Step 2: Configure and start the node

The init subcommand generates a user configuration that includes per-node settings such as keys, ports, and peer addresses, along with fresh cryptographic keys and an auto-detected public IP.

{% hint style="info" %}

Make sure to use the current bootstrap peer addresses in the Logos Blockchain Node release notes for your selected release.

{% endhint %}

1. Generate your user_config.yaml by running init with the bootstrap peer addresses. For example, for release 0.1.2:

   ./logos-blockchain-node init \
       -p /ip4/65.109.51.37/udp/3000/quic-v1 \
       -p /ip4/65.109.51.37/udp/3001/quic-v1 \
       -p /ip4/65.109.51.37/udp/3002/quic-v1 \
       -p /ip4/65.109.51.37/udp/3003/quic-v1
   

   • To change the API port, set api.backend.listen_address in user_config.yaml before starting. The default is 8080.

2. Start the node:

   ./logos-blockchain-node user_config.yaml
   

Step 3: Verify that your node is running and connected to peers

Wait for your node to finish syncing and reach Online mode before requesting tokens. Pipe any curl command through jq . to format JSON output.

1. Check the consensus state:

   curl -s http://localhost:8080/cryptarchia/info | jq .
   

   Example response:

   {
     "lib": "3d0c...4e6d",
     "lib_slot": 0,
     "tip": "f44d...e2f5",
     "slot": 70899,
     "height": 120,
     "mode": "Bootstrapping"
   }
   

   • mode starts as Bootstrapping while syncing and transitions to Online once caught up.
   • Confirm slot and height are increasing. height counts confirmed blocks; slot counts elapsed time intervals, with a new block expected roughly every 10 seconds.

2. Check peer connectivity:

   curl -s http://localhost:8080/network/info | jq .
   

   Example response:

   {
     "listen_addresses": ["/ip4/127.0.0.1/udp/3001/quic-v1"],
     "peer_id": "12D3...fuS2",
     "n_peers": 16,
     "n_connections": 19,
     "n_pending_connections": 0
   }
   

   • Confirm n_peers is greater than 0.

3. After 30–60 seconds, run the cryptarchia/info command again and confirm slot and height have increased.

4. Wait until mode transitions to Online before continuing. Bootstrapping should take approximately 1 hour.

Step 4: Request tokens from the faucet

A faucet distributes free tokens on test networks so you can experiment without financial risk. Navigate to the public faucet site after your node reaches Online mode.

1. Find the keys associated with your node:

   grep -A3 known_keys user_config.yaml
   

   Example output:

   known_keys:
       57364103d3ff29c35d2073cba0526ef729b8e08490bddfc6b74128b6613fe923: ...
       de3233cec107e6589f83d4f3094caa65c633b5b33601211353779dc01972ca14: ...
   voucher_master_key_id: de3233cec107e6589f83d4f3094caa65c633b5b33601211353779dc01972ca14
   

2. Choose any key from known_keys, enter it in Destination Public Key (Hex) on the faucet site, and press Request Funds.

   

3. Wait 1 to 2 minutes, then check your balance. Replace <your-chosen-key> with the key you used:

   curl -s http://localhost:8080/wallet/<your-chosen-key>/balance | jq .
   

   Example response:

   {
     "tip": "5d16d4bd3712dc5869fc624e59774552b4fb0c974a6efa516563b3778bac9258",
     "balance": 1000,
     "address": "57364103d3ff29c35d2073cba0526ef729b8e08490bddfc6b74128b6613fe923"
   }
   

   • Only one faucet transaction can be included per block. During high demand, your transaction may be dropped; retry the request and wait 1 to 2 minutes before checking again.

{% hint style="info" %}

Your tokens become eligible for consensus after 3.5 hours. Confirm that your node is participating by checking that mode remains Online and height continues to increase.

Block proposal is probabilistic. Your node will not propose on every slot; participation depends on your stake relative to total active stake in the network.

{% endhint %}

Troubleshooting the Logos Blockchain node

The testnet explorer shows an error when I click on a transaction?

The testnet explorer does not support clicking on individual transactions. Searching by address is also not supported. Transaction hashes returned by the faucet may appear truncated and may not be immediately findable.

My wallet balance is not updating after requesting tokens?

Only one faucet transaction can be included per block. During high demand, your transaction may be dropped. Retry the request and wait 1 to 2 minutes before checking your balance again.