# Cosmosvisor Quick Start
cosmovisor is a small process manager around Cosmos SDK binaries that monitors the governance module via stdout to see if there's a chain upgrade proposal coming in. If it see a proposal that gets approved it can be run manually or automatically to download the new code, stop the node, run the migration script, replace the node binary, and start with the new genesis file.
go get github.com/cosmos/cosmos-sdk/cosmovisor/cmd/cosmovisor
# Command Line Arguments And Environment Variables
All arguments passed to the
cosmovisor program will be passed to the current daemon binary (as a subprocess).
It will return
/dev/stderr of the subprocess as its own. Because of that, it cannot accept
any command line arguments, nor print anything to output (unless it terminates unexpectedly before executing a
cosmovisor reads its configuration from environment variables:
DAEMON_HOMEis the location where upgrade binaries should be kept (e.g.
DAEMON_NAMEis the name of the binary itself (eg.
DAEMON_ALLOW_DOWNLOAD_BINARIES(optional) if set to
truewill enable auto-downloading of new binaries (for security reasons, this is intended for full nodes rather than validators).
DAEMON_RESTART_AFTER_UPGRADE(optional) if set to
trueit will restart the sub-process with the same command line arguments and flags (but new binary) after a successful upgrade. By default,
cosmovisordies afterwards and allows the supervisor to restart it if needed. Note that this will not auto-restart the child if there was an error.
# Data Folder Layout
$DAEMON_HOME/cosmovisor is expected to belong completely to
subprocesses that are controlled by it. The folder content is organised as follows:
Each version of the Cosmos SDK application is stored under either
upgrades/<name>, which holds
along with any other needed files such as auxiliary client programs or libraries.
current is a symbolic link to the currently
active folder (so
current/bin/$DAEMON_NAME is the currently active binary).
name variable in
upgrades/<name> holds the URI-encoded name of the upgrade as specified in the upgrade module plan.
Please note that
$DAEMON_HOME/cosmovisor just stores the binaries and associated program code.
cosmovisor binary can be stored in any typical location (eg
/usr/local/bin). The actual blockchain
program will store it's data under their default data directory (e.g.
$HOME/.gaiad) which is independent of
$DAEMON_HOME. You can choose to set
$DAEMON_HOME to the actual binary's home directory and then end up
with a configuation like the following, but this is left as a choice to the system admininstrator for best
The system administrator admin is responsible for:
- installing the
cosmovisorbinary and configure the host's init system (e.g.
launchd, etc) along with the environmental variables appropriately;
- installing the
- installing the
cosmovisor will set the
current link to point to
genesis at first start (when no
current link exists) and handles
binaries switch overs at the correct points in time, so that the system administrator can prepare days in advance and relax at upgrade time.
Note that blockchain applications that wish to support upgrades may package up a genesis
cosmovisor tarball with this information,
just as they prepare the genesis binary tarball. In fact, they may offer a tarball will all upgrades up to current point for easy download
for those who wish to sync a fullnode from start.
DAEMON specific code and operations (e.g. tendermint config, the application db, syncing blocks, etc) are performed as normal.
Application binaries' directives such as command-line flags and environment variables work normally.
# Example: simd
The following instructions provide a demonstration of
cosmovisor's integration with the
shipped along the Cosmos SDK's source code.
Create a new key and setup the
Set the required environment variables:
cosmovisor’s genesis folders and deploy the binary:
For the sake of this demonstration, we would amend
.simapp/config/genesis.json to a reduced time ~5 minutes (300s) and eventually launch
Submit a software upgrade proposal:
Query the proposal to ensure it was correctly broadcast and added to a block:
Yes vote for the upgrade proposal:
For the sake of this demonstration, we will hardcode a modification in
simapp to simulate a code change.
simapp/app.go, find the line containing the upgrade Keeper initialisation, it should look like
app.UpgradeKeeper = upgradekeeper.NewKeeper(skipUpgradeHeights, keys[upgradetypes.StoreKey], appCodec, homePath).
After that line, add the following snippet:
Now recompile a new binary and place it in
The upgrade will occur automatically at height 100.