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.
| Arguments | Description |
|---|---|
--config <path> | Path to a configuration TOML file to run the validator with |
--standby | Boot as a failover standby using an unstaked identity, see the failover guide |
Capabilities
| Capability | Reason |
|---|---|
CAP_NET_RAW | call socket(2) to bind to a raw socket for use by XDP |
CAP_SYS_ADMIN | call bpf(2) with the BPF_OBJ_GET command to initialize XDP |
CAP_SYS_ADMIN | call unshare(2) with CLONE_NEWUSER to sandbox the process in a user namespace. Only required on kernels which restrict unprivileged user namespaces |
CAP_SETUID | call setresuid(2) to switch uid to the sandbox user. Not required if the UID is already the same as the sandbox UID |
CAP_SETGID | call setresgid(2) to switch gid to the sandbox user. Not required if the GID is already the same as the sandbox GID |
CAP_SYS_RESOURCE | call 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_RESOURCE | call setpriority(2) to increase thread priorities. Not required if the process already has a nice value of -19 |
CAP_SYS_RESOURCE | call 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_SERVICE | call 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.
| Arguments | Description |
|---|---|
--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
| Capability | Reason |
|---|---|
CAP_SYS_ADMIN | call unshare(2) with CLONE_NEWUSER to sandbox the process in a user namespace. Only required on kernels which restrict unprivileged user namespaces |
CAP_SETUID | call setresuid(2) to switch uid to the sandbox user. Not required if the UID is already the same as the sandbox UID |
CAP_SETGID | call setresgid(2) to switch gid to the sandbox user. Not required if the GID is already the same as the sandbox GID |
CAP_SYS_RESOURCE | call 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[0K
tile | tid | stale | heart | nivcsw | nvcsw | in backp | backp cnt | % hkeep | % wait | % backp | % finish[0K
---------+---------+------------+-------+---------------------+---------------------+----------+---------------------+----------+----------+----------+----------[0K
netlnk | 1983482 | - | - | 1( +0) | 92592( +0) | -( -) | 0( +0) | 0.002 | 99.998 | 0.000 | 0.000[0K
net | 1983506 | - | - | 29( +0) | 8( +0) | -( -) | 0( +0) | 0.684 | 99.316 | 0.000 | 0.000[0K
net | 1983508 | - | - | 27( +0) | 4( +0) | -( -) | 0( +0) | 0.678 | 99.322 | 0.000 | 0.000[0K
metric | 1983483 | - | - | 0( +0) | 92626( +0) | -( -) | 0( +0) | 0.003 | 99.997 | 0.000 | 0.000[0K
diag | 1983484 | - | - | 0( +0) | 4989( +0) | -( -) | 0( +0) | 0.003 | 99.997 | 0.000 | 0.000[0K
ipecho | 1983486 | - | - | 3( +0) | 92511( +0) | -( -) | 1( +0) | 0.003 | 99.997 | 0.000 | 0.000[0K
gossvf | 1983512 | - | - | 27( +0) | 3( +0) | -( -) | 0( +0) | 0.049 | 99.951 | 0.000 | 0.000[0K
gossip | 1983511 | - | - | 37( +0) | 5( +0) | -( -) | 0( +0) | 0.092 | 99.897 | 0.000 | 0.011[0K
shred | 1983514 | - | - | 26( +0) | 5( +0) | -( -) | 0( +0) | 0.086 | 99.914 | 0.000 | 0.000[0K
repair | 1983515 | - | - | 30( +0) | 5( +0) | -( -) | 0( +0) | 0.086 | 99.914 | 0.000 | 0.000[0K
rserve | 1983517 | - | - | 61( +0) | 5( +0) | -( -) | 0( +0) | 0.491 | 99.509 | 0.000 | 0.000[0K
replay | 1983528 | - | - | 27( +0) | 5( +0) | -( -) | 0( +0) | 2.738 | 97.262 | 0.000 | 0.000[0K
accdb | 1983529 | - | - | 40( +0) | 55( +0) | -( -) | 0( +0) | 0.018 | 99.982 | 0.000 | 0.000[0K
execrp | 1983531 | - | - | 27( +0) | 64( +0) | -( -) | 0( +0) | 0.019 | 99.981 | 0.000 | 0.000[0K
execrp | 1983532 | - | - | 27( +0) | 67( +0) | -( -) | 0( +0) | 0.020 | 99.980 | 0.000 | 0.000[0K
execrp | 1983534 | - | - | 26( +0) | 65( +0) | -( -) | 0( +0) | 0.020 | 99.980 | 0.000 | 0.000[0K
execrp | 1983535 | - | - | 26( +0) | 68( +0) | -( -) | 0( +0) | 0.020 | 99.980 | 0.000 | 0.000[0K
execrp | 1983538 | - | - | 29( +0) | 60( +0) | -( -) | 0( +0) | 0.020 | 99.980 | 0.000 | 0.000[0K
execrp | 1983547 | - | - | 25( +0) | 59( +0) | -( -) | 0( +0) | 0.020 | 99.980 | 0.000 | 0.000[0K
execrp | 1983555 | - | - | 25( +0) | 63( +0) | -( -) | 0( +0) | 0.024 | 99.976 | 0.000 | 0.000[0K
execrp | 1983556 | - | - | 25( +0) | 63( +0) | -( -) | 0( +0) | 0.020 | 99.980 | 0.000 | 0.000[0K
execrp | 1983554 | - | - | 26( +0) | 58( +0) | -( -) | 0( +0) | 0.023 | 99.977 | 0.000 | 0.000[0K
execrp | 1983557 | - | - | 24( +0) | 59( +0) | -( -) | 0( +0) | 0.022 | 99.978 | 0.000 | 0.000[0K
votor | 1983566 | - | - | 27( +0) | 3( +0) | -( -) | 0( +0) | 0.110 | 99.890 | 0.000 | 0.000[0K
quic | 1983569 | - | - | 28( +0) | 15( +0) | -( -) | 0( +0) | 0.004 | 99.996 | 0.000 | 0.000[0K
verify | 1983568 | - | - | 27( +0) | 16( +0) | -( -) | 0( +0) | 6.555 | 93.445 | 0.000 | 0.000[0K
verify | 1983570 | - | - | 27( +0) | 16( +0) | -( -) | 0( +0) | 6.543 | 93.457 | 0.000 | 0.000[0K
verify | 1983572 | - | - | 26( +0) | 15( +0) | -( -) | 0( +0) | 6.625 | 93.375 | 0.000 | 0.000[0K
dedup | 1983573 | - | - | 27( +0) | 8( +0) | -( -) | 0( +0) | 0.398 | 99.602 | 0.000 | 0.000[0K
resolv | 1983575 | - | - | 26( +0) | 17( +0) | -( -) | 0( +0) | 0.102 | 99.898 | 0.000 | 0.000[0K
pack | 1983584 | - | - | 28( +0) | 16( +0) | -( -) | 0( +0) | 0.101 | 15.631 | 0.000 | 84.268[0K
execle | 1983586 | - | - | 24( +0) | 48( +0) | -( -) | 0( +0) | 0.057 | 99.943 | 0.000 | 0.000[0K
execle | 1983585 | - | - | 27( +0) | 51( +0) | -( -) | 0( +0) | 0.058 | 99.942 | 0.000 | 0.000[0K
motor | 1983587 | - | - | 24( +0) | 44( +0) | -( -) | 0( +0) | 0.044 | 99.956 | 0.000 | 0.000[0K
sign | 1983593 | - | - | 27( +0) | 3( +0) | -( -) | 0( +0) | 0.045 | 99.955 | 0.000 | 0.000[0K
sign | 1983594 | - | - | 40( +0) | 4( +0) | -( -) | 0( +0) | 0.017 | 99.983 | 0.000 | 0.000[0K
rpc | 1983595 | - | - | 75( +0) | 3( +0) | -( -) | 0( +0) | 0.049 | 99.951 | 0.000 | 0.000[0K
admin | 1983489 | - | - | 0( +0) | 4855( +0) | -( -) | 0( +0) | 0.002 | 99.998 | 0.000 | 0.000[0K
event | 1983598 | - | - | 52( +0) | 23( +0) | -( -) | 0( +0) | 0.006 | 99.982 | 0.000 | 0.012[0K
gui | 1983599 | - | - | 27( +0) | 3( +0) | -( -) | 0( +0) | 0.163 | 99.528 | 0.000 | 0.309[0K
waker | 1983490 | - | - | 1( +0) | 10303( +0) | -( -) | 0( +0) | 0.003 | 99.997 | 0.000 | 0.000[0Kconfigure
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:
iavfConfigures VFs, clears and installs PF ntuple rules and loads thevfio-pcikernel module required by the iavf network provider.mlx5Loads theib_uverbskernel module required by the mlx5 network provider. Clears leftover XDP ntuple rules, resets the RSS indirection table and channel count to defaults.hugetlbfsReserves huge and gigantic pages for use by Firedancer and mounts huge page filesystems for then under a path in the configuration TOML file.sysctlSet required kernel parameters.hyperthreadsChecks hyperthreaded pair for critical CPU cores.bondingPrepares bonded network devices for XDP networking.ethtool-channelsConfigures the number of channels on the network device.ethtool-offloadsModify offload feature flags on the network device.ethtool-loopbackDisables UDP segmentation on the loopback device.irq-affinityRemoves Firedancer tile CPUs from configurable/proc/irq/*/smp_affinitymasks.irq-balanceConfigures the irqbalance daemon to avoid Firedancer tile CPUs. If irqbalance is not running, this stage is a no-op.snapshotsPrepares the snapshot download directory.
| Arguments | Description |
|---|---|
--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 |
[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
| Capability | Reason |
|---|---|
root | increase /proc/sys/vm/nr_hugepages and mount hugetlbfs filesystems. Only applies for the hugetlbfs stage |
root | increase network device channels with ethtool --set-channels. Only applies for the ethtool-channels stage |
root | disable network device offloads with ethtool --offload IFACE FEATURE off. Only applies for the ethtool-offloads stage |
root | disable network device tx-udp-segmentation with ethtool --offload lo tx-udp-segmentation off. Only applies for the ethtool-loopback stage |
root | restore network device defaults and load the ib_uverbs kernel module if needed |
CAP_SYS_MODULE | load the ib_uverbs kernel module with modprobe when the uverbs interface is unavailable |
root | configure VFs and PF ntuple rules. Only applies for the iavf stage |
CAP_SYS_MODULE | load the vfio-pci kernel module with modprobe when the driver is unavailable. Only applies for the iavf stage |
CAP_SYS_ADMIN | set 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