This document will help you get a kava network up and running locally on your machine. It uses a CLI tool call
kvtool that manages the configuration and initial setup of a network. The tool uses docker containers to run a Kava network with some optional configuration.
You must have the following tools:
Ensure Go is setup in your PATH
Once Go & Docker are installed, update your bash_profile to include the go path.
Make sure to source your bash profile or restart it for the changes to take place.
Getting The Kava Repository & Development Tools
Once you have the core tools installed & set up, its now time to get the following repositories from Github:
Set Up a Local Blockchain
Now that you have set up all the tools & repositories in your local machine its finally time to set up a local blockchain.
- Open a terminal and change into the
- Ensure Docker is running.
make installin your terminal which will install
kvtoolin your machine.
kvtool testnet bootstrap. By default, this command will initialize a docker container running the code of the current master branch of
Kava is now running on your local machine! The endpoints are publically exposed to your localhost:
- RPC: http://localhost:26657
- REST: http://localhost:1317
- GRPC: http://localhost:9090
- GRPC Websocket: http://localhost:9091
- EVM JSON-RPC: http://localhost:8545
- EVM Websocket: http://localhost:8546
To interact with the network you can use
kava CLI from your local machine by setting the
kava --node http://localhost:26657 status
However, it is likely more convenient to run the
kava CLI directly in the container. This ensures you are running a compatible version of the CLI and gives you access to the accounts configured in the local chain. To do this, add the following alias:
alias dkava='docker exec -it generated_kavanode_1 kava'
Note that for some architectures or docker versions, the containers are generated with hyphens (
-) instead of underscores (
This alias execs into the container and runs
kava. From there you have access to accounts.
NOTE: Before Kava 9 (
kava binary was two separate binaries. One for running the chain (
kvd) and a separate one for the cli (
kvcli). If running older versions, you will need to use
kvcli instead of
Example: Create a new account & fund it:
$ dkava keys add my-test-account
- name: my-test-account
**Important** write this mnemonic phrase in a safe place.
It is the only way to recover your account if you ever forget your password.
sign sausage monster group rain kite stage cat brush arm result chalk join hamster cup mass chuckle swing inflict april salmon deposit habit grid
$ dkava tx bank send whale kava17fuj33p6y472j3kplsjdz966xlw6cdhwqzl8rl 1000000000ukava --gas-prices 0.01ukava -y
The above creates a new randomly generated account (
kava17fuj33p6y472j3kplsjdz966xlw6cdhwqzl8rl) and funds it from the
Additionally, you can just exec into a shell in the container. Kvtool manages everything with docker-compose and it exposes a command that will run docker-compose in the required location. The running configuration is in
$ kvtool testnet dc -- exec kavanode bash
bash-5.1# kava --help
Daemon and CLI for the Kava blockchain.
add-genesis-account Add a genesis account to genesis.json
assert-invariants Validates that the input genesis file is valid and invariants pass
collect-gentxs Collect genesis txs and output a genesis.json file
config Create or query an application CLI configuration file
debug Tool for helping with debugging your application
export Export state to JSON
gentx Generate a genesis tx carrying a self delegation
help Help about any command
init Initialize private validator, p2p, genesis, and application configuration files
keys Manage your application's keys
migrate Migrate genesis from v0.17 to v0.18
query Querying subcommands
start Run the full node
status Query remote node for status
tendermint Tendermint subcommands
tx Transactions subcommands
validate-genesis validates the genesis file at the default location or at the location passed as an arg
version Print the application binary version information
-h, --help help for kava
--home string directory for config and data (default "/root/.kava")
--log_format string The logging format (json|plain) (default "plain")
--log_level string The logging level (trace|debug|info|warn|error|fatal|panic) (default "info")
--trace print out full stack trace on errors
Use "kava [command] --help" for more information about a command.
Config templates control the initial genesis file used to start the network and contain the . They also include all the account keys for accounts configured in the docker container.
The available config templates can be found in
kvtool runs with the
master config template which defaults to the
master docker tag which is autodeployed whenever a commit is made to the master branch of
kava. Occasionally, the configuration may become out of sync with what is currently on the master branch of kava. In these cases, it can be useful to use a template that uses a fixed docker tag with a working configuration:
For example, running a network with v0.21 of
$ kvtool testnet bootstrap --kava.configTemplate v0.21
This won't be subject to changes breaking changes of
kava that have yet to be updated in
kvtool's master template.
Docker Image Tag
Additionally, all kava confiug templates support overriding the docker image tag. A full list of available tags is available on Docker Hub.
You can override the tag by setting the
KAVA_TAG environment variable. For instance running the master template with a fixed kava version of
KAVA_TAG=v0.21.0 kvtool testnet bootstrap
Note that at the time you're reading this, the master template's genesis and configuration may not be compatible with kava version v0.21.0.
This is also useful for the development of
kava itself. You can build a docker image, give it a tag like
kava/kava:TAG_HERE, and then run a local network with the built image. There is a shortcut for this in the
# the docker-build command builds the docker image and tags it `kava/kava:local`
# then you can run a network with the image you created
KAVA_TAG=local kvtool testnet bootstrap
But wait! There's more!
kvtool has a lot more functionality than simply running a single local kava network. Be sure to use its
--help command and check out the repo's README.md.
It supports things like running two networks with an open IBC channel, chain upgrades, and more.
Be sure to check out our guide on developing for Kava's EVM.
kvtool is beta software. 😊 Some of its features may not always work as expected. Generally, the commands used in this guide are frequently used enough to be reliable. If you run into any problems, please reach out to us on Discord or by opening an issue.