Introduction to the Obol Stack
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:
- obolup.sh - A bootstrap installer that sets up your environment
- 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.