DEV Community

Cover image for Setting Up a Local WAX Development Environment
Ivan Montiel
Ivan Montiel

Posted on • Updated on

Setting Up a Local WAX Development Environment


In this section, we will go over the prerequisites we will need to start writing Smart Contracts and interacting with the WAX blockchain.

We will use Docker and using the official WAX development image to create a container. Then we’ll go over setting up a local WAX blockchain.

The purpose of this is to create a local blockchain that we can use to deploy Smart Contracts to without having to deploy to a testnet or the mainnet blockchain.

Installing Docker

WAX makes it easy to get started with contract development by offering a few Docker Images that we can use.

Docker is a container platform, similar to virtual machines. It lets you run software, applications, and other operating systems in an isolated environment on your computer. Throughout this class, we will be using Docker to develop our smart contracts.

If you don’t have Docker installed, go to, Get Started, and download Docker Desktop for your operating system.

Once installed, we can continue.

Setting up a WAX Development Container

I will also be using the Mac terminal to run commands, most commands should translate 1 to 1 to Windows, but I will make notes where they might be different.

First, let’s open a terminal and set up our workspace. For this tutorial, I’m just going to create a folder called wax-workspace that I will be working in:

mkdir ~/wax-workspace
cd ~/wax-workspace
Enter fullscreen mode Exit fullscreen mode

For Windows, use the bash terminal and you should be able to create a folder and change directories to it using the same commands as above.

Let’s pull the WAX development image:

docker pull waxteam/dev
Enter fullscreen mode Exit fullscreen mode

Once we have the image, we can run it:

docker run -it --name wax-tutorial --publish 8888:8888 -v $(pwd):/wax waxteam/dev bash
Enter fullscreen mode Exit fullscreen mode

This command will start the Docker image, creating a container. It also will change our terminal’s context to be within the container. From here, if we run a command, it will run in the isolated environment that has software already installed for us to develop WAX apps.

Creating a Local Blockchain

In this section, we will set up our local WAX Container with a wallet, account, and a local blockchain. The WAX development Docker image already has the tools we need to use installed on it.

The first tool is keosd , which is a key manager service for storing private keys and signing digital messages. We need to run this to store and use our keys for our wallet.

Let’s start keosd in our docker container:

keosd &
Enter fullscreen mode Exit fullscreen mode

The next tool we’ll use is nodeos, the core service that runs our WAX node. It can be configured to process smart contracts, validate transactions, and produce blocks.

nodeos -e -p eosio \
--plugin eosio::producer_plugin 
--plugin eosio::chain_api_plugin \
--plugin eosio::http_plugin \
--access-control-allow-origin='*' \
--contracts-console \
--http-validate-host=false \
--http-server-address= \
--verbose-http-errors >> nodeos.log 2>&1 &

Enter fullscreen mode Exit fullscreen mode

The above command initializes all the basic plugins, sets the server address, and adds contract debugging and logging.

One other command we will be using is cleos. This is a command line tool that interfaces with the REST API exposed by nodeos, which we just started.

We can test that our WAX node is running correctly by pinging it from a new terminal (outside of the context of our docker image):

curl --request POST \
  --url \
  --header 'content-type: application/x-www-form-urlencoded; charset=UTF-8'

Enter fullscreen mode Exit fullscreen mode

We have a local WAX blockchain running at this point!

Creating a Local Wallet

Now that our key service is running and our node is running, we can create a wallet to store our public/private key pairs that we will use later to deploy smart contracts and interact with them.

First, let’s create a wallet:

cleos wallet create -n testwallet --file ./secrets
Enter fullscreen mode Exit fullscreen mode

For simplicity, we write the password out to a file: ./secrets. Never share this file.

Next let’s open our wallet. Wallets start closed by default, and need to be opened to interact with them:

cleos wallet open -n testwallet
Enter fullscreen mode Exit fullscreen mode

We can close our wallet with:

cleos wallet close -n testwallet
Enter fullscreen mode Exit fullscreen mode

But let’s keep our wallet open for the section section.

Now that our wallet is open, let’s unlock the wallet:

cleos wallet unlock -n testwallet --password="$(cat ./secrets)"
Enter fullscreen mode Exit fullscreen mode

Before being able to interact with your wallet, you will frequently need to unlock it. Keep this command handy.

Creating a Local Account

We are going to create a local account for our local blockchain. To continue, we are first going to import a special default system user into our local blockchain wallet:

cleos wallet import --private-key 5KQwrPbwdL6PhXujxW37FSSQZ1JiwsST4cqQzDeyXtP79zkvFD3
Enter fullscreen mode Exit fullscreen mode

This special default system user will let us create accounts and deploy smart contracts to our local blockchain without having to worry about staking any WAX.

Let’s create a local user next.

cleos create account eosio guestbook123 EOS6MRyAjQq8ud7hVNYcfnVPJqcVpscN5So8BhtHuGYqET5GDW5CV
Enter fullscreen mode Exit fullscreen mode

You can verify that the account was successfully created with:

cleos get account guestbook123
Enter fullscreen mode Exit fullscreen mode

Example output:

Screenshot of example cleos output

One last thing we need to do is add the add-code permission to our account. This will let us deploy and run Smart Contracts to this account:

cleos set account permission guestbook123 active --add-code
Enter fullscreen mode Exit fullscreen mode


In this section, we went over creating a local blockchain development environment using Docker and the official WAX development image. In a container using that image, we started our local blockchain, created a local wallet, and set up an account on our local blockchain.

In the next section, we’ll go over using the WAX testnet.

WAX Testnet Setup


Get this entire WAX tutorial as an e-book on Amazon.

Additional Links

Top comments (0)