EOS Environment Setup Guide: Private Chain, Wallet, Keys, and Accounts

Setting up an EOS development environment is a crucial first step for blockchain developers exploring decentralized applications (dApps) on the EOSIO platform. This comprehensive guide walks you through launching a private chain, creating and managing wallets, importing keys, and setting up accounts — all using EOS version 1.0.5 as a foundation.

Whether you're building smart contracts or testing dApp logic, mastering these core components ensures a smooth development workflow. We’ll break down complex concepts into digestible parts and provide practical commands with real-world context.

Understanding the EOSIO Architecture

EOSIO operates through several modular programs that work together to power the blockchain ecosystem. The three primary tools you’ll interact with are:

• nodeos – The core daemon responsible for running the EOSIO node, producing blocks, and maintaining the blockchain state.
• cleos – A command-line interface (CLI) tool used to interact with the blockchain, manage wallets, and execute transactions.
• keosd – A wallet management daemon that securely stores private keys and handles transaction signing.

These components form the backbone of any EOSIO-based network. When setting up your private chain, proper coordination between them is essential.

Additionally, eosiocpp serves as the compiler for writing and deploying smart contracts in C++.

👉 Discover how blockchain developers streamline wallet and node operations.

Core Concepts: Wallets, Keys, Accounts, and Contracts

To avoid confusion, let’s clarify how these elements relate to each other using a real-world analogy.

1. Wallets Are Like Property Managers

Think of a wallet as a property manager who oversees multiple properties (accounts) and holds various keys (private/public key pairs). One system can host many wallets, each isolated for security.

Use this command to create a wallet:

cleos wallet create -n your_wallet_name

2. Keys Are Digital Locks and Keys

Each key pair consists of a public key (shared openly) and a private key (kept secret). Think of the public key as a lock visible on a door, while the private key is what actually opens it.

You import private keys into your wallet like this:

cleos wallet import [your_private_key] -n your_wallet_name

3. Accounts Are Like Houses

An account is analogous to a house. It can have two types of access:

• Owner Key: Full control — like owning the title deed. With this key, you can change everything about the account.
• Active Key: Limited access — typically allows fund transfers but not ownership changes.

This mirrors real-life scenarios where a homeowner (owner key) grants rental access (active key) to tenants without handing over full control.

Create an account with:

cleos create account eosio [new_account] [owner_public_key] [active_public_key]

EOS accounts must be 12 characters or fewer and use only lowercase letters a–z, numbers 1–5, and dots.

Step-by-Step Setup Guide

Follow this structured process to set up your local EOS private chain environment.

Launching the Keosd Wallet Daemon

Before starting the blockchain node, launch keosd to manage wallet operations:

keosd --http-server-address=127.0.0.1:8900

This starts the wallet service on port 8900 and creates a default wallet directory at ~/eosio-wallet.

🔔 Critical Note: Starting from EOS v1.0.5, keosd must be running before nodeos, or wallet creation will fail.

Expected output includes API endpoints being registered:

starting wallet_api_plugin
add api url: /v1/wallet/create
add api url: /v1/wallet/import_key
...

If you encounter connection issues when creating wallets:

ps -ef | grep keosd
kill -9 [process_id]
keosd --http-server-address=127.0.0.1:8900

👉 Learn best practices for secure blockchain wallet management.

Starting Your Private Blockchain Node

In a new terminal window, start nodeos with required plugins:

cd ~/eos/build/programs/nodeos
./nodeos -e -p eosio \
  --plugin eosio::wallet_plugin \
  --plugin eosio::chain_api_plugin \
  --plugin eosio::history_api_plugin \
  --replay-blockchain

Key Parameters Explained:

• -e: Enables stale block production (useful during development).
• -p eosio: Sets the block producer name.
• --plugin eosio::wallet_plugin: Ensures wallet data persists across restarts.
• --replay-blockchain: Clears previous blockchain state and rebuilds from logs.

If you see errors like:

database dirty flag set: replay required

Resolve by deleting the data folder:

rm -r ~/.local/share/eosio/nodeos/data

After restarting nodeos, unlock your wallet:

cleos wallet unlock -n your_wallet_name

Creating and Managing Wallets

Create a named wallet:

cleos wallet create -n duncanwang

Output includes a password — save it securely:

Creating wallet: duncanwang
PW5JMZdES2Cds5LsPRUBRo2THEXpbFSM17Xmcd2XWG7XBd49wveTo

Verify your wallet exists:

cleos wallet list

Asterisk (*) indicates an unlocked wallet.

Common Issues & Fixes:

Issue: "Wallet already exists" but not visible in list
Cause: Missing wallet_plugin during nodeos startup
Fix: Restart nodeos with --plugin eosio::wallet_plugin

Issue: Wallet missing after node restart
Solution: Use cleos wallet open -n duncanwang to reload it manually.

Importing System Account Keys

The default system account eosio uses predefined keys found in config.ini:

#signature-provider = EOS6MRyAjQq8ud7hVNYcfnVPJqcVpscN5So8BhtHuGYqET5GDW5CV=KEY:5KQwrPbwdL6PhXujxW37FSSQZ1JiwsST4cqQzDeyXtP79zkvFD3

Import the private key:

cleos wallet import 5KQwrPbwdL6PhXujxW37FSSQZ1JiwsST4cqQzDeyXtP79zkvFD3 -n duncanwang

Check account details:

cleos get account eosio

Output shows permissions, memory quota, and bandwidth — all set to unlimited in local environments.

Deploying the Bios Contract

With the eosio account unlocked, deploy the default eosio.bios contract to enable system-level functions:

cleos set contract eosio build/contracts/eosio.bios -p eosio

This transaction performs two actions:

• eosio::setcode: Uploads the contract bytecode.
• eosio::setabi: Defines the interface for interacting with the contract.

Output confirms execution:

executed transaction: f4c1cc4e953710645a4849eb41cf92d9d3881c756b227323a3ade221e3807fbb
warning: transaction executed locally, but may not be confirmed by the network yet

In production chains, this role is filled by eosio.system, but eosio.bios suffices for testing.

Generating and Using New Key Pairs

Generate a fresh key pair:

cleos create key

Sample output:

Private key: 5JZQmnt6ZtEzUADswgKgBwMp9qAwTSNM9JFHPRFu1FjrLjj49g7
Public key: EOS6EHAzvrpQ4wo1BPcAk86X6aGDARZgqTcAq1mJRF1SxEYgNGWN1

Import the private key into your wallet:

cleos wallet import 5JZQmnt6ZtEzUADswgKgBwMp9qAwTSNM9JFHPRFu1FjrLjj49g7 -n duncanwang

Verify imported keys:

cleos wallet keys

You should see both your new and system keys listed.

Creating a New Account

Now create a user account using the eosio system account:

cleos create account eosio boss EOS6EHAzvrpQ4wo1BPcAk86X6aGDARZgqTcAq1mJRF1SxEYgNGWN1 EOS6EHAzvrpQ4wo1BPcAk86X6aGDARZgqTcAq1mJRF1SxEYgNGWN1

Success output:

executed transaction: cb6801fe82816f94b447cbfb903ae8e9477f5c99920322d679a9c8c04347e536
## eosio <= eosio::newaccount ...

If you receive error 3050000: action exception, check if the account already exists:

cleos get accounts [public_key]

Account names must follow strict rules:

• Up to 12 characters long.
• Only lowercase letters (a–z), numbers (1–5), and dots allowed.

Frequently Asked Questions (FAQ)

Q: Why do I need to run keosd before nodeos?

A: From EOS v1.0.5 onward, the wallet plugin requires keosd to be active before nodeos starts. Otherwise, wallet creation fails due to missing backend services.

Q: What’s the difference between Owner and Active keys?

A: The Owner key grants full control over the account, including changing keys and permissions. The Active key allows transaction signing (e.g., token transfers) but cannot alter ownership settings.

Q: How do I recover a lost wallet password?

A: There is no recovery method. The password encrypts your private keys. If lost, you must recreate the wallet and re-import keys from backup.

Q: Can I use the same key for Owner and Active permissions?

A: Yes, especially in development. However, best practice is to use separate keys for enhanced security in production environments.

Q: Why does my wallet disappear after restarting nodeos?

A: Ensure you’re launching nodeos with --plugin eosio::wallet_plugin. Without it, wallet data isn't loaded automatically. You may also need to manually open it with cleos wallet open.

Q: Where are wallet files stored?

A: By default, wallets are saved in ~/eosio-wallet/ as .wallet files (e.g., duncanwang.wallet). You can customize this path using --wallet-dir.

Final Steps and Next Actions

You’ve now successfully:

• Launched a local EOS private chain.
• Created and managed a secure wallet.
• Imported system and custom keys.
• Deployed essential contracts.
• Created a functional user account.

With this foundation in place, you're ready to deploy your first smart contract — such as a "Hello World" dApp — and begin deeper exploration of EOSIO’s capabilities.

Stay updated with official EOSIO GitHub issues for troubleshooting tips and version-specific fixes beyond v1.0.5.

👉 Explore advanced tools for blockchain developers working with EOSIO and other protocols.