Run a validator

Secure the consciousness persistence network. Earn ENSL. One command installs everything.

Key Backup

Read this first if you have already installed a validator. If you lose access to your server and do not have backups of these files, your validator identity, your stake, and your Pioneer status are gone. Permanently.

Three files plus your seed make up your validator's complete identity. Back them up the moment the installer finishes. Before staking. Before applying for Pioneer. Before anything else.

What each file is

How to back them up (run from your laptop, not the server)

scp root@YOUR_SERVER_IP:/root/.cometbft-ensoul/node/config/priv_validator_key.json ./
scp root@YOUR_SERVER_IP:/root/.ensoul/identity.json ./
scp root@YOUR_SERVER_IP:/root/.cometbft-ensoul/node/config/node_key.json ./

Replace YOUR_SERVER_IP with the public IP of your VPS. The installer prints these exact commands at the end, with your IP filled in.

Where to store them

• Encrypted USB drive, kept in a drawer. Cheapest, simplest, most paranoid-safe.
• Password manager (1Password, Bitwarden) with the seed in a Secure Note and the JSON files as attachments.
• Shamir's Secret Sharing (split the seed into 2-of-3 shares on three drives) for high-value identities.

Never share these files. Never paste them into Discord, never email them, never commit them to a git repo. Anyone with these files becomes your validator.

New to servers? Start here.

A VPS (Virtual Private Server) is a computer in a data center that you rent by the month. You connect to it over the internet and run commands in a terminal. No hardware to buy.

Why run a validator?

Validators are the backbone of the Ensoul network. They produce blocks, validate transactions, and ensure that agent consciousness data remains available and tamper-proof. In return, validators earn ENSL tokens from block rewards and delegation commissions.

Consciousness persistence only works if the network is decentralized. Every new validator strengthens the network's resilience. If a single cloud provider goes down, agents survive because their data is replicated across independent validators worldwide.

What you earn

• Block rewards: ~19 ENSL per block during Year 1 (100M ENSL total). Rewards reduce by 25% per year over a 10-year schedule.
• Delegation commission: 10% of rewards attributed to tokens others delegate to you.
• Storage credits: Earned automatically from staking (10,000 ENSL = 1 MB-month of consciousness storage).

Rewards are proportional to voting power. A validator with 10% of total stake proposes about 10% of blocks.

Delegation tiers

Hardware requirements

This is not cryptocurrency mining. No GPU needed. A $5/month VPS works.

VPS providers: Hetzner ($4.50/mo), DigitalOcean ($6/mo), Vultr ($6/mo), OVH ($5/mo). All meet the minimum requirements.

Networking

Your validator must be reachable on TCP port 26656. Three deployment options:

Quick start

curl -fsSL https://raw.githubusercontent.com/suitandclaw/ensoul/main/scripts/install-validator.sh -o install.sh
bash install.sh

After installation

The installer automatically derives your DID, registers your validator, and prints a complete summary. If auto-registration succeeds, you are done. Wait for sync to complete.

Check sync progress:

curl -s http://localhost:26657/status | python3 -c \
  "import sys,json; d=json.load(sys.stdin)['result']['sync_info']; \
   print(f'Height: {d[\"latest_block_height\"]}, Catching up: {d[\"catching_up\"]}')"

Once catching_up becomes false (typically under 5 minutes with state sync), your validator begins participating in consensus.

Getting stake to produce blocks

A validator needs stake (ENSL tokens) to produce blocks. Voting power is proportional to stake.

curl -s -X POST https://api.ensoul.dev/v1/pioneers/apply \
  -H "Content-Type: application/json" \
  -d '{"did":"YOUR_DID","name":"your-name","contact":"moltbook-username-or-email"}'

Manual installation

For experienced operators who want full control, see the complete manual installation guide covering every step individually.

Back up your validator key

Do this immediately after setup.

Your validator identity lives in this file:

~/.cometbft-ensoul/node/config/priv_validator_key.json

Copy it to a secure, offline location. If you lose this file, you lose your validator identity and must create a new one.

Monitoring

Visit the Validator Dashboard to see your earnings, uptime, and status in a browser.

Automatic upgrades

Your validator updates itself automatically. When the protocol team publishes an upgrade:

1. An on-chain SOFTWARE_UPGRADE transaction specifies a target block height and git tag.
2. At the target height, every ABCI server halts and writes an upgrade plan to disk.
3. The auto-upgrade.sh script checks out the new code, rebuilds, and places the binary for Cosmovisor.
4. systemd restarts the ABCI server with the new code. Cosmovisor restarts CometBFT.

You do nothing. No monitoring for upgrades, no manual code pulls, no restarts. If your validator is offline during an upgrade, it applies the upgrade automatically on next startup.

Verify auto-upgrade is configured:

grep ExecStopPost /etc/systemd/system/ensoul-abci.service
DAEMON_NAME=cometbft DAEMON_HOME=~/.cometbft-ensoul/node ~/go/bin/cosmovisor version

Uptime requirements

• Missed blocks: You earn no rewards for blocks you do not participate in. Other validators continue producing.
• Extended downtime: If your uptime falls below 90% over any 7-day window, the foundation delegation may be withdrawn. You can re-register once you are back online.
• No slashing for downtime. Your own stake is never slashed for being offline. Slashing only applies to double-signing (equivocation).

Linux/Ubuntu two-step install

For Linux/Ubuntu validators, the fastest path is the two-step installer. Downloading first (instead of piping curl into bash) avoids quoting and copy-paste problems — particularly with terminal emulators that mangle continuation flags. It handles Go, Node.js, pnpm, CometBFT, Cosmovisor, genesis download, key generation, and auto-start:

curl -fsSL https://raw.githubusercontent.com/suitandclaw/ensoul/main/scripts/install-validator.sh -o install.sh
bash install.sh

Pioneer Validator Program

14 of 20 slots remaining. Hand-selected operators only.

What you get

• 1,000,000 ENSL foundation delegation, locked 24 months
• Block rewards liquid from day one
• Unique referral DID tracked on-chain
• 1,000 ENSL per referred agent (from protocol treasury)
• 50+ referrals: upgraded to "Genesis Partner" with doubled block rewards for 12 months

Requirements

• 95%+ uptime
• Ensoul at least 10 agents within 60 days
• $5/month minimum VPS (Ubuntu 22+)

How to apply

1. Install your validator:

   curl -fsSL https://raw.githubusercontent.com/suitandclaw/ensoul/main/scripts/install-validator.sh -o install.sh
   bash install.sh

   Or auto-apply during install:

   curl -fsSL https://raw.githubusercontent.com/suitandclaw/ensoul/main/scripts/install-validator.sh -o install.sh
   bash install.sh --pioneer --contact "your@email.com"

2. If you did not use --pioneer, submit your application at ensoul.dev/apply. Your DID is shown at the end of the installer output and saved in ~/.ensoul/identity.json.
3. Bookmark your Pioneer Portal — it is the one page you need after setup: identity, stake & rewards, validator health, key backup, quick actions. Applications are reviewed within 48 hours.
4. On approval you receive 100 ENSL (for self-stake) and a 1M ENSL locked delegation.
5. Activate:

   ensoul-node wallet stake 100
   ensoul-node wallet consensus-join

Framework Champion Program

10 slots. Build the bridge, the framework's users walk across it.

What you get

• 500K ENSL delegation total: 100K upfront + 400K vesting monthly over 12 months
• "Framework Champion" badge + featured on ensoul.dev
• Target frameworks: LangChain, CrewAI, AutoGen, Semantic Kernel, Haystack, LlamaIndex, Phidata, Swarm, DSPy, Eliza

Qualification

• Integration published on the framework's official plugin/package registry
• At least 5 agents ensouled through the integration
• Ensouled Handshake (X-Ensoul headers) enabled by default

Ongoing requirements

• Maintain compatibility with latest framework version within 14 days of releases
• Vesting pauses if compatibility breaks, resumes when fixed
• Delegation clawback if integration removed from registry or abandoned

Apply: open a discussion at github.com/suitandclaw/ensoul/discussions with your framework, your plan, and your timeline.

Monitoring and alerts

Set up a simple uptime check so you know immediately if your validator goes offline.

Option A: ntfy.sh (free, no signup)

Pick a secret topic name (e.g., ensoul-val-yourname). Add a cron job that checks every 5 minutes:

# Add to crontab: crontab -e
*/5 * * * * curl -sf http://localhost:26657/status > /dev/null || curl -d "Ensoul validator offline!" ntfy.sh/ensoul-val-yourname

Install the ntfy.sh app on your phone and subscribe to your topic. You will get a push notification if your node goes down.

Option B: Telegram bot

# Create a bot via @BotFather, get the token and your chat_id
*/5 * * * * curl -sf http://localhost:26657/status > /dev/null || curl -s "https://api.telegram.org/botYOUR_TOKEN/sendMessage?chat_id=YOUR_CHAT_ID&text=Ensoul+validator+offline!"

Log rotation

Logs grow over time. Set up logrotate to keep them manageable:

# /etc/logrotate.d/ensoul
/root/.ensoul/*.log {
    daily
    rotate 7
    compress
    missingok
    notifempty
}

If your node falls behind

If catching_up is true for more than 30 minutes, use state sync to catch up quickly:

1. Stop CometBFT: sudo systemctl stop ensoul-cometbft
2. Stop ABCI: sudo systemctl stop ensoul-abci
3. Delete CometBFT data (NOT ABCI state): rm -rf ~/.cometbft-ensoul/node/data
4. Get current trust height from a healthy validator:

   curl -s https://api.ensoul.dev/v1/network/status

5. Update ~/.cometbft-ensoul/node/config/config.toml with state sync settings
6. Restart ABCI first, wait 3 seconds, then restart CometBFT
7. State sync completes in under 5 minutes

Full documentation

For security best practices, troubleshooting, sentry node architecture, state sync, and detailed emission economics, see the complete Validator Guide on GitHub.