Skip to main content

Configuring Cosmovisor

Installing Cosmovisor

Use 'go install' Method

You can get the latest version of Cosmovisor by executing this command:

go install

or a previous version by executing this command:

go install

Building Manually

Alternatively, Cosmovisor can be installed from the source code. Clone the cosmos-sdk repository, navigate to the required version and build the tool using these commands:

git clone
cd cosmos-sdk
git checkout cosmovisor/v1.5.0
make cosmovisor

After successful compilation, Cosmovisor will be available in the /cosmovisor directory. You might want to copy it into your system's PATH as shown:

cp cosmovisor/cosmovisor ~/go/bin/cosmovisor

To validate your CosmoVisor version, run:

cosmovisor version

Directory Structure

├── current -> genesis or upgrades/<name>
├── genesis
│ └── bin
└── upgrades
└── <name>
├── bin
└── upgrade-info.json

Initializing Cosmovisor

You'll need to rename your binary to templated:

mv templated.<version>-<platform> templated

Next, define the following environment variables:

export DAEMON_NAME=templated
export DAEMON_HOME=~/.template

You can set up the directory structure using:

cosmovisor init <path to executable>

Remember to point DAEMON_HOME to the home directory of the validator because CosmoVisor references /data/ for upgrade information. DAEMON_NAME should be templated.

Running Cosmovisor

Cosmovisor serves as a lean interface around Cosmos applications. Here's how to initiate a testnet validator with Cosmovisor:

cosmovisor run start --log-level info


Generally, cosmovisor requires that the system administrator place all relevant binaries on disk before the upgrade happens. However, for people who don't need such control and want an automated setup (maybe they are syncing a non-validating fullnode and want to do little maintenance), there is another option.

NOTE: we don't recommend using auto-download because it doesn't verify in advance if a binary is available. If there will be any issue with downloading a binary, the cosmovisor will stop and won't restart an App (which could lead to a chain halt).

If DAEMON_ALLOW_DOWNLOAD_BINARIES is set to true, and no local binary can be found when an upgrade is triggered, cosmovisor will attempt to download and install the binary itself based on the instructions in the info attribute in the data/upgrade-info.json file. The files is constructed by the x/upgrade module and contains data from the upgrade Plan object. The Plan has an info field that is expected to have one of the following two valid formats to specify a download:

  1. Store an os/architecture -> binary URI map in the upgrade plan info field as JSON under the "binaries" key. For example:

    "binaries": {

    You can include multiple binaries at once to ensure more than one environment will receive the correct binaries:

    "binaries": {

    When submitting this as a proposal ensure there are no spaces. An example command using templated could look like:

    > templated tx gov submit-proposal software-upgrade \
    'name' \
    --upgrade-height 2142000 \
    --upgrade-info '{"binaries":{"linux/amd64":"","linux/arm64":""},"urls":{"docs":""}}' \
    --from template10uu75g7zl0gnzt0wz46htgqnl5ml27dnthcztx
  2. Store a link to a file that contains all information in the above format (e.g. if you want to specify lots of binaries, changelog info, etc. without filling up the blockchain). For example:

When cosmovisor is triggered to download the new binary, cosmovisor will parse the "binaries" field, download the new binary with go-getter, and unpack the new binary in the upgrades/<name> folder so that it can be run as if it was installed manually.

Note that for this mechanism to provide strong security guarantees, all URLs should include a SHA 256/512 checksum. This ensures that no false binary is run, even if someone hacks the server or hijacks the DNS. go-getter will always ensure the downloaded file matches the checksum if it is provided. go-getter will also handle unpacking archives into directories (in this case the download link should point to a zip file of all data in the bin directory).

To properly create a sha256 checksum on linux, you can use the sha256sum utility. For example:

sha256sum ./testdata/repo/zip_directory/

The result will look something like the following: 29139e1381b8177aec909fab9a75d11381cab5adf7d3af0c05ff1c9c117743a7.

You can also use sha512sum if you would prefer to use longer hashes, or md5sum if you would prefer to use broken hashes. Whichever you choose, make sure to set the hash algorithm properly in the checksum argument to the URL.