Configure cosmovisor
Last updated
Was this helpful?
Last updated
Was this helpful?
π¬ Cosmovisor is a process manager for Cosmos SDK application binaries that automates application binary switch at chain upgrades. It polls the
upgrade-info.json
file that is created by the x/upgrade module at upgrade height, and then can automatically download the new binary, stop the current binary, switch from the old binary to the new one, and finally restart the node with the new binary.
This guide explains the key configuration options for Cosmovisor when running a cheqd node. You can configure these settings via:
Environment variables
A config.toml file
under $DAEMON_HOME/cosmovisor/
(by default) or any other location passed to cosmovisor with --cosmovisor-config
flag
Note: Environment variables always take precedence over values set in the config file, if the
--cosmovisor-config
flag is not passed.
The cheqd node's sets most of these parameters for you in both the daemon service configuration file (cheqd-cosmovisor.service
) and as a system-wide environment variable. It will also create a config.toml file, for consistency purposes. Understanding these settings helps with troubleshooting and advanced setups.
DAEMON_HOME
/home/cheqd/.cheqdnode
Yes
Location of the cosmovisor/
directory.
β
DAEMON_NAME
cheqd-noded
Yes
Name of the node binary. Usually doesnβt need to change.
β
DAEMON_ALLOW_DOWNLOAD_BINARIES
true
No
Allows Cosmovisor to auto-download upgrade binaries. Recommended to be true.
β
DAEMON_DOWNLOAD_MUST_HAVE_CHECKSUM
true
No
Ensures downloaded binaries have checksums. Always true in cheqd upgrade plans.
β
DAEMON_RESTART_AFTER_UPGRADE
true
No
Automatically restarts node after an upgrade.
β
DAEMON_RESTART_DELAY
30s
No
Delay before restart after upgrade. 0s is fine for most setups.
β
DAEMON_SHUTDOWN_GRACE
30s
No
Grace period for clean shutdown. Helps with safe unattended upgrades.
β
DAEMON_POLL_INTERVAL
300s
No
How often to check for upgrade plans.
β
DAEMON_DATA_BACKUP_DIR
DAEMON_HOME
No
Custom directory for pre-upgrade backups. Requires extra storage.
β
UNSAFE_SKIP_BACKUP
true
No
Set to false to enable auto-backups (slower and storage-heavy).
β
DAEMON_PREUPGRADE_MAX_RETRIES
0
No
Max retries for pre-upgrade hook (exit code 31).
β
COSMOVISOR_DISABLE_LOGS
false
No
Disable Cosmovisor logs (not the node logs).
β
COSMOVISOR_COLOR_LOGS
true
No
Enables colored logs for easier readability.
β.
COSMOVISOR_TIMEFORMAT_LOGS
kitchen
No
Time format for logs (e.g., 3:04PM). Other formats: rfc3339, unix, etc.
β
COSMOVISOR_CUSTOM_PREUPGRADE
''
No
Path to a custom pre-upgrade script. It should be located under $DAEMON_HOME/cosmovisor/
.
β
COSMOVISOR_DISABLE_RECASE
false
No
Enforces exact case matching for upgrade plan directories.
β
Backups: Enabling backups can use significant disk space and time. Use with caution, especially on non-pruned nodes.
Custom Pre-upgrade Scripts: Use COSMOVISOR_CUSTOM_PREUPGRADE for advanced automation (e.g., state export).
To set Cosmovisor parameters at the service level, you can edit the systemd service file, typically located at /usr/lib/systemd/system/cheqd-cosmovisor.service
. Here is an example with custom values:
If you decide to use config.toml file instead, feel free to remove environment variables from daemon service file and add --cosmovisor-config
to your config file, i.e. ExecStart=/usr/bin/cosmovisor run start --cosmovisor-config /home/cheqd/.cheqdnode/cosmovisor/config.toml
.
β οΈ Important: If you manually modify this file, the cheqd installer may overwrite your changes. When prompted during future installs, decline the update to preserve your custom settings.
β οΈ Reminder: Like the service file, custom config.toml changes can be overwritten by the installer. Decline updates if youβve made manual modifications.
Log Time Format: kitchen is human-readable. See for more options.
For further details, refer to the official .