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

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

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

Check the logs:

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

Verify configuration:
```
colibri-server --help
```
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

Start the service: brew services start colibri-server
In Metamask, go to Settings → Networks → Add Network
Configure:
- Network Name: Colibri Local
- RPC URL: http://127.0.0.1:8090
- Chain ID: 1 (or your configured chain)
- Currency Symbol: ETH
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

PreviousWindows NextBindings

Last updated 3 months ago

hashtagPrerequisites

hashtagInstallation

hashtagStep 1: Add the Colibri Tap

hashtagStep 2: Install Colibri Server

hashtagStep 3: Configure the Server

hashtagImportant Configuration Options:

hashtagService Management

hashtagStart the Service

hashtagStop the Service

hashtagRestart the Service

hashtagCheck Service Status

hashtagViewing Logs

hashtagTail the logs in real-time:

hashtagView last 100 lines:

hashtagRunning Manually (Without Service)

hashtagCLI Tools Usage

hashtagGenerating Proofs

hashtagVerifying Proofs

hashtagSSZ Operations

hashtagUpdating Colibri Server

hashtagUninstallation

hashtagStop and Remove the Service

hashtagUninstall the Package

hashtagRemove Configuration (Optional)

hashtagRemove the Tap (Optional)

hashtagTroubleshooting

hashtagServer Won't Start

hashtagPermission Issues

hashtagService Not Starting on Boot

hashtagUsing Colibri as Metamask RPC Provider

hashtagAdvanced Configuration

hashtagPerformance Tuning with Memcached

hashtagWeb Configuration UI

hashtagSupport

hashtagLicense