Introduction

A local Kubernetes-based framework for running blockchain networks

The Obol Stack is a local development environment for running blockchain networks on your machine. It provides a simplified CLI experience for managing a Kubernetes cluster with dynamically deployable network instances, allowing developers and operators to run Ethereum nodes, Layer 2 networks, and other blockchain infrastructure locally.

The Obol Stack is designed for local development and testing. For production deployments, refer to the respective network documentation and use appropriate infrastructure.

What is the Obol Stack?

Obol Stack is a two-part system:

1. obolup.sh - A bootstrap installer that sets up your environment

2. obol CLI - A Go-based binary for stack and network management

The stack runs entirely on your local machine using k3d (Kubernetes in Docker), providing a lightweight yet fully-featured Kubernetes environment for blockchain development.

Key features

• Local-first architecture - Run everything on your machine without cloud dependencies.

• Multiple network support - Deploy Ethereum nodes, Helios light clients, Aztec sequencers, and more.

• Unique deployments - Each network installation creates a uniquely-namespaced deployment, allowing multiple instances of the same network type to run simultaneously.

• Simplified tooling - Wraps kubectl, helm, and other Kubernetes tools with automatic configuration.

• Persistent storage - Data persists across cluster restarts.

Core concepts

Stack lifecycle

The Obol Stack follows a simple lifecycle:

Command	Description
obol stack init	Initialize cluster configuration
obol stack up	Start the Kubernetes cluster
obol stack down	Stop the cluster (preserves data)
obol stack purge	Remove cluster and configuration

Network deployments

Networks are deployed as isolated Kubernetes namespaces. Each deployment gets a unique identifier (either user-specified or auto-generated), enabling:

• Multiple deployments of the same network type (e.g., mainnet and testnet Ethereum nodes)

• Isolated resources per deployment

• Independent lifecycle management

• Simple cleanup via namespace deletion

Passthrough commands

Obol Stack wraps common Kubernetes tools with automatic kubeconfig configuration:

obol kubectl get pods -A          # kubectl with stack kubeconfig
obol helm list -A                 # helm with stack kubeconfig
obol k9s                          # k9s terminal UI

System requirements

Prerequisites

• Docker 20.10.0 or later (daemon must be running)

• macOS (Darwin) or Linux

• amd64 or arm64 architecture

Resource recommendations

Component	Minimum	Recommended
CPU	4 cores	8 cores
RAM	8 GB	16 GB
Storage	50 GB	500+ GB (varies by network)

Running full Ethereum nodes requires significant disk space. Mainnet execution clients can require 1+ TB of storage. Plan your storage accordingly based on which networks you intend to run.

Architecture overview

┌─────────────────────────────────────────────────────────────┐
│                        Obol Stack                           │
├─────────────────────────────────────────────────────────────┤
│  obol CLI                                                   │
│  ├── stack (init, up, down, purge)                         │
│  ├── network (list, install, sync, delete)                 │
│  └── passthrough (kubectl, helm, helmfile, k9s)            │
├─────────────────────────────────────────────────────────────┤
│  k3d Cluster                                                │
│  ├── 1 Server + 3 Agent Nodes                              │
│  ├── Traefik Ingress (ports 8080, 8443)                    │
│  └── Local Path Storage                                     │
├─────────────────────────────────────────────────────────────┤
│  Network Deployments                                        │
│  ├── ethereum-mainnet-prod (namespace)                     │
│  ├── ethereum-hoodi-test (namespace)                     │
│  ├── aztec-mainnet-node (namespace)                        │
│  └── helios-knowing-wahoo (namespace)                      │
└─────────────────────────────────────────────────────────────┘

Need assistance?

If you have questions or encounter issues with Obol Stack, head over to our Discord where a member of our team or the community will be happy to assist you.