Skip to content

firedancer Command Line Interface ​

The Firedancer binary firedancer contains many subcommands which can be run from the command line.

Commands that attach to a running validator fall into two groups. set-identity, get-identity, and add-authorized-voter are versioned and work across releases. Diagnostic commands like monitor, watch, and metrics read the validator's memory directly and must be run from the same binary the validator is running.

run ​

Runs the validator. This command does not exit until the validator does, an error in running the validator will be propagated to the exit code of the process. The command can be run with the capabilities listed below but it is suggested to run it as sudo. The command writes an abbreviated log output to stderr and nothing will be written to stdout.

ArgumentsDescription
--config <path>Path to a configuration TOML file to run the validator with
--standbyBoot as a failover standby using an unstaked identity, see the failover guide
Capabilities
CapabilityReason
CAP_NET_RAWcall socket(2) to bind to a raw socket for use by XDP
CAP_SYS_ADMINcall bpf(2) with the BPF_OBJ_GET command to initialize XDP
CAP_SYS_ADMINcall unshare(2) with CLONE_NEWUSER to sandbox the process in a user namespace. Only required on kernels which restrict unprivileged user namespaces
CAP_SETUIDcall setresuid(2) to switch uid to the sandbox user. Not required if the UID is already the same as the sandbox UID
CAP_SETGIDcall setresgid(2) to switch gid to the sandbox user. Not required if the GID is already the same as the sandbox GID
CAP_SYS_RESOURCEcall rlimit(2) to increase RLIMIT_MEMLOCK so all memory can be locked with mlock(2). Not required if the process already has a high enough limit
CAP_SYS_RESOURCEcall setpriority(2) to increase thread priorities. Not required if the process already has a nice value of -19
CAP_SYS_RESOURCEcall rlimit(2) to increase RLIMIT_NOFILE` to allow more open files for Agave. Not required if the resource limit is already high enough
CAP_NET_BIND_SERVICEcall bind(2) to bind to a privileged port for serving metrics. Only required if the bind port is below 1024
$ firedancer run --config config.toml
Log at "/tmp/fd-0.1.1_1987461_sun-ossdev-firedancer31_2026_10_20_16_32_23_068864834_GMT+00"
WARNING 10-20 16:32:23.089738 main      nohz-full.c(71): tile cpus 1-38 are not in the kernel nohz_full= set and will be interrupted by periodic timer ticks. For lower jitter, boot with nohz_full=1-38.
WARNING 10-20 16:32:24.188608 main      fd_topo.c(159): fd_topo_wksp_new(store) took 165 ms
NOTICE  10-20 16:32:24.306879 main      fd_bootinfo.c(168): booting validator fd1 version 0.1.1 (babe91c83ca) pid 1987461 with 55 tiles and 87 GiB memory at /mnt/.fd
NOTICE  10-20 16:32:24.362519 metric:0  fd_metric_tile.c(148): prometheus server listening at http://127.0.0.1:7999/metrics
WARNING 10-20 16:32:24.419250 votor:0   fd_votor_tile.c(2508): vote history file `/home/firedancer/.firedancer/fd1/vote_history-4Dm5AX6DruesFVJYK5ajk2Gyymqmscgx1PoXbYfQbGSY.bin` does not exist, creating it.  This identity is assumed to have never voted.
NOTICE  10-20 16:32:24.438850 gui:0     fd_gui_tile.c(857): gui server listening at http://127.0.0.1:80
NOTICE  10-20 16:32:24.442772 rpc:0     fd_rpc_tile.c(3155): rpc server listening at http://127.0.0.1:8899
NOTICE  10-20 16:32:25.290178 genesi:0  fd_genesi_tile.c(383): retrieved genesis /home/firedancer/.firedancer/fd1/genesis.bin from peer at http://109.94.99.177:8899/genesis.tar.bz2
NOTICE  10-20 16:32:25.454314 event:0   fd_event_client.c(687): connected to telemetry server https://events-in.firedancer.io:443
NOTICE  10-20 16:32:27.370526 snapct:0  fd_snapct_tile.c(756): downloading full snapshot from untrusted gossip peer 141vSYKGRPNGieSrGJy8EeDVBcbjSr6aWkimNgrNZ6xN
NOTICE  10-20 16:32:38.820601 snapct:0  fd_snapct_tile.c(756): downloading incremental snapshot from untrusted gossip peer 141vSYKGRPNGieSrGJy8EeDVBcbjSr6aWkimNgrNZ6xN
NOTICE  10-20 16:32:38.858957 snapin:0  fd_snapin_tile.c(389): loaded 89.3M accounts (9.2K dups) from snapshot in 14.466 seconds
NOTICE  10-20 16:32:41.805075 replay:0  fd_replay_tile.c(1313): caught up to cluster at slot 454774712 (19.3 seconds since boot)

monitor ​

Monitors a validator that is running locally on this machine. This is a low level performance monitor mostly useful for diagnosing throughput issues. The monitor takes over the controlling terminal and refreshes it many times a second with up to date information. You can exit the monitor by sending Ctrl+C or SIGINT.

ArgumentsDescription
--config <path>Path to a configuration TOML file to run the monitor with. This must be the same configuration file the validator was started with
Capabilities
CapabilityReason
CAP_SYS_ADMINcall unshare(2) with CLONE_NEWUSER to sandbox the process in a user namespace. Only required on kernels which restrict unprivileged user namespaces
CAP_SETUIDcall setresuid(2) to switch uid to the sandbox user. Not required if the UID is already the same as the sandbox UID
CAP_SETGIDcall setresgid(2) to switch gid to the sandbox user. Not required if the GID is already the same as the sandbox GID
CAP_SYS_RESOURCEcall rlimit(2) to increase RLIMIT_MEMLOCK so all memory can be locked with mlock(2). Not required if the process already has a high enough limit
$ firedancer monitor --config config.toml
snapshot for 2026-10-20 16:29:11.311695967 GMT+00 | Use TAB to switch panes
    tile |     tid |      stale | heart | nivcsw              | nvcsw               | in backp |           backp cnt |  % hkeep |  % wait  |  % backp | % finish
---------+---------+------------+-------+---------------------+---------------------+----------+---------------------+----------+----------+----------+----------
  netlnk | 1983482 |          - |     - |          1(     +0) |      92592(     +0) |   -(  -) |          0(     +0) |    0.002 |   99.998 |    0.000 |    0.000
     net | 1983506 |          - |     - |         29(     +0) |          8(     +0) |   -(  -) |          0(     +0) |    0.684 |   99.316 |    0.000 |    0.000
     net | 1983508 |          - |     - |         27(     +0) |          4(     +0) |   -(  -) |          0(     +0) |    0.678 |   99.322 |    0.000 |    0.000
  metric | 1983483 |          - |     - |          0(     +0) |      92626(     +0) |   -(  -) |          0(     +0) |    0.003 |   99.997 |    0.000 |    0.000
    diag | 1983484 |          - |     - |          0(     +0) |       4989(     +0) |   -(  -) |          0(     +0) |    0.003 |   99.997 |    0.000 |    0.000
  ipecho | 1983486 |          - |     - |          3(     +0) |      92511(     +0) |   -(  -) |          1(     +0) |    0.003 |   99.997 |    0.000 |    0.000
  gossvf | 1983512 |          - |     - |         27(     +0) |          3(     +0) |   -(  -) |          0(     +0) |    0.049 |   99.951 |    0.000 |    0.000
  gossip | 1983511 |          - |     - |         37(     +0) |          5(     +0) |   -(  -) |          0(     +0) |    0.092 |   99.897 |    0.000 |    0.011
   shred | 1983514 |          - |     - |         26(     +0) |          5(     +0) |   -(  -) |          0(     +0) |    0.086 |   99.914 |    0.000 |    0.000
  repair | 1983515 |          - |     - |         30(     +0) |          5(     +0) |   -(  -) |          0(     +0) |    0.086 |   99.914 |    0.000 |    0.000
  rserve | 1983517 |          - |     - |         61(     +0) |          5(     +0) |   -(  -) |          0(     +0) |    0.491 |   99.509 |    0.000 |    0.000
  replay | 1983528 |          - |     - |         27(     +0) |          5(     +0) |   -(  -) |          0(     +0) |    2.738 |   97.262 |    0.000 |    0.000
   accdb | 1983529 |          - |     - |         40(     +0) |         55(     +0) |   -(  -) |          0(     +0) |    0.018 |   99.982 |    0.000 |    0.000
  execrp | 1983531 |          - |     - |         27(     +0) |         64(     +0) |   -(  -) |          0(     +0) |    0.019 |   99.981 |    0.000 |    0.000
  execrp | 1983532 |          - |     - |         27(     +0) |         67(     +0) |   -(  -) |          0(     +0) |    0.020 |   99.980 |    0.000 |    0.000
  execrp | 1983534 |          - |     - |         26(     +0) |         65(     +0) |   -(  -) |          0(     +0) |    0.020 |   99.980 |    0.000 |    0.000
  execrp | 1983535 |          - |     - |         26(     +0) |         68(     +0) |   -(  -) |          0(     +0) |    0.020 |   99.980 |    0.000 |    0.000
  execrp | 1983538 |          - |     - |         29(     +0) |         60(     +0) |   -(  -) |          0(     +0) |    0.020 |   99.980 |    0.000 |    0.000
  execrp | 1983547 |          - |     - |         25(     +0) |         59(     +0) |   -(  -) |          0(     +0) |    0.020 |   99.980 |    0.000 |    0.000
  execrp | 1983555 |          - |     - |         25(     +0) |         63(     +0) |   -(  -) |          0(     +0) |    0.024 |   99.976 |    0.000 |    0.000
  execrp | 1983556 |          - |     - |         25(     +0) |         63(     +0) |   -(  -) |          0(     +0) |    0.020 |   99.980 |    0.000 |    0.000
  execrp | 1983554 |          - |     - |         26(     +0) |         58(     +0) |   -(  -) |          0(     +0) |    0.023 |   99.977 |    0.000 |    0.000
  execrp | 1983557 |          - |     - |         24(     +0) |         59(     +0) |   -(  -) |          0(     +0) |    0.022 |   99.978 |    0.000 |    0.000
   votor | 1983566 |          - |     - |         27(     +0) |          3(     +0) |   -(  -) |          0(     +0) |    0.110 |   99.890 |    0.000 |    0.000
    quic | 1983569 |          - |     - |         28(     +0) |         15(     +0) |   -(  -) |          0(     +0) |    0.004 |   99.996 |    0.000 |    0.000
  verify | 1983568 |          - |     - |         27(     +0) |         16(     +0) |   -(  -) |          0(     +0) |    6.555 |   93.445 |    0.000 |    0.000
  verify | 1983570 |          - |     - |         27(     +0) |         16(     +0) |   -(  -) |          0(     +0) |    6.543 |   93.457 |    0.000 |    0.000
  verify | 1983572 |          - |     - |         26(     +0) |         15(     +0) |   -(  -) |          0(     +0) |    6.625 |   93.375 |    0.000 |    0.000
   dedup | 1983573 |          - |     - |         27(     +0) |          8(     +0) |   -(  -) |          0(     +0) |    0.398 |   99.602 |    0.000 |    0.000
  resolv | 1983575 |          - |     - |         26(     +0) |         17(     +0) |   -(  -) |          0(     +0) |    0.102 |   99.898 |    0.000 |    0.000
    pack | 1983584 |          - |     - |         28(     +0) |         16(     +0) |   -(  -) |          0(     +0) |    0.101 |   15.631 |    0.000 |   84.268
  execle | 1983586 |          - |     - |         24(     +0) |         48(     +0) |   -(  -) |          0(     +0) |    0.057 |   99.943 |    0.000 |    0.000
  execle | 1983585 |          - |     - |         27(     +0) |         51(     +0) |   -(  -) |          0(     +0) |    0.058 |   99.942 |    0.000 |    0.000
   motor | 1983587 |          - |     - |         24(     +0) |         44(     +0) |   -(  -) |          0(     +0) |    0.044 |   99.956 |    0.000 |    0.000
    sign | 1983593 |          - |     - |         27(     +0) |          3(     +0) |   -(  -) |          0(     +0) |    0.045 |   99.955 |    0.000 |    0.000
    sign | 1983594 |          - |     - |         40(     +0) |          4(     +0) |   -(  -) |          0(     +0) |    0.017 |   99.983 |    0.000 |    0.000
     rpc | 1983595 |          - |     - |         75(     +0) |          3(     +0) |   -(  -) |          0(     +0) |    0.049 |   99.951 |    0.000 |    0.000
   admin | 1983489 |          - |     - |          0(     +0) |       4855(     +0) |   -(  -) |          0(     +0) |    0.002 |   99.998 |    0.000 |    0.000
   event | 1983598 |          - |     - |         52(     +0) |         23(     +0) |   -(  -) |          0(     +0) |    0.006 |   99.982 |    0.000 |    0.012
     gui | 1983599 |          - |     - |         27(     +0) |          3(     +0) |   -(  -) |          0(     +0) |    0.163 |   99.528 |    0.000 |    0.309
   waker | 1983490 |          - |     - |          1(     +0) |      10303(     +0) |   -(  -) |          0(     +0) |    0.003 |   99.997 |    0.000 |    0.000

configure ​

Configures the operating system so that it can run Firedancer. See the guide for more information. There are the following stages to each configure command:

  • iavf Configures VFs, clears and installs PF ntuple rules and loads the vfio-pci kernel module required by the iavf network provider.
  • mlx5 Loads the ib_uverbs kernel module required by the mlx5 network provider. Clears leftover XDP ntuple rules, resets the RSS indirection table and channel count to defaults.
  • hugetlbfs Reserves huge and gigantic pages for use by Firedancer and mounts huge page filesystems for then under a path in the configuration TOML file.
  • sysctl Set required kernel parameters.
  • hyperthreads Checks hyperthreaded pair for critical CPU cores.
  • bonding Prepares bonded network devices for XDP networking.
  • ethtool-channels Configures the number of channels on the network device.
  • ethtool-offloads Modify offload feature flags on the network device.
  • ethtool-loopback Disables UDP segmentation on the loopback device.
  • irq-affinity Removes Firedancer tile CPUs from configurable /proc/irq/*/smp_affinity masks.
  • irq-balance Configures the irqbalance daemon to avoid Firedancer tile CPUs. If irqbalance is not running, this stage is a no-op.
  • snapshots Prepares the snapshot download directory.
ArgumentsDescription
--config <path>Path to a configuration TOML file to configure the validator with. This must be the same configuration file the validator will be started with
toml
[hugetlbfs]
    mount_path = "/mnt/.fd"
[layout]
    net_tile_count = 2
[tiles]
    [net]
        interface = "ens3f0"

configure init <stage>... ​

Prepare the operating system environment to run Firedancer. This will reserve and mount the huge page filesystems, set the kernel parameters, and configure the number of combined channels on the network device.

Capabilities
CapabilityReason
rootincrease /proc/sys/vm/nr_hugepages and mount hugetlbfs filesystems. Only applies for the hugetlbfs stage
rootincrease network device channels with ethtool --set-channels. Only applies for the ethtool-channels stage
rootdisable network device offloads with ethtool --offload IFACE FEATURE off. Only applies for the ethtool-offloads stage
rootdisable network device tx-udp-segmentation with ethtool --offload lo tx-udp-segmentation off. Only applies for the ethtool-loopback stage
rootrestore network device defaults and load the ib_uverbs kernel module if needed
CAP_SYS_MODULEload the ib_uverbs kernel module with modprobe when the uverbs interface is unavailable
rootconfigure VFs and PF ntuple rules. Only applies for the iavf stage
CAP_SYS_MODULEload the vfio-pci kernel module with modprobe when the driver is unavailable. Only applies for the iavf stage
CAP_SYS_ADMINset kernel parameters in /proc/sys. Only applies for the sysctl stage
$ firedancer configure init all
NOTICE  hugetlbfs ... unconfigured ... mounts `/mnt/.fd/.huge` and `/mnt/.fd/.gigantic` do not exist
NOTICE  hugetlbfs ... configuring
NOTICE  RUN: `mkdir -p /mnt/.fd/.huge`
NOTICE  RUN: `mount -t hugetlbfs none /mnt/.fd/.huge -o pagesize=2097152,min_size=6155141120`
NOTICE  RUN: `mkdir -p /mnt/.fd/.gigantic`
NOTICE  RUN: `mount -t hugetlbfs none /mnt/.fd/.gigantic -o pagesize=1073741824,min_size=150323855360`
NOTICE  ethtool-channels ... unconfigured ... device `bond0` missing ethtool-channels network configuration
NOTICE  ethtool-channels ... configuring
NOTICE  RUN: `ethtool --set-rxfh-indir enp1s0f0np0 default`
NOTICE  RUN: `ethtool --set-channels enp1s0f0np0 combined 128`
NOTICE  RUN: `ethtool --set-rxfh-indir enp1s0f0np0 start 2 equal 126`
NOTICE  RUN: `ethtool --config-ntuple enp1s0f0np0 flow-type udp4 dst-port 8003 src-ip 0.0.0.0 m 255.255.255.254 queue 0`
WARNING error configuring network device (enp1s0f0np0), ioctl(SIOCETHTOOL,ETHTOOL_SRXCLSRLINS) failed (95-ENOTSUP-operation not supported)
WARNING error configuring network device (bond0), rss_queue_mode "auto" attempted "dedicated" configuration but falling back to "simple".
NOTICE  RUN: `ethtool --set-rxfh-indir enp1s0f0np0 default`
NOTICE  RUN: `ethtool --set-channels enp1s0f0np0 combined 128`
NOTICE  RUN: `ethtool --set-rxfh-indir enp1s0f0np0 default`
NOTICE  RUN: `ethtool --set-rxfh-indir enp1s0f0np0 default`
NOTICE  RUN: `ethtool --set-channels enp1s0f0np0 combined 2`
NOTICE  RUN: `ethtool --set-rxfh-indir enp1s0f0np0 default`
NOTICE  RUN: `ethtool --config-nfc enp1s0f0np0 rx-flow-hash udp4 sdfn`
NOTICE  RUN: `ethtool --set-rxfh-indir enp1s0f1np1 default`
NOTICE  RUN: `ethtool --set-channels enp1s0f1np1 combined 2`
NOTICE  RUN: `ethtool --set-rxfh-indir enp1s0f1np1 default`
NOTICE  RUN: `ethtool --config-nfc enp1s0f1np1 rx-flow-hash udp4 sdfn`
NOTICE  irq-affinity ... unconfigured ... found IRQs overlapping with Firedancer tile CPUs (IRQs: 1,3,4,5,6,7,8,9,10,11,12,13,14,15,22,23,+45 more; tiles: )
NOTICE  irq-affinity ... configuring
NOTICE  kworkers ... unconfigured ... kernel workqueue cpumask includes Firedancer tile CPUs or their isolated siblings 94
NOTICE  kworkers ... configuring
NOTICE  RUN: `echo "fffffff0,03fffff9,fffffff0,00000001" > /sys/devices/virtual/workqueue/cpumask`
NOTICE  kernel workqueue cpumask changed while writing `/sys/devices/virtual/workqueue/cpumask`: fffffe00,40000001,fffff800,00000001 -> fffffff0,03fffff9,fffffff0,00000001 (kernel 7.0.0-34-generic). 
NOTICE  cpuset ... unconfigured ... `/sys/fs/cgroup/fd1` does not exist
NOTICE  cpuset ... configuring
NOTICE  RUN: `echo "+cpuset" > /sys/fs/cgroup/cgroup.subtree_control`
NOTICE  RUN: `mkdir /sys/fs/cgroup/fd1`
NOTICE  RUN: `echo "1-35,65-66,90-99" > /sys/fs/cgroup/fd1/cpuset.cpus`
NOTICE  RUN: `echo "isolated" > /sys/fs/cgroup/fd1/cpuset.cpus.partition`
NOTICE  console ... unconfigured ... console loglevel is 4; kernel messages render console work on the printing CPU
NOTICE  console ... configuring
NOTICE  RUN: `echo "0" > /sys/class/graphics/fbcon/cursor_blink`
NOTICE  RUN: `echo "2" > /proc/sys/kernel/printk`

configure check <stage>... ​

Check if the operating system environment is properly configured. Exits with a non-zero exit code if it is not, after printing relevant diagnostics to stderr.

$ firedancer configure check all
WARNING