FluxOS Setup Guide

FluxOS Setup Guide

This guide walks you through setting up a Flux node from scratch. ArcaneOS is the recommended — and soon mandatory — way to run a Flux node. It replaces the legacy manual Linux setup with a streamlined, security-first approach that includes automatic updates, self-healing, and eligibility for Progressive Node Rewards (PNR).

ArcaneOS Setup (Recommended)

ArcaneOS is a hardened, Ubuntu 24-based operating system designed specifically for Flux nodes. It introduces the SAS (Secure Autonomous System) security protocol, automatic self-healing, and — critically — is required for PNR eligibility. After installation, ArcaneOS handles FluxOS updates, daemon updates, and Docker management automatically.

Prerequisites

• •Architecture: AMD64 only (ARM/Apple Silicon not supported)
• •Installation type: Bare metal or virtual machine (VM)
• •TPM 2.0: Required for UEFI Secure Boot — ensure your BIOS/hypervisor supports it
• •Network: Stable internet connection with a dedicated public IPv4 address
• •Collateral: Flux collateral ready in ZelCore or SSP Wallet (1,000 for Cumulus, 12,500 for Nimbus, 40,000 for Stratus)

Step 1: Create a Virtual Machine (if applicable)

If running on a hypervisor (Proxmox, VMware, Hyper-V), create a new VM with the following settings:

Step 2: Download & Boot the ISO

1. 1

   Download ArcaneOS ISO

   Get the latest ISO from the official Flux download page or through your ZelCore wallet under the ArcaneOS section.

2. 2

   Create bootable media

   For bare metal: flash the ISO to a USB drive using Balena Etcher or Rufus. For VMs: mount the ISO directly.

3. 3

   Boot from ISO

   Set your BIOS/VM to boot from the ISO. The ArcaneOS installer will launch automatically.

Step 3: OS Installation

The installer is guided and largely automated. It will partition the disk, install the base Ubuntu 24 system, and apply the ArcaneOS security hardening layer. Follow the on-screen prompts to configure your timezone, keyboard layout, and initial user account.

Step 4: Platform Key Configuration

After the first boot, ArcaneOS will prompt you to configure your Platform Key. This cryptographic key ties your node to the Flux network and is essential for node identity verification.

Step 5: FluxNode Configuration

Configure your FluxNode using one of three methods:

1. 1

   ZelCore Token (Recommended)

   Generate a configuration token from ZelCore wallet and paste it into the ArcaneOS setup. Simplest method for most users.

2. 2

   SSP Token

   Generate a token from SSP Wallet. Works the same way as ZelCore but uses SSP's key management.

3. 3

   Manual configuration

   Enter your collateral transaction hash, output index, and Flux private key manually. Best for advanced users.

Step 6: Notifications

ArcaneOS supports built-in notification channels. Configure Discord webhooks or Telegram bot tokens to receive alerts about node status changes, benchmark results, and maintenance events.

Step 7: SSH Access

SSH is available for remote management. ArcaneOS enforces key-based authentication by default. During setup, you can add your public SSH key. Password-based SSH login is disabled for security.

Step 8: Verify Node Status

Access the FluxOS UI dashboard by navigating to your server IP on port 16126 in a web browser. This provides a real-time overview of your node status, benchmark results, connected peers, and deployed applications.

http://YOUR_SERVER_IP:16126

Legacy Setup (Not Recommended)

The legacy method involves manually installing FluxOS on a standard Ubuntu server using the Multitoolbox script. This approach requires ongoing manual maintenance, including OS updates, FluxOS updates, and firewall configuration.

Legacy Prerequisites

• •Operating System: Ubuntu 22.04 LTS (recommended). Ubuntu 20.04 LTS is also supported.
• •Fresh Server: Start with a clean OS installation.
• •Root Access: You need root or sudo access.
• •Public IPv4 Address: Dedicated public IPv4 reachable from the internet.
• •Collateral: FLUX collateral in your Zelcore or SSP Wallet.
• •Zel ID: Registered through Zelcore wallet.

Legacy Installation Steps

1. 1

   Update system and install dependencies

   Run "sudo apt update && sudo apt upgrade -y" and install curl, wget, and git.

2. 2

   Configure firewall

   Open ports 16124-16129/tcp and 16132/tcp using UFW. Allow SSH before enabling the firewall.

3. 3

   Run the Multitoolbox installer

   Execute "bash -i <(curl -s https://raw.githubusercontent.com/RunOnFlux/fluxnode-multitool/master/multitoolbox.sh)" and select the option to install a new Flux node. The script installs Docker, MongoDB, Node.js, the Flux daemon, and FluxOS.

4. 4

   Configure node identity

   Enter your Zel ID, identity key (znodePrivKey), and collateral transaction (znodeoutpoint) when prompted.

5. 5

   Start the node from your wallet

   In Zelcore, go to Apps > Flux Nodes, select your node, and click "Start Node".

6. 6

   Wait for blockchain sync and confirmation

   Monitor with "flux-cli getblockchaininfo". The node must fully sync and reach "CONFIRMED" status.

Common Issues and Troubleshooting

1. 1

   Node stuck on "STARTED" instead of "CONFIRMED"

   The blockchain is still syncing or the node has not been recognized by the network yet. Wait for full sync and allow up to 2 hours for confirmation. Verify your collateral transaction is correct.

2. 2

   Benchmark failures after installation

   Check that your hardware meets the minimum requirements for your chosen tier. Run "fluxbench-cli getbenchmarks" to see which specific test is failing (CPU, RAM, SSD, or bandwidth).

3. 3

   Port not reachable

   On ArcaneOS, ports are configured automatically. On legacy, verify UFW rules with "sudo ufw status verbose". Check that your hosting provider does not have an external firewall blocking the required ports.

4. 4

   FluxOS UI not loading

   Ensure port 16126 is accessible. On legacy nodes, check that FluxOS is running with "pm2 list" and restart with "pm2 restart flux" if needed. On ArcaneOS, the SAS protocol handles restarts automatically.