{"id":44911040,"url":"https://github.com/obolnetwork/obol-stack","last_synced_at":"2026-05-10T08:04:12.986Z","repository":{"id":323758006,"uuid":"951445189","full_name":"ObolNetwork/obol-stack","owner":"ObolNetwork","description":"A Kubernetes-based Ethereum stack for running decentralised applications.","archived":false,"fork":false,"pushed_at":"2026-03-26T20:37:14.000Z","size":3885,"stargazers_count":4,"open_issues_count":37,"forks_count":0,"subscribers_count":3,"default_branch":"main","last_synced_at":"2026-03-26T20:46:38.088Z","etag":null,"topics":["dapp","ethereum","helm","kubernetes"],"latest_commit_sha":null,"homepage":"https://obol.org/stack","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ObolNetwork.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-03-19T17:31:06.000Z","updated_at":"2026-03-26T18:49:53.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/ObolNetwork/obol-stack","commit_stats":null,"previous_names":["obolnetwork/obol-stack"],"tags_count":27,"template":false,"template_full_name":null,"purl":"pkg:github/ObolNetwork/obol-stack","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ObolNetwork%2Fobol-stack","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ObolNetwork%2Fobol-stack/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ObolNetwork%2Fobol-stack/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ObolNetwork%2Fobol-stack/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ObolNetwork","download_url":"https://codeload.github.com/ObolNetwork/obol-stack/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ObolNetwork%2Fobol-stack/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31290740,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-01T13:12:26.723Z","status":"ssl_error","status_checked_at":"2026-04-01T13:12:25.102Z","response_time":53,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["dapp","ethereum","helm","kubernetes"],"created_at":"2026-02-18T00:13:44.275Z","updated_at":"2026-05-10T08:04:12.957Z","avatar_url":"https://github.com/ObolNetwork.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n  \u003cimg src=\"https://obol.org/obolnetwork.png\" alt=\"Obol banner\" /\u003e\n\n\u0026nbsp;\n\n\u003ch1\u003eThe Obol Stack: Where agents deploy their infrastructure\u003c/h1\u003e\n\n\u003c/div\u003e\n\n## Overview\n\nThe [Obol Stack](https://obol.org/stack) is a framework for AI agents to run decentralised infrastructure locally. It provides an agent with the ability to sync blockchain networks (Ethereum, Aztec, etc.), interact with them via skills, and expose services to the public internet through Cloudflare [tunnels](https://developers.cloudflare.com/cloudflare-one/networks/connectors/cloudflare-tunnel/) and [x402](https://www.x402.org/) payment gateways.\n\nBuilt on [Kubernetes](https://kubernetes.io) with [Helm](https://helm.sh/) for package management. Read more in the [docs](https://docs.obol.org/next/obol-stack/obol-stack).\n\n![The Obol Stack](./assets/frontend.png)\n\n\u003e [!IMPORTANT]\n\u003e The Obol Stack is alpha software. If you encounter an issue, please open a\n\u003e [GitHub issue](https://github.com/obolNetwork/obol-stack/issues).\n\n## Getting Started\n\n### Prerequisites\n\n[Docker](https://www.docker.com/) must be installed and running:\n\n- **Linux**: [Docker Engine installation guide](https://docs.docker.com/engine/install/)\n- **macOS/Windows**: [Docker Desktop](https://docs.docker.com/desktop/)\n\n### Install\n\n```bash\nbash \u003c(curl -s https://stack.obol.org)\n```\n\nThe installer will set up the `obol` CLI and all dependencies (`kubectl`, `helm`, `k3d`, `helmfile`, `k9s`) into `~/.local/bin/`, configure your PATH, and offer to start the cluster.\n\nVerify:\n\n```bash\nobol version\n```\n\n### Quick Start\n\n```bash\n# Start the stack\nobol stack init\nobol stack up\n\n# Apply agent capabilities to the default stack-managed agent\nobol agent init\n\n# Inspect the default Hermes agent\nobol agent list\nobol agent auth obol-agent\n```\n\n`obol stack up` provisions the default [Hermes Agent](https://github.com/NousResearch/hermes-agent) runtime behind LiteLLM. `obol agent init` applies the controller-based agent capabilities used for monetization and reconciliation.\n\n## Blockchain Networks\n\nInstall and run blockchain networks as isolated deployments. Each installation gets a unique namespace so you can run multiple instances side-by-side.\n\n```bash\n# List available networks\nobol network list\n\n# Install a network (defaults to network name as ID)\nobol network install ethereum\n# → ethereum/mainnet\n\n# Deploy to the cluster (auto-selects if only one deployment exists)\nobol network sync\n\n# Or specify by type (auto-selects if only one ethereum deployment)\nobol network sync ethereum\n\n# Or by full identifier\nobol network sync ethereum/mainnet\n\n# Sync all deployments at once\nobol network sync --all\n```\n\n**Available networks:** ethereum, aztec\n\n**Ethereum options:** `--network` (mainnet, sepolia, hoodi), `--execution-client` (reth, geth, nethermind, besu, erigon, ethereumjs), `--consensus-client` (lighthouse, prysm, teku, nimbus, lodestar, grandine)\n\n```bash\n# View installed deployments\nobol kubectl get namespaces | grep -E \"ethereum|aztec\"\n\n# Delete a deployment (auto-selects if only one exists)\nobol network delete\nobol network delete ethereum/mainnet --force\n```\n\n\u003e [!TIP]\n\u003e Use `obol network install \u003cnetwork\u003e --help` to see all options.\n\n## Applications\n\nInstall arbitrary Helm charts as managed applications:\n\n```bash\n# Install from ArtifactHub\nobol app install bitnami/redis\n\n# With specific version\nobol app install bitnami/postgresql@15.0.0\n\n# Deploy to cluster (auto-selects if only one app is installed)\nobol app sync\n\n# Or specify by type (auto-selects if only one postgresql deployment)\nobol app sync postgresql\n\n# Or by full identifier\nobol app sync postgresql/eager-fox\n\n# List and manage\nobol app list\nobol app delete postgresql/eager-fox --force\n```\n\nFind charts at [Artifact Hub](https://artifacthub.io).\n\n## Model Providers\n\nThe stack runs [LiteLLM](https://github.com/BerriAI/litellm) as an in-cluster OpenAI-compatible gateway that proxies all LLM traffic. By default, Ollama on the host machine is used.\n\n**Minimum local model size**: agents in this stack rely heavily on tool calling (skills are exposed as OpenAI-style tools, the agent's identity bootstrap reads files, etc.). Models below ~7B parameters tend to either ignore the structured tool-calling channel and return raw JSON in the assistant message, or hallucinate tool failures without actually invoking the tool. Recommended local minimums for reliable agent behaviour:\n\n- `llama3.1:8b` — reference Ollama tool-calling implementation\n- `qwen3:8b` — strong tool support, modern\n- `qwen2.5:7b` (instruct) — works, slightly less disciplined under load\n\nAvoid the 1B–4B and `*-coder` variants for the agent role — they pass simple chats but break under multi-tool workflows. They remain fine for embeddings or single-turn completions exposed via `obol sell inference`.\n\nTo switch to a cloud provider:\n\n```bash\n# Interactive — prompts for provider and API key\nobol model setup\n\n# Or pass flags directly\nobol model setup --provider anthropic --api-key sk-ant-...\nobol model setup --provider openai --api-key sk-proj-...\n\n# Check which providers are enabled\nobol model status\n```\n\n`model setup` patches the LiteLLM config and Secret with your API key, adds the model to the gateway, restarts LiteLLM, and syncs the stack-managed Hermes default agent.\n\n## AI Agent Runtimes\n\nHermes is the default AI agent runtime deployed by the stack as `obol-agent`. OpenClaw remains available as an optional manual runtime. Multiple Hermes and OpenClaw instances can run side-by-side.\n\n```bash\n# Default stack-managed Hermes agent\nobol agent list\nobol agent auth obol-agent\nobol hermes skills list\n\n# Create and deploy an additional Hermes instance\nobol agent new --id research\n\n# Create and deploy an optional OpenClaw instance\nobol agent new --runtime openclaw\n\n# List optional OpenClaw instances\nobol agent list --runtime openclaw\n\n# Open the OpenClaw web dashboard\nobol openclaw dashboard\n```\n\nUse `obol agent` for Obol-managed lifecycle and auth flows. Use `obol hermes` for native Hermes CLI commands against the default instance, or pass `--agent \u003cid\u003e` for a non-default Hermes instance.\n\n### Skills\n\nThe stack ships with embedded Obol skills that are installed automatically for the default Hermes agent and for OpenClaw instances. Skills give the agent domain-specific capabilities — from querying blockchains to understanding Ethereum development patterns.\n\n#### Infrastructure\n\n| Skill | Purpose |\n|-------|---------|\n| `ethereum-networks` | Read-only Ethereum queries via cast — blocks, balances, contract reads, ERC-20, ENS |\n| `ethereum-local-wallet` | Sign and send Ethereum transactions via the per-agent remote-signer |\n| `obol-stack` | Kubernetes cluster diagnostics — pods, logs, events, deployments |\n| `distributed-validators` | Obol DVT cluster monitoring, operator audit, exit coordination |\n\n#### Ethereum Development\n\n| Skill | Purpose |\n|-------|---------|\n| `addresses` | Verified contract addresses — DeFi, tokens, bridges, ERC-8004 registries across chains |\n| `building-blocks` | OpenZeppelin patterns, DEX integration, oracle usage, access control |\n| `concepts` | Mental model — state machines, incentive design, gas mechanics, EOAs vs contracts |\n| `gas` | Gas optimization patterns, L2 fee structures, estimation |\n| `indexing` | The Graph, Dune, event indexing for onchain data |\n| `l2s` | L2 comparison — Base, Arbitrum, Optimism, zkSync with gas costs and use cases |\n| `orchestration` | End-to-end dApp build (Scaffold-ETH 2) + AI agent commerce cycle |\n| `security` | Smart contract vulnerability patterns, reentrancy, flash loans, MEV protection |\n| `standards` | ERC-8004, x402, EIP-3009, EIP-7702, ERC-4337 — spec details and integration patterns |\n| `ship` | Architecture planning — onchain vs offchain, chain selection, agent service patterns |\n| `testing` | Foundry testing — unit, fuzz, fork, invariant tests |\n| `tools` | Development tooling — Foundry, Hardhat, Scaffold-ETH 2, verification |\n| `wallets` | Wallet management — EOAs, Safe multisig, EIP-7702, key safety for AI agents |\n\n#### Frontend \u0026 QA\n\n| Skill | Purpose |\n|-------|---------|\n| `frontend-playbook` | Deployment — IPFS, Vercel, ENS subdomains |\n| `frontend-ux` | Web3 UX patterns — wallet connection, transaction flows, error handling |\n| `qa` | Quality assurance — testing strategy, coverage, CI/CD patterns |\n| `why` | Why Ethereum — the AI agent angle with ERC-8004 and x402 |\n\nManage skills at runtime:\n\n```bash\nobol openclaw skills list                   # list installed skills\nobol openclaw skills sync                   # re-inject embedded defaults\nobol openclaw skills sync --from ./my-skills  # push custom skills from local dir\nobol openclaw skills add \u003cpackage\u003e          # add via openclaw CLI in pod\nobol openclaw skills remove \u003cname\u003e          # remove via openclaw CLI in pod\n```\n\nSkills are delivered via host-path PVC injection — no ConfigMap size limits, works before pod readiness, and survives pod restarts.\n\n## Public Access (Cloudflare Tunnel)\n\nExpose your stack to the internet via Cloudflare Tunnel:\n\n```bash\n# Check tunnel status (quick tunnel mode is the default)\nobol tunnel status\n\n# Use a persistent hostname\nobol tunnel login --hostname stack.example.com\n\n# Or provision via API\nobol tunnel provision --hostname stack.example.com \\\n  --account-id ... --zone-id ... --api-token ...\n```\n\n## Managing the Stack\n\n```bash\nobol stack up        # Start the cluster\nobol stack down      # Stop the cluster (preserves data)\nobol stack purge -f  # Remove everything (including data)\nobol k9s             # Interactive cluster UI\n```\n\nThe `obol` CLI wraps `kubectl`, `helm`, `helmfile`, and `k9s` with the correct KUBECONFIG:\n\n```bash\nobol kubectl get pods --all-namespaces\nobol helm list --all-namespaces\n```\n\n## Troubleshooting\n\n#### Port 80 Already in Use\n\nEdit `~/.config/obol/k3d.yaml`, remove the `80:80` and `443:443` port entries (keep `8080:80` and `8443:443`), then restart:\n\n```bash\nobol stack down \u0026\u0026 obol stack up\n```\n\nAccess at http://obol.stack:8080 instead.\n\n#### Direct `X-PAYMENT` Buyers\n\nRaw direct `X-PAYMENT` requests through the Traefik `ForwardAuth` route are not a supported production payment path. The verifier is intentionally `verifyOnly: true`, so Traefik can gate requests but is not the final settlement point.\n\nUse:\n\n- `x402-buyer` for cluster-routed paid traffic\n- `obol sell inference` for direct buyers that need to send raw `X-PAYMENT`\n\nIf you call `x402-verifier /verify` directly for debugging, you must send `X-Forwarded-Uri` (and usually `X-Forwarded-Host`) like Traefik does, or verifier correctly returns `403 forbidden: missing forwarded URI`.\n\n#### Monetize Flow Preflight (Recommended)\n\nBefore running sell/buy tests on a machine, verify:\n\n```bash\n# 1) Kubeconfig matches the currently running k3d cluster (ports can drift).\nk3d kubeconfig write \u003ccluster-name\u003e -o ~/.config/obol/kubeconfig.yaml --overwrite\n\n# 2) Stack components are healthy.\nobol kubectl get pods -A\n\n# 3) Seller route exists and is Ready.\nobol sell list\nobol sell status \u003coffer-name\u003e -n \u003cnamespace\u003e\n\n# 4) Buyer wallet and balances are available.\nobol kubectl exec -n hermes-obol-agent deploy/hermes -c hermes -- \\\n  python3 /data/.hermes/obol-skills/buy-x402/scripts/buy.py balance\n```\n\nRun the paid tests only after all four checks pass.\n\n#### Known Limitations\n\n- `PurchaseRequest.status` (`remaining`/`spent` and `conditions[].message`) is a reconciled snapshot, not a live per-request counter.\n- For real-time auth pool state, use `x402-buyer` `GET /status` from the litellm pod.\n- Agent-managed refill is driven by `buy.py process --all`; use live sidecar status as the source of truth for refill decisions.\n- Raw direct `X-PAYMENT` through Traefik is not a supported production path; use `obol sell inference` if you need a direct buyer flow.\n\n## File Locations\n\nFollows the [XDG Base Directory](https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html) specification:\n\n| Directory | Purpose |\n|-----------|---------|\n| `~/.config/obol/` | Cluster config, kubeconfig, network and app deployments |\n| `~/.local/share/obol/` | Persistent volumes (blockchain data) |\n| `~/.local/bin/` | CLI binary and dependencies |\n\n## Updating\n\n```bash\nbash \u003c(curl -s https://stack.obol.org)\n```\n\nThe installer detects your existing installation and upgrades safely.\n\n## Uninstalling\n\n```bash\nobol stack purge -f\nrm -f ~/.local/bin/{obol,kubectl,helm,k3d,helmfile,k9s,obolup.sh}\nrm -rf ~/.config/obol ~/.local/share/obol\n```\n\n## Development\n\n```bash\ngit clone https://github.com/ObolNetwork/obol-stack.git\ncd obol-stack\nOBOL_DEVELOPMENT=true ./obolup.sh\n```\n\nDevelopment mode uses `.workspace/` instead of XDG directories and runs `go run` on every `obol` invocation — no build step needed.\n\nNetworks are embedded at `internal/embed/networks/`. Each uses annotated Go templates that auto-generate CLI flags:\n\n```yaml\n# @enum mainnet,hoodi\n# @default mainnet\n# @description Blockchain network to deploy\nnetwork: {{.Network}}\n```\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for details.\n\n## License\n\n[Apache License 2.0](LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fobolnetwork%2Fobol-stack","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fobolnetwork%2Fobol-stack","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fobolnetwork%2Fobol-stack/lists"}