Run a Native Node

TL;DR

Fiber v0.9.1 includes an installer that 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

The installer supports Linux, macOS, and 64-bit Windows. Linux and macOS release bundles are available for x86-64 and ARM64; Windows currently uses the x86-64 bundle.

Linux and macOS

Run the bootstrap step:

curl -sSfL https://raw.githubusercontent.com/nervosnetwork/fiber/v0.9.1/tools/install/install.sh \
  | INSTALL_REF=v0.9.1 FNN_VERSION=0.9.1 bash

This non-interactive step installs the v0.9.1 release bundle and ckb-cli into ~/.fiber, writes the Testnet configuration, and saves the pinned 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 export 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 = "v0.9.1"
$env:FNN_VERSION = "0.9.1"
$env:NETWORK = "testnet"
$env:INSTALL_DIR = "$HOME\.fiber"
irm https://raw.githubusercontent.com/nervosnetwork/fiber/v0.9.1/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; bootstrap or non-interactive Mainnet setup requires NETWORK=mainnet and 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 when you need a custom installation layout or want 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 the archive for your operating system and CPU from the v0.9.1 release. The portable archives include fnn, fnn-cli, and the Mainnet and Testnet configuration templates.

For example, on an Apple Silicon Mac:

curl --fail --location --remote-name --retry 5 \
  https://github.com/nervosnetwork/fiber/releases/download/v0.9.1/fnn_v0.9.1-aarch64-darwin-portable.tar.gz
tar -xzf fnn_v0.9.1-aarch64-darwin-portable.tar.gz
./fnn --version
./fnn-cli --version

The expected versions are fnn Fiber v0.9.1 and fnn-cli 0.9.1. Replace aarch64-darwin with the target matching your system; the release also provides archives for Intel macOS, x86-64 and ARM64 Linux, and x86-64 Windows.

Alternatively, build the tagged source release:

git clone --branch v0.9.1 --depth 1 https://github.com/nervosnetwork/fiber.git
cd fiber
cargo build --release

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

2. Create the Node Directory

From the extracted release directory, create a dedicated directory for your node and copy the included binaries and Testnet configuration:

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

If you built from source, copy target/release/fnn, target/release/fnn-cli, and config/testnet/config.yml from the cloned repository instead.

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 | sed 's/^0x//' > ./ckb/key
rm ./ckb/exported-key
chmod 600 ./ckb/key

4. Start the Node

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

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

You should see the node migrate the key to its encrypted format, listen on P2P port 8228, connect to the Testnet bootnodes, and create an initial backup under fiber/backups. The RPC server is available at 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.

Version Compatibility and Upgrades

Upgrade Safely to v0.9.1

1. Stop the old node cleanly. Never run two FNN processes against the same data directory.
2. Back up the complete node directory, including ckb, fiber/store, fiber/sk, and config.yml.
3. Replace both fnn and fnn-cli with the v0.9.1 binaries.
4. Start FNN against the existing directory and review any migration confirmation before proceeding.

Do not delete fiber/store during an upgrade. It contains channel state, and losing it can put funds at risk. See Backup and Restore for backup contents, validation, and recovery steps.

RPC Changes Since v0.7.1

Storage Migration

Storage migration has been integrated into fnn since v0.9.0-rc1. A v0.8.x database can be migrated when v0.9.1 starts; databases older than v0.8.x must first be upgraded with the matching v0.8.x fnn-migrate tool. Back up the full data directory first, and do not bypass an unexpected migration error by deleting the store.

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