Run a Native Node

TL;DR

The Fiber installer downloads the FNN release bundle and ckb-cli, prepares the selected network configuration, guides you through key setup, and creates a reusable startup script.

Choose an Installation Method

Automated Installer Preview

The installer supports Linux, macOS, and 64-bit Windows. On Linux and macOS it recognizes x86_64 and ARM64 release bundles; Windows currently uses the x86_64 bundle.

Linux and macOS

Run the bootstrap step. The explicit develop ref is required while the installer remains unreleased:

curl -sSfL https://raw.githubusercontent.com/nervosnetwork/fiber/develop/tools/install/install.sh \
  | INSTALL_REF=develop FNN_VERSION=0.9.0-rc7 bash

This non-interactive step installs the release bundle and ckb-cli into ~/.fiber, writes the Testnet configuration, and saves the guided installer. It does not create or import your CKB key.

Run the guided step to set up the key and startup script:

~/.fiber/tools/install/install.sh ~/.fiber testnet

The guided installer can create a new CKB account or import an existing account. Save the wallet password and the FIBER_SECRET_KEY_PASSWORD securely; they protect different operations and may be different values.

When setup finishes, accept the prompt to start FNN or start it later with:

cd ~/.fiber
./start-node.sh

Windows PowerShell

The Windows installer performs the guided setup in one pass. Use Windows PowerShell 5.1 or newer:

$env:INSTALL_REF = "develop"
$env:FNN_VERSION = "0.9.0-rc7"
$env:NETWORK = "testnet"
$env:INSTALL_DIR = "$HOME\.fiber"
irm https://raw.githubusercontent.com/nervosnetwork/fiber/develop/tools/install/install.ps1 | iex

After stopping the node, restart it with:

cd $HOME\.fiber
.\start-node.ps1

You can also run start-node.bat from Command Prompt or double-click it in the install directory.

What the Installer Creates

The install directory contains the complete node state and tools:

Mainnet Requirements

Start on Testnet. A Mainnet installation additionally requires a trusted CKB RPC endpoint. The installer validates that the endpoint is reachable and belongs to the selected network; non-interactive Mainnet setup requires CKB_RPC_URL explicitly.

Use a separate install directory for each network. The installer records the selected network and refuses to reuse a directory containing another network's data.

Manual Installation

Use this path with current Fiber releases or when you need to build FNN yourself.

Prerequisites

• Basic command-line experience
• ckb-cli for key management
• Git, Rust, and Cargo only when building from source

1. Obtain the FNN Binary

Download a pre-built bundle from Fiber Releases, or build from source:

git clone https://github.com/nervosnetwork/fiber.git
cd fiber
git checkout v0.9.0-rc7
cargo build --release

The examples below use v0.9.0-rc7. Keep the binary and configuration from the same release. Omit the checkout step only when you intentionally want to test unreleased source.

xattr -d com.apple.quarantine fnn fnn-cli

2. Create the Node Directory

Create a dedicated directory and copy the binaries and Testnet configuration into it:

mkdir -p /folder-to/my-fnn
cp target/release/fnn /folder-to/my-fnn
cp target/release/fnn-cli /folder-to/my-fnn
cp config/testnet/config.yml /folder-to/my-fnn
cd /folder-to/my-fnn

When using a release bundle, copy its fnn, fnn-cli, and matching config/testnet/config.yml instead of the target/release files.

3. Create or Import the Node Key

FNN's built-in wallet signs channel funding transactions. Create an account and save its lock_arg:

ckb-cli account new

Export the selected account into the node directory:

mkdir -p ckb
ckb-cli account export \
  --lock-arg <lock_arg> \
  --extended-privkey-path ./ckb/exported-key
head -n 1 ./ckb/exported-key > ./ckb/key
rm ./ckb/exported-key
chmod 600 ./ckb/key

The key is plaintext until FNN starts successfully for the first time. Keep the directory private during setup.

4. Start the Node

Use a strong, unique password. FNN encrypts a plaintext ckb/key on first start and requires the same password on every later start:

FIBER_SECRET_KEY_PASSWORD='YOUR_STRONG_PASSWORD' \
  RUST_LOG=info \
  ./fnn -c config.yml -d .

You should see logs for the RPC service, P2P listener, and bootnode connections. The local RPC endpoint is http://127.0.0.1:8227 by default.

Interact with Your Node

Open another terminal in the install directory.

Use fnn-cli

# View node information
./fnn-cli info

# List connected peers
./fnn-cli peer list_peers

# List open channels
./fnn-cli channel list_channels

# List available commands
./fnn-cli --help

The CLI connects to http://127.0.0.1:8227 by default.

export NO_PROXY=127.0.0.1,localhost
./fnn-cli info

Use JSON-RPC

curl -X POST -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"node_info"}' \
  http://127.0.0.1:8227/

Stop and Restart

Press Ctrl+C in the FNN terminal to stop the node cleanly.

For an installer-created node, use the generated startup script and enter the original FIBER_SECRET_KEY_PASSWORD when prompted:

cd ~/.fiber
./start-node.sh

For a manual installation, rerun the original fnn command with the same data directory, configuration, and password.

Upgrades and Storage Migration

Back up the entire node directory before every upgrade. Starting with v0.9.0-rc1, FNN detects supported database versions and performs required migration during startup.

For databases too old for the current binary, use the migration tool from the appropriate older release first. See Fiber Node Backup for the version-specific process.

Next Steps

• Basic Transfer — send your first payment
• Connect to Nodes — connect to Fiber peers
• Configuration Reference — review all node settings
• Back Up Your Node — protect keys, identity, and channel state