• Home
• Run
• Run A Generator
• Install

Install

This page covers installing a Shinzo Generator client with Docker or from source. To complete the Generator setup, you must also register it with the Shinzo Network (see Registration).

Running the client only requires access to an execution node. You do not need to run a validator to install or run the Generator. Registration, however, is a separate step that does require you to be an active, bonded validator on your source chain. See the Registration prerequisites for details.

Hardware recommendations

The Generator client is a lightweight sidecar (the binary is approximately 50 MB) that runs next to an execution node. See the hardware requirements page for CPU, RAM, storage, and network sizing, including how to account for the execution node itself.

Using Docker

These steps use Docker to run the Shinzo Generator client. To build the Generator client from source, see Building from source below.

Prerequisites

• Docker.
• Access to an execution node that exposes JSON-RPC and WebSocket. The Generator client does not run a node for you; it just reads from one. This can be a node you run yourself, a node co-located with your validator, or a managed provider.
• A browser wallet setup. This wallet does not need to hold any funds.

You do not need to be a validator, or to run a validator, just to install and run the Generator client. Validator requirements only apply to the Registration step.

Steps

1. Pull the pre-built Generator client image from the Shinzo container registry.

   docker pull ghcr.io/shinzonetwork/shinzo-generator-client:ethereum-mainnet-latest
   

   standard: Pulling from shinzonetwork/shinzo-generator-client
   2521f1b70bf8: Pull complete
   2c845527b24c: Pull complete
   
   [...]
   
   Digest: sha256:a272b09607e6f3f07399d72d019f058919ba2854469835b80478fd75799fa0fd
   Status: Downloaded newer image for ghcr.io/shinzonetwork/shinzo-generator-client:ethereum-mainnet-latest
   

2. Gather your execution node's:

   • RPC URL
   • WebSocket URL
   • API key (if set)

3. Start the Generator client by filling in your details and running:

   docker run --rm \
     -e GETH_RPC_URL={{ YOUR RPC URL }}\
     -e GETH_WS_URL={{ YOUR WEBSOCKET URL }}\
     -e GETH_API_KEY={{ YOUR API KEY (OPTIONAL) }} \
     -e GETH_API_KEY_TYPE={{ HEADER NAME, e.g. x-goog-api-key or x-api-key (OPTIONAL) }} \
     -e INDEXER_START_HEIGHT=0 \
     -e DEFRADB_KEYRING_SECRET=testnet-secret \
     -e DEFRADB_PLAYGROUND=true \
     -e DEFRADB_P2P_ENABLED=true \
     -e DEFRADB_P2P_LISTEN_ADDR=/ip4/0.0.0.0/tcp/9171 \
     -e LOGGER_DEBUG=true \
     -p 9181:9181 \
     -p 9171:9171 \
     -p 8080:8080 \
     ghcr.io/shinzonetwork/shinzo-generator-client:ethereum-mainnet-latest
   

You should see the Generator client connect to your node and start collecting and committing blocks:

2026-05-11T10:59:54.762Z	INFO	Committed block 25071330 (ID: bae-235bbc36-32ff-5fb0-8361-6c4dc3d6aeb9)
2026-05-11T10:59:54.902Z	DEBUG	HTTP response: 200 OK (Content-Length: )
2026-05-11T10:59:54.902Z	DEBUG	HTTP request successful, status: 200 OK
2026-05-11T10:59:55.272Z	DEBUG	HTTP Request: POST http://35.193.228.182:8080
2026-05-11T10:59:55.272Z	DEBUG	Setting x-goog-api-key header: df7f****e6db
2026-05-11T10:59:55.272Z	DEBUG	Request headers: Content-Type=application/json, User-Agent=
2026-05-11T10:59:55.409Z	DEBUG	HTTP response: 200 OK (Content-Length: )
2026-05-11T10:59:55.409Z	DEBUG	HTTP request successful, status: 200 OK

Eventually your Generator client will catch up with the validator node and start waiting for new blocks rather than pulling historical data:

2026-05-11T11:05:09.338Z	DEBUG	HTTP response: 200 OK (Content-Length: )
2026-05-11T11:05:09.338Z	DEBUG	HTTP request successful, status: 200 OK
2026-05-11T11:05:09.338Z	INFO	Block 25071451 not available yet, waiting...

Registration

Once the Generator client is running, register it with the Shinzo Network. See Registration for details.

Building from source

You can also build the Generator client binary from source instead of using Docker.

Prerequisites

• Go 1.26 or later.
• Git.
• Access to an execution node (same as the Docker install method).

Steps

1. Clone the repository and install the Go dependencies.

   git clone https://github.com/shinzonetwork/shinzo-generator-client.git
   cd shinzo-generator-client
   go mod download
   

2. Create a .env file with your node details and Generator client settings.

   cat > .env << EOF
   GETH_RPC_URL=<your-rpc-url>
   GETH_WS_URL=<your-ws-url>
   GETH_API_KEY=<your-api-key>
   GETH_API_KEY_TYPE=<header-name, e.g. x-goog-api-key or x-api-key>
   
   DEFRADB_KEYRING_SECRET=<your-keyring-secret>
   DEFRADB_PLAYGROUND=true
   DEFRADB_P2P_ENABLED=true
   DEFRADB_P2P_LISTEN_ADDR=/ip4/0.0.0.0/tcp/9171
   
   INDEXER_START_HEIGHT=0
   LOGGER_DEBUG=true
   EOF
   

   You may not need to enter an API key.

3. Build the binary.

   make build
   

4. Run the Generator client.

   make start
   

Registration

Once your Generator client is running, register it with the Shinzo Network. See Registration for details.

Do you need an API key?

It depends on where your node is.

If the Generator client and your node are on the same private network (both on VMs in the same VPC, for example) you probably don't need one. Most execution nodes have no authentication by default. Leave GETH_API_KEY empty and point GETH_RPC_URL at the node's internal IP or hostname.

For an externally hosted node, authentication is almost always required. Two common cases:

• GCP Blockchain Node Engine (blockchainnodeengine.com) expects the key in the x-goog-api-key header.
• A self-hosted node behind a reverse proxy (e.g. nginx) uses whatever header the operator configures. x-api-key is common.

Set GETH_API_KEY_TYPE to the header name your provider expects.

Exposed ports

The following ports must be exposed and available on the machine.

Troubleshooting

Permission denied on .defra/keys

The data directories are owned by root but the container runs as UID 1001. Stop the container, fix the ownership, then start again:

docker-compose -f ~/docker-compose.yml stop
chown -R 1001:1001 ~/data/defradb ~/data/lens
docker-compose -f ~/docker-compose.yml start

Failed to load existing DefraDB identity

DEFRADB_KEYRING_SECRET has changed since the first run. Restore the original value in your compose file and restart.

WebSocket unavailable, will use HTTP-only mode

The Generator client falls back to HTTP polling. Check that GETH_WS_URL is correct and the port is reachable. HTTP-only mode works but is slightly slower.

Need help

• For onboarding and technical support, join the Shinzo Discord.
• To report a documentation bug or request a feature, open an issue in the docs repo.
• For a technical issue with the Generator client, open an issue in the shinzo-generator-client repo.