Skip to main content

​
Introduction

The SSV Node CLI (ssvnode) provides commands for running and managing SSV operators. It includes tools for:
  • Running an SSV operator node
  • Generating operator keys (encrypted or raw)
  • Creating threshold validator keys for distributed validation
  • Exporting validator keys from mnemonic phrases

​
Installation

Build the SSV Node CLI from source: 
make build
The binary will be available at ./bin/ssvnode.

​
Available Commands

start-node

Start an SSV operator node instance

generate-operator-keys

Generate operator keys for contract event decryption

create-threshold

Split validator keys into threshold shares

export-keys

Extract validator keys from mnemonic phrase

​
Common Usage Patterns

​
Setting Up a New Operator

  1. Generate operator keys (encrypted format recommended for production):
./bin/ssvnode generate-operator-keys --password-file=password.txt
This creates encrypted_private_key.json that you’ll reference in your config.
  1. Configure your node by creating a config.yaml file:
KeyStore:
  PrivateKeyFile: ./encrypted_private_key.json
  PasswordFile: ./password.txt

ssv:
  Network: mainnet

eth2:
  BeaconNodeAddr: http://localhost:5052

eth1:
  ETH1Addr: ws://localhost:8546/ws
  1. Start the node:
./bin/ssvnode start-node --config=./config.yaml

​
Creating Validator Shares for Testing

For local testing, you can split a validator key into shares: 
# Export validator keys from mnemonic
./bin/ssvnode export-keys --mnemonic="your 24 word mnemonic" --index=0

# Create threshold shares (4 operators)
./bin/ssvnode create-threshold --private-key=<validator-private-key> --count=4
The create-threshold and export-keys commands are for testing only. For production, use ssv-keys to generate shares securely.

​
Configuration Methods

SSV Node supports multiple configuration methods: Create a YAML configuration file: 
./bin/ssvnode start-node --config=./config.yaml

​
2. Environment Variables

All configuration options can be set via environment variables: 
export LOG_LEVEL=debug
export SSV_NETWORK=mainnet
export BEACON_NODE_ADDR=http://localhost:5052
./bin/ssvnode start-node

​
3. Hybrid Approach

Combine config files with environment variable overrides. Environment variables take precedence.

​
Security Best Practices

  • Always use encrypted keystores in production (generated with --password-file)
  • Never commit raw private keys to version control
  • Store password files separately from keystore files
  • Use file permissions to restrict access: chmod 600 encrypted_private_key.json
  • Keep the SSV API port (SSVAPIPort) private and not exposed to the internet
  • Use firewalls to restrict access to node ports
  • Only expose P2P ports (TCP/UDP) to the internet
  • Use ssv-keys tool for production validator key splitting
  • Never use create-threshold or export-keys in production environments
  • Keep validator key shares distributed across operators

​
Logging and Debugging

​
Log Levels

Control log verbosity with the LogLevel configuration:
  • debug - Detailed information for debugging
  • info - General operational information (default)
  • warn - Warning messages
  • error - Error messages
  • fatal - Critical errors that cause shutdown
  • panic - Severe errors with stack trace

​
Log Formats

# Console output (human-readable)
LogFormat: console
LogLevelFormat: capitalColor

# JSON output (machine-readable)
LogFormat: json
LogLevelFormat: lowercase

​
Log Files

Configure log file rotation: 
LogFilePath: ./data/debug.log
LogFileSize: 500  # MB before rotation
LogFileBackups: 3  # Number of rotated files to keep

​
Troubleshooting

Build the binary first:
make build
ls -la ./bin/ssvnode
Specify the full path to your config file:
./bin/ssvnode start-node --config=/path/to/config.yaml
Ensure your password file contains the correct password:
cat password.txt  # Verify password
# Re-generate keystore if needed
./bin/ssvnode generate-operator-keys --password-file=password.txt
Verify beacon node is running and accessible:
curl http://localhost:5052/eth/v1/node/version

​
Version Information

Check the installed version: 
./bin/ssvnode version
Get help for any command: 
./bin/ssvnode --help
./bin/ssvnode start-node --help
./bin/ssvnode generate-operator-keys --help

​
Next Steps

Start Node

Learn about all start-node configuration options

Generate Keys

Generate operator keys for your node

Configuration

Full configuration reference

Running Locally

Set up a local development environment

Build docs developers (and LLMs) love

Get started for freeTalk to us