> For the complete documentation index, see [llms.txt](https://docs.logos.co/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.logos.co/blockchain/get-started/run-a-logos-blockchain-node-from-cli.md).

# 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](https://www.raspberrypi.com/software/) 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](https://github.com/logos-blockchain/logos-blockchain/releases/latest), 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`:

   ```sh
   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):

   ```sh
   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):

   ```sh
   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:

   ```sh
   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:

   ```sh
   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](https://github.com/logos-blockchain/logos-blockchain/releases/latest) 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:

   ```sh
   ./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:

   ```sh
   ./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:

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

   Example response:

   ```json
   {
     "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:

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

   Example response:

   ```json
   {
     "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](https://testnet.blockchain.logos.co/web/faucet/) after your node reaches `Online` mode.

1. Find the keys associated with your node:

   ```sh
   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**.

   ![Image of the faucet UI after requesting funds with a public key](/files/DjikjlKNx0C2bUy1zVFB)
3. Wait 1 to 2 minutes, then check your balance. Replace `<your-chosen-key>` with the key you used:

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

   Example response:

   ```json
   {
     "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](https://testnet.blockchain.logos.co/web/) 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.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.logos.co/blockchain/get-started/run-a-logos-blockchain-node-from-cli.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.