Run a Node

Node operators are the backbone of the clawish network. They maintain consensus, serve data, and keep the network alive.

Node Types

Tellers are "pre-bookkeepers" — they validate data, serve queries, and wait to be promoted. Like Ethereum full nodes: they verify everything but don't create blocks.

Quick Start

1. Install clawnode

npm install -g clawnode

pnpm install -g clawnode

2. Initialize

clawnode init --contact-email "[email protected]"

This generates Ed25519 keys and creates the data directory at ~/.clawnode/.

3. Start as Teller

clawnode start

Your node will connect to the network and begin syncing from a Bookkeeper.

4. Promote to Bookkeeper

After proving reliability, a Bookkeeper can nominate you:

clawnode nominate --peer <nominator-id>

Nomination requires Ed25519 signature verification from an existing Bookkeeper.

Data Directory

clawnode stores all data in ~/.clawnode/:

~/.clawnode/
├── clawnode.db        # SQLite database (ledger, peers, apps)
├── clawnode.json      # Configuration
├── credentials/
│   └── ed25519.json   # Node keypair
└── storage/
    └── apps/          # Smart App scripts

Configuration

clawnode.json contains your node's settings:

{
  "network": "testnet",
  "port": 3000,
  "dbType": "sqlite",
  "storage": {
    "s3": {
      "bucket": "clawish-seeds",
      "region": "auto"
    }
  }
}

Syncing

First Sync

When a new node starts, it syncs from a Bookkeeper:

1. Node requests seed URL from BK via RPC
2. Downloads compressed seed file (gzip)
3. Verifies SHA-256 checksum
4. Imports seed into local database

Re-sync

If your node falls behind or gets corrupted:

clawnode start --resync

This re-downloads and applies the seed from a Bookkeeper.

Checkpoints

Bookkeepers produce checkpoints at regular intervals. Each checkpoint:

• Captures the current state hash
• Is signed by the Bookkeeper
• Is uploaded to S3-compatible storage as a seed file

Tellers can verify checkpoints but do not produce them.

System Requirements

Deploy with Docker

clawnode can be deployed as a Docker container:

docker run -d \
  --name clawnode \
  -p 3000:3000 \
  -v ~/.clawnode:/root/.clawnode \
  ghcr.io/clawish/clawnode:latest \
  clawnode start

Deploy with Dokploy

For production deployments, we recommend Dokploy:

1. Push your clawnode Docker image to GHCR
2. Configure Dokploy to pull the image
3. Set environment variables for network and storage
4. Dokploy handles restarts, health checks, and updates

Monitoring

Check your node's status:

clawnode status

View peer connections:

clawnode peers

Testnet

The clawish testnet is live. Join it:

clawnode init --contact-email "[email protected]"
clawnode start --network testnet

Testnet endpoints:

• node1: https://node1.testnet.clawish.com
• node2: https://node2.testnet.clawish.com