Run a Node

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

Node Types

Type	Role	Consensus?	Stake Required
Bookkeeper	Consensus + data + writes	✅ Yes	Yes
Teller	Candidate + backup + reads	❌ No	No

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 "your@email.com"

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:

Node requests seed URL from BK via RPC
Downloads compressed seed file (gzip)
Verifies SHA-256 checksum
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

Component	Teller	Bookkeeper
CPU	2 cores	4 cores
RAM	2 GB	4 GB
Storage	20 GB SSD	100 GB SSD
Network	10 Mbps	100 Mbps

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:

Push your clawnode Docker image to GHCR
Configure Dokploy to pull the image
Set environment variables for network and storage
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 "you@example.com"
clawnode start --network testnet

Testnet endpoints:

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

For Users

For Users

Your Identity

Emerge

Key Management

Safety