# Introduction

The Obol Stack is a local development environment for running AI agents alongside blockchain infrastructure. It provides a simplified CLI for managing a Kubernetes cluster with an AI agent ([OpenClaw](https://openclaw.ai)), dynamically deployable blockchain networks, and public access via Cloudflare tunnels.

{% hint style="info" %}
The Obol Stack is alpha software. For production deployments, refer to the respective network documentation and use appropriate infrastructure.
{% endhint %}

## 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, agent, and network management

The stack runs entirely on your local machine using [k3d](https://k3d.io/) (Kubernetes in Docker), providing a lightweight yet fully-featured Kubernetes environment.

## Key features

* **Agent-first** - Deploy an AI agent (OpenClaw) that can interact with blockchain networks and expose services.
* **Multiple network support** - Deploy Ethereum nodes, Aztec sequencers, and more.
* **Unique deployments** - Each installation creates a uniquely-namespaced deployment, allowing multiple instances to run simultaneously.
* **Public access** - Expose services to the internet via Cloudflare tunnels and x402 payment gateways.
* **Simplified tooling** - Wraps kubectl, helm, and other Kubernetes tools with automatic configuration.

## CLI overview

| Command                                       | Description                    |
| --------------------------------------------- | ------------------------------ |
| `obol stack init / up / down / purge`         | Cluster lifecycle management   |
| `obol agent init`                             | Set up the AI agent (OpenClaw) |
| `obol openclaw dashboard / setup / ...`       | Manage OpenClaw instances      |
| `obol model setup / status`                   | Configure LLM providers        |
| `obol network list / install / sync / delete` | Manage blockchain networks     |
| `obol app install / sync / list / delete`     | Install arbitrary Helm charts  |
| `obol tunnel status / login / provision`      | Manage Cloudflare tunnels      |
| `obol kubectl / helm / k9s`                   | Kubernetes tool passthroughs   |

## Default infrastructure

When you start the stack, the following services are deployed automatically:

| Service           | Namespace       | Description                                      |
| ----------------- | --------------- | ------------------------------------------------ |
| **Traefik**       | `traefik`       | Gateway API ingress controller                   |
| **Cloudflared**   | `traefik`       | Cloudflare tunnel connector                      |
| **ERPC**          | `erpc`          | Unified RPC load balancer for Ethereum endpoints |
| **Obol Frontend** | `obol-frontend` | Web management dashboard                         |
| **Monitoring**    | `monitoring`    | Prometheus + kube-prometheus-stack               |
| **llmspy**        | `llm`           | LLM proxy/router for AI agent traffic            |

## 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) |

{% hint style="warning" %}
Running full Ethereum nodes requires significant disk space. Mainnet execution clients can require 1+ TB of storage.
{% endhint %}

## Architecture overview

```
+---------------------------------------------------------+
|                      Obol Stack                         |
+---------------------------------------------------------+
|  obol CLI                                               |
|  +-- stack     (init, up, down, purge)                  |
|  +-- agent     (init)                                   |
|  +-- openclaw  (dashboard, setup, sync, skills, ...)     |
|  +-- model     (configure, status)                      |
|  +-- network   (list, install, sync, delete)            |
|  +-- app       (install, sync, list, delete)            |
|  +-- tunnel    (status, login, provision)               |
|  +-- kubectl / helm / helmfile / k9s                    |
+---------------------------------------------------------+
|  k3d Cluster                                            |
|  +-- Traefik Gateway (ports 80, 8080, 443, 8443)       |
|  +-- Cloudflared (public tunnel)                        |
|  +-- llmspy (LLM gateway)                               |
|  +-- ERPC (RPC load balancer)                           |
|  +-- Obol Frontend (web dashboard)                      |
|  +-- Monitoring (Prometheus)                            |
+---------------------------------------------------------+
|  Deployments                                            |
|  +-- openclaw-<id>        (AI agent + remote-signer)    |
|  +-- ethereum-<id>        (blockchain network)          |
|  +-- aztec-<id>           (blockchain network)          |
|  +-- redis-<id>           (installed app)               |
+---------------------------------------------------------+
```

## Need assistance?

If you have questions or encounter issues with Obol Stack, head over to our [Discord](https://discord.gg/n6ebKsX46w) where a member of our team or the community will be happy to assist you.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.obol.org/next/obol-stack/obol-stack.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.