Skip to content

README.md

Latest commit

 

History

History
129 lines (100 loc) · 7.15 KB

README.md

File metadata and controls

129 lines (100 loc) · 7.15 KB
description A framework for AI agents to run decentralized infrastructure locally

Introduction to the Obol Stack

The Obol Stack is a local-first agent harness: a Kubernetes cluster on your laptop, a default AI agent (Hermes) with its own Ethereum wallet, dynamically-deployable blockchain networks, a Cloudflare tunnel for public exposure, and an x402 payment gateway so agents can charge for what they serve.

The thesis is simple: agents should be able to run real infrastructure, build something valuable on top of it, and sell access to it for micropayments — without asking permission and without standing up cloud accounts.

{% hint style="info" %} The Obol Stack is alpha software. For production validator deployments, use the Run a DV docs and dedicated infrastructure. {% endhint %}

What's in the box

Obol Stack is a two-part system:

  1. obolup.sh — bootstrap installer that lays down pinned dependencies (kubectl, helm, k3d, helmfile, k9s) and the obol CLI.
  2. obol CLI — Go binary that drives everything: cluster lifecycle, the agent, networks, payment-gated services, and the tunnel.

The cluster runs entirely on your machine via k3d (Kubernetes in Docker).

Key features

  • Agent-first — obol stack up brings up a default Hermes agent with its own Ethereum signing wallet (backed by a remote-signer), a chat TUI, and a growing skill set. Talk to it with obol hermes chat.
  • Sell what your agent builds — obol sell demo deploys a payment-gated HTTP service in one command. Use it as the starting point for selling inference, indexed data, or any HTTP API for $OBOL or USDC micropayments.
  • Native $OBOL micropayments with sponsored gas on mainnet — when buyers pay in $OBOL on Ethereum mainnet, the Obol facilitator sponsors the on-chain settlement gas. Buyers sign an EIP-2612 permit off-chain and never need ETH. Sellers receive $OBOL directly to their agent wallet.
  • Multiple network support — sync local Ethereum nodes (mainnet, sepolia, hoodi), Aztec sequencers, and more. Built-in eRPC routes to public RPCs when no local node is present.
  • Public access — expose only the routes you choose (/services/<name>/* and discovery metadata) via a Cloudflare quick tunnel. Internal routes (frontend, eRPC) stay locked to obol.stack.
  • Unique deployments — every install gets a uniquely-namespaced deployment, so multiple stacks coexist on one machine.

CLI overview

Command Description
obol stack init / up / down / purge Cluster lifecycle
obol agent init / new / setup / sync / list / delete Manage agent instances (default runtime: Hermes)
obol hermes chat / skills / config / ... Pass-through to the in-cluster Hermes CLI
obol model setup / status Configure LLM providers (Ollama, Anthropic, OpenAI, custom)
obol network list / install / sync / delete Manage blockchain networks
obol sell demo / inference / http / list / status / register Create payment-gated services and register on ERC-8004
obol app install / sync / list / delete Install arbitrary Helm charts
obol tunnel status / login / provision Manage Cloudflare tunnels
obol kubectl / helm / helmfile / k9s Kubernetes tool passthroughs (auto-configured KUBECONFIG)

Default infrastructure

When you run obol stack up, the following services are deployed automatically:

Service Namespace Purpose
Hermes (default agent) hermes-obol-agent AI agent + dashboard, with its own Ethereum signing wallet
Traefik traefik Gateway API ingress controller
Cloudflared traefik Cloudflare tunnel connector for public routes
eRPC erpc Unified RPC load balancer (local nodes + public fallbacks)
Obol Frontend obol-frontend Web management dashboard (local-only)
Monitoring monitoring Prometheus + kube-prometheus-stack
LiteLLM llm OpenAI-compatible LLM gateway (Ollama, Anthropic, OpenAI, custom endpoints)
x402 verifier + ServiceOffer controller x402 Payment gating + reconciliation of payment-gated services

Use it from Claude Code

The Obol team publishes a Claude Code plugin with skills for installing, operating, and selling on the Obol Stack.

/plugin marketplace add ObolNetwork/skills
/plugin install obol@obol

Once installed, Claude Code can drive obol stack up, set up the agent, troubleshoot pods, and walk you through obol sell demo. Source: github.com/ObolNetwork/skills.

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, new, setup, sync, list, delete)   |
|  +-- hermes    (passthrough — chat, skills, config)     |
|  +-- model     (setup, status)                          |
|  +-- network   (list, install, sync, delete)            |
|  +-- sell      (demo, inference, http, register, ...)   |
|  +-- 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)                        |
|  +-- LiteLLM (LLM gateway)                              |
|  +-- eRPC (RPC load balancer)                           |
|  +-- Obol Frontend (web dashboard, local-only)          |
|  +-- x402 verifier + ServiceOffer controller            |
|  +-- Monitoring (Prometheus)                            |
+---------------------------------------------------------+
|  Deployments                                            |
|  +-- hermes-obol-agent     (default agent + signer)     |
|  +-- ethereum-<id>         (blockchain network)         |
|  +-- aztec-<id>            (blockchain network)         |
|  +-- demo                  (services from `obol sell`)  |
+---------------------------------------------------------+

Need assistance?

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