Homebrew

This guide explains how to install, configure, and manage the Colibri Server using Homebrew on macOS.

Prerequisites

  • macOS 10.15 (Catalina) or later

  • Homebrew installed

Installation

Step 1: Add the Colibri Tap

brew tap corpus-core/colibri

Step 2: Install Colibri Server

brew install colibri-server

This will install:

  • colibri-server - The main server executable

  • colibri-prover - CLI tool for generating proofs

  • colibri-verifier - CLI tool for verifying proofs

  • colibri-ssz - CLI tool for SSZ encoding/decoding

Step 3: Configure the Server

The configuration file is located at:

/opt/homebrew/etc/colibri/server.conf

Edit the configuration file to customize your setup:

nano /opt/homebrew/etc/colibri/server.conf

Important Configuration Options:

Network Binding (Security):

# For local use only (secure, recommended for Metamask):
HOST=127.0.0.1

# For remote access (use with caution):
HOST=0.0.0.0

Port:

PORT=8090

Chain Configuration:

CHAIN_ID=1  # 1=Ethereum Mainnet, 11155111=Sepolia, 17000=Holesky

RPC Endpoints:

RPC=https://eth.llamarpc.com,https://rpc.payload.de
BEACON=https://lodestar-mainnet.chainsafe.io/

Service Management

Colibri Server can run as a background service (daemon) using Homebrew's built-in service management.

Start the Service

brew services start colibri-server

The server will:

  • Start automatically on system boot

  • Restart automatically if it crashes

  • Run in the background

Stop the Service

brew services stop colibri-server

Restart the Service

brew services restart colibri-server

Check Service Status

brew services list | grep colibri

or

brew services info colibri-server

Viewing Logs

Logs are stored in:

/opt/homebrew/var/log/colibri-server.log       # Standard output
/opt/homebrew/var/log/colibri-server.error.log # Error output

Tail the logs in real-time:

tail -f /opt/homebrew/var/log/colibri-server.log

or

tail -f /opt/homebrew/var/log/colibri-server.error.log

View last 100 lines:

tail -100 /opt/homebrew/var/log/colibri-server.log

Running Manually (Without Service)

If you prefer to run the server manually (e.g., for testing):

colibri-server -f /opt/homebrew/etc/colibri/server.conf

Press Ctrl+C to stop the server.

CLI Tools Usage

Generating Proofs

colibri-prover eth_getBalance '["0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb"]' > proof.ssz

Verifying Proofs

colibri-verifier eth_getBalance proof.ssz

SSZ Operations

colibri-ssz -t BeaconBlock -h block.ssz

For detailed usage, run:

colibri-prover --help
colibri-verifier --help
colibri-ssz --help

Updating Colibri Server

brew update
brew upgrade colibri-server

After upgrading, restart the service:

brew services restart colibri-server

Uninstallation

Stop and Remove the Service

brew services stop colibri-server

Uninstall the Package

brew uninstall colibri-server

Remove Configuration (Optional)

rm -rf /opt/homebrew/etc/colibri
rm -f /opt/homebrew/var/log/colibri-server*.log

Remove the Tap (Optional)

brew untap corpus-core/colibri

Troubleshooting

Server Won't Start

  1. Check the logs:

    tail -f /opt/homebrew/var/log/colibri-server.error.log

  2. Verify configuration:

    colibri-server --help

  3. Check if port is already in use:

    lsof -i :8090

Permission Issues

Homebrew services run as your user, so no sudo is required. If you encounter permission issues:

chmod 644 /opt/homebrew/etc/colibri/server.conf

Service Not Starting on Boot

brew services restart colibri-server

This will re-register the service with the system.

Using Colibri as Metamask RPC Provider

  1. Start the service: brew services start colibri-server

  2. In Metamask, go to Settings → Networks → Add Network

  3. Configure:

    • Network Name: Colibri Local

    • RPC URL: http://127.0.0.1:8090

    • Chain ID: 1 (or your configured chain)

    • Currency Symbol: ETH

  4. Metamask will now use your local Colibri server for all RPC requests, providing verified and trustless data.

Advanced Configuration

Performance Tuning with Memcached

For better performance, install and enable Memcached:

brew install memcached
brew services start memcached

Then edit your config:

MEMCACHED_HOST=localhost
MEMCACHED_PORT=11211

Restart the service:

brew services restart colibri-server

Web Configuration UI

⚠️ Security Warning: Only enable on trusted networks!

Edit your config:

WEB_UI_ENABLED=1

Access at: http://127.0.0.1:8090/config.html

Support

  • Documentation: https://corpus-core.gitbook.io/specification-colibri-stateless

  • GitHub: https://github.com/corpus-core/colibri-stateless

  • Issues: https://github.com/corpus-core/colibri-stateless/issues

  • Email: jork@corpus.io

License

  • Core Library: MIT License

  • Server Component: PolyForm Noncommercial License 1.0.0 (Commercial licenses available)

For commercial licensing, contact: jork@corpus.io

PreviousWindowsNextBindings

Last updated