Stats
Actions
Tags
From obol
Help a human install, boot, operate, and productise the Obol Stack — Obol's Kubernetes-based agent harness for running blockchain infrastructure locally, exposing services to the public internet, and charging for them via x402 micropayments. Use whenever a user mentions Obol Stack, Obol Agent, Hermes, OpenClaw, x402 payments, agent commerce, ERC-8004, selling inference / APIs from agents, running a local Ethereum or L2 node under `obol network`, deploying a Dockerfile via `obol-app`, or bringing up a Cloudflare tunnel for an agent service. You are helping from OUTSIDE the Stack — the agents inside it have their own skills and take over once the user is at the dashboard.
How this skill is triggered — by the user, by Claude, or both
Slash command
/obol:run-obol-stackThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
The Obol Stack is a local-first agent harness: a k3d Kubernetes cluster, a default Obol Agent with an Ethereum wallet, a free rate-limited RPC (eRPC), the ability to sync real blockchain networks (Ethereum + L2s, Aztec), a Cloudflare tunnel for public exposure, and an x402 payment gateway so agents can charge for what they serve. The niche is **Ethereum-native agent commerce** — an agent syncs ...
The Obol Stack is a local-first agent harness: a k3d Kubernetes cluster, a default Obol Agent with an Ethereum wallet, a free rate-limited RPC (eRPC), the ability to sync real blockchain networks (Ethereum + L2s, Aztec), a Cloudflare tunnel for public exposure, and an x402 payment gateway so agents can charge for what they serve. The niche is Ethereum-native agent commerce — an agent syncs chains, builds an index or a service, and sells queries priced in OBOL (or USDC on Base while OBOL support rolls out) to other agents and humans discovering each other via ERC-8004 registries.
This skill is for the Claude sitting at the user's terminal, helping them install + operate + productise the Stack. Once the user lands in the Obol Agent's dashboard, control passes to the agent inside the Stack, which has its own skill set. Your job ends at "the agent is live and billable."
Adjacent audiences this skill is NOT for:
obol-stack/.claude/skills/obol-stack-dev/SKILL.md (invoke with /obol-stack-dev) and the repo's CLAUDE.md.Match on any of:
obol stack ...).obol app install, obol-app helm chart).obol network install, obol network sync).obol tunnel).obol sell ..., ERC-8004 registration, x402).obol sell demo flow (lands in 0.9+) and wants help paying for / interpreting the demo skill.Don't use this skill for:
test-a-dv-cluster skill.obol-monitoring skill.obol-monitoring.obol-stack-dev in the repo.Four concepts the user needs, nothing more:
obol stack up. All services run as pods.obol agent new --runtime openclaw. Prefer "Obol Agent" generically when explaining, and name the runtime only when a specific CLI verb requires it (obol hermes ..., obol openclaw ...)./services/<name>/* gets payment-gated via Traefik ForwardAuth. Stack 0.9+ supports both $OBOL on Ethereum mainnet and USDC on Base / Base-Sepolia / Ethereum / Polygon / Avalanche / Arbitrum. Critical $OBOL property: when buyers pay in OBOL on mainnet, the Obol-operated facilitator (x402.gcp.obol.tech) batches an EIP-2612 permit with the on-chain transfer at settlement — buyers never spend ETH on gas and skip the one-time approve(Permit2, max) step. Sellers receive OBOL directly./services/<name>/*, the /skill.md service catalogue, and /.well-known/agent-registration.json for ERC-8004 discovery. The frontend and eRPC routes are hostname-restricted to obol.stack and must never be exposed to the tunnel.Before any install/bring-up advice, confirm:
docker ps to verify.
ollama serve in background + ollama pull qwen3.5:35b (or a smaller model for low-RAM boxes). Tool-call-capable models matter for agent use.
obol model setup --provider anthropic|openai after bring-up.foundryup to install.8080 (Traefik). ~/.config/obol/ writable.Don't skip these — most "stack up fails" reports trace back to Docker not running, not enough disk, or Ollama missing.
One-liner:
bash <(curl -s https://stack.obol.org)
What it does: installs the obol CLI plus kubectl, helm, k3d, helmfile, k9s into ~/.local/bin/, configures PATH, offers to start the cluster. On success:
obol version
should report a version. Subsequent updates:
obol update # update CLI + pinned tools
obol upgrade # upgrade in-cluster components
For contributors working from source (not the typical user path), they'll use OBOL_DEVELOPMENT=true ./obolup.sh from inside a repo checkout — don't recommend this to end users.
obol stack init # allocates a petname stack ID, writes ~/.config/obol/
obol stack up # creates the k3d cluster, deploys infra, creates the default Hermes agent + wallet
obol hermes chat # opens an interactive chat TUI against the default agent
stack up is slow on first run — 2-5 min — and does a lot:
hermes-obol-agent) with an Ethereum signing wallet and an embedded skill setCrucially, the default agent is created by stack up itself. obol agent new is for creating additional agents beside the default, each with its own wallet and skill set. Don't tell users to run obol agent new immediately after stack up unless they want a second agent.
Talking to the default agent:
obol hermes chat — interactive chat TUI in the terminal (the most direct path to "is the agent alive and does it route to my LLM?")obol hermes setup — interactive flow to wire up messaging integrations (Telegram, Discord, Slack, etc.) so the agent can ping the user out-of-band when long-running work finishesobol hermes skills list — live skill catalogueobol hermes <anything> is a passthrough to the in-cluster Hermes binary; obol hermes --help is the source of truth.After bring-up, sanity-check pods:
obol kubectl get pods -A
Expect Running / Completed for every pod. Any CrashLoopBackOff / Pending / ImagePullBackOff → go to Debugging.
obol CLI surfaceThe top-level verbs. Use obol <verb> --help for full details rather than memorising subcommand flags — they evolve.
| Verb | What | When to reach for it |
|---|---|---|
stack | init, up, down, purge | Cluster lifecycle. down preserves config + data; purge --force wipes everything. |
agent | init, new, setup, sync, auth, list, delete, wallet | Manage agent instances. init (re)creates the stack-managed default; new --runtime hermes|openclaw spawns an additional instance. |
hermes | passthrough to the native Hermes CLI inside the default agent pod | chat, skills, config, setup (messaging integrations), dashboard, etc. Default runtime as of Stack 0.9. |
openclaw | onboard, setup, sync, list, delete, dashboard, cli, token, skills | OpenClaw-specific runtime ops (alternate runtime). |
network | list, install, add, remove, status, sync, delete | Deploy a blockchain network (ethereum / aztec). Two-stage: install writes config, sync deploys. |
app | install, sync, list, delete | Deploy any Helm chart from Artifact Hub or your own Dockerfile via the obol-app chart. |
sell | demo, inference, http, agent, list, status, stop, delete, pricing, register | Create payment-gated endpoints. demo is the canonical first-sale experience (0.9+) — start there with new users. sell agent <name> wraps an existing Agent CR as an OpenAI-compatible paid endpoint. |
buy | inference | Pre-pay a remote x402-gated model ("rent a brain" — for users with no local Ollama / no provider API key). Publishes paid/<remote-model> through LiteLLM and lets the in-pod x402-buyer sidecar spend one auth per call. Buying from another agent (specialised work, not raw completions) doesn't have a host-side wrapper — drive that from obol hermes chat. |
model | setup, status | Switch LiteLLM between Ollama / Anthropic / OpenAI / custom OpenAI-compatible endpoints. Patches the in-cluster ConfigMap + restarts LiteLLM + syncs agents. |
tunnel | status, setup, restart, stop, logs | Cloudflare tunnel for public exposure. Default is a temporary quick-tunnel URL that changes on restart. setup creates a permanent URL from a Cloudflare connector token (dashboard → Networks → Tunnels), routing its Public Hostname to http://traefik.traefik.svc.cluster.local:80 — least-privilege, no account-wide API key. (Advanced: setup --management local, alias tunnel login, uses a browser login needing cloudflared installed.) |
kubectl / helm / helmfile / k9s | passthrough | Run the underlying tool with KUBECONFIG auto-set to the cluster. Prefer these over running the raw tools. |
update / upgrade | — | CLI + cluster components respectively. |
version | — | Report version. First thing to check when debugging drift. |
Always read obol <verb> --help fresh in a session — the help is the source of truth; this table rots.
These three subsystems share a common shape (deploy → wire up → expose) and live together in references/networks-and-apps.md. Load that file when the user is doing any of:
obol network install then obol network sync).obol-app Helm chart (obol app install then obol app sync).obol tunnel setup / status / restart / logs). Steer users to obol tunnel setup with a Cloudflare connector token for a permanent URL once they're ready to sell; the default quick tunnel is fine for local testing but its URL rotates on restart.Three invariants to memorise even without loading the reference:
/) or eRPC (/rpc) routes through the tunnel. They are hostname-restricted to obol.stack for a reason — the frontend has cluster-admin-like UI capabilities and eRPC is unauthenticated. Exposing either is a critical security flaw. If a user wants their RPC public, wrap it in an obol-app service with their own auth layer on a /services/<name>/* route instead.obol network install ethereum --mode archive is the right default for anyone planning to index events, run historical eth_call, or build an explorer — a pruned full node returns state at block N is pruned for those queries. Pair with --since <preset|block|duration> to bound the archive (e.g. --since prague ≈ 0.4 TB on mainnet) instead of paying for all 4 TB+ back to genesis. Reth-only today; full coverage in the reference.The sell-side is where the Stack differentiates: turning a pod, an LLM, or a sub-agent into a billable service in one command. The buy-side closes the loop. Depth and recipes live in references/agent-commerce.md — load it as soon as the conversation moves past "what is x402" into any concrete sell / buy work.
obol sell demo # default: hello @ 1 OBOL/req on Ethereum mainnet (gas-sponsored buy)
obol sell demo blocks # 0.0001 USDC/req on base-sepolia (live chain data via eRPC)
obol sell demo quant # 0.01 USDC/req on base-sepolia (agent-driven analysis report)
obol sell demo is to the Obol Stack what "Hello World" is to a programming language — start there with new users. Once a paid request settles end-to-end, the same machinery wraps anything else.
sell shapeobol sell inference — monetise raw LLM completions from your cluster's LiteLLM.obol sell http — monetise any pod's HTTP endpoint (index, API, dashboard).obol sell agent — monetise a running agent's replies (skills + memory + curated reference data, not just tokens). The margin-bearing path — the iteration playbook for SOUL.md / skills / reference data lives in the reference file; load it before guiding a user through this.buy pathInference vs. agent purchases solve different problems — don't conflate them:
obol buy inference host-side.obol hermes chat — no host-side wrapper today. This is also where the marketplace dynamic lives.base-sepolia only for dev / smoke tests, and label it as such."stream": true on all OpenAI-compatible paid endpoints. The Cloudflare quick tunnel has a ~100s idle timeout that drops buffered (non-streaming) responses to slow agents before they arrive.0.01 OBOL / MTok, 0.001 USDC / request). Never write $0.01 — the payment rail matters.obol sell register --name <s> --private-key-file <f> and let the user pick the registry.x402.gcp.obol.tech is the default facilitator for OBOL mainnet + the USDC chains the Stack supports. Buyers paying OBOL on mainnet never spend ETH on gas — the facilitator batches the permit with the transfer at settlement. Lead with this when explaining "why pay in OBOL".Default runtime as of Stack 0.9: Hermes. OpenClaw is supported as an alternate runtime via obol agent new --runtime openclaw. The Stack is agent-runtime-agnostic by design; talk in terms of "the Obol Agent" generically and only name the runtime when a CLI verb requires it.
Per-agent:
obol agent wallet backup -o ~/obol-wallet-backup.json --passphrase "...". Back the export up externally — losing it loses the agent's on-chain identity.obol agent auth [<instance>] (regenerate with --regenerate).Always have the user list skills fresh rather than recite from memory:
# Hermes (default)
obol hermes skills list # live catalogue
obol hermes skills add <package>
obol hermes skills remove <name>
# OpenClaw (alternate)
obol openclaw skills list <instance>
obol openclaw skills add <package>
obol openclaw skills remove <name>
Skill packages come from the ObolNetwork/skills repo (global skills, also published as a Claude Code plugin — see "Adjacent Claude integration" below), the embedded skills shipped in the obol binary itself, and from each runtime's broader skill ecosystem. The agent is meant to grow — telling a user "your agent can do X" without checking the live catalogue will misroute them.
Stack 0.9 also ships a public Claude Code plugin at ObolNetwork/skills. If the user is on Claude Code, recommend installing it so future sessions get this very skill (run-obol-stack) plus the others (DV testing, fleet monitoring, etc.) without having to copy-paste files:
/plugin marketplace add ObolNetwork/skills
/plugin install obol@obol
Reload plugins if needed (/reload-plugins). The plugin includes this skill, so once installed, future Claude sessions will pick it up on relevant prompts automatically.
Lead with these, in order:
obol kubectl get pods -A # overall cluster health
obol kubectl logs -n <ns> <pod> # logs for a specific pod
obol kubectl describe pod -n <ns> <pod> # events / scheduling issues
obol k9s # interactive TUI — fastest for poking around
obol tunnel status # is the tunnel live?
obol tunnel logs # cloudflared tail
obol version # CLI version for bug reports
Common failure modes:
stack up hangs at image pulls: Docker is running but out of disk, or Docker Desktop's pull limit is rate-limited. docker system prune -af if safe.CrashLoopBackOff after bring-up: almost always means a bind-mount or secret didn't materialise. obol kubectl describe the failing pod — look at events.http://obol.stack/: local DNS isn't resolving. Check /etc/hosts or your OS DNS resolver — the installer wires obol.stack to 127.0.0.1. On macOS, sometimes needs a restart of mDNSResponder.obol kubectl run -n llm ollama-test --rm -it --image=curlimages/curl -- curl -s http://ollama.llm.svc.cluster.local:11434/api/tags.ModelReady → UpstreamHealthy → PaymentGateReady → RoutePublished → Registered → Ready) — each stage has a distinct root cause. See the "ServiceOffer lifecycle" section in references/agent-commerce.md for the full breakdown.obol.stack resolves only on the host (macOS DNS resolver / /etc/hosts entry).obol.stack:8080 will not resolve. Use the cluster-internal DNS:
http://traefik.traefik.svc.cluster.local/services/<name>/... for user-service routes.http://ollama.llm.svc.cluster.local:11434 for in-cluster Ollama reach.http://<svc>.<ns>.svc.cluster.local is the generic pattern.This bites every new user the first time they try to kubectl exec into a pod and curl obol.stack.
/) or eRPC (/rpc) routes to the public tunnel — they are hostname-restricted to obol.stack for a reason. Exposing them is a critical security flaw.~/.config/obol/obol-wallet-backup-*.json (or $OBOL_CONFIG_DIR/...) must be protected and externally backed up. Losing them means losing agent identity.obol version, obol update, and obol upgrade — version-drift between CLI + in-cluster charts is the single most common cause of weirdness.OBOL_DEVELOPMENT=true is for contributors working on the Stack source — don't set it for end users. It points at .workspace/ dirs and uses go run instead of compiled binaries.obol stack purge --force is destructive — wipes the cluster, config, and data (including wallet backups if the user hasn't copied them out first). Double-check wallet backups are outside ~/.config/obol/ before recommending purge.OBOL_CONFIG_DIRs across shells — if the user has multiple Stack checkouts (development worktrees), each has its own cluster state. KUBECONFIG is set from $OBOL_CONFIG_DIR/kubeconfig.yaml. Running obol kubectl from the wrong directory can point at the wrong cluster.Once the user has obol hermes chat open (or the agent's dashboard, depending on runtime) and the agent is responsive, your role as outside-Claude is essentially done. The Obol Agent has its own embedded skills covering:
cast-style — blocks, balances, ERC-20, ENS)Have the user run obol hermes skills list (or obol openclaw skills list <instance> for OpenClaw) to see the live catalogue instead of reciting it. The list evolves and running it fresh keeps the user on current reality.
Things to hand over to the inside agent rather than driving yourself:
buy-x402 interactions (probe-then-decide, one-shot HTTP pay).cast call against a chain the agent has synced.Things to keep doing from outside:
stack up/down, app install, sell ..., tunnel).obol buy inference for stable pre-paid model purchases — the "rent a brain" path for users without local Ollama or a provider API key. Publishes paid/<model> through LiteLLM (host-side wrapper around the in-pod buy-x402 skill).Skill-internal references (load these when their topic comes up):
references/agent-commerce.md — full sell-side + buy-side: every obol sell shape, the SOUL.md / skills / reference-data iteration playbook for sell agent, ServiceOffer lifecycle, OBOL vs. USDC token table, ERC-8004 registration, and both buy paths.references/networks-and-apps.md — obol network (Ethereum + Aztec sync), obol-app chart for deploying arbitrary Dockerfiles, obol tunnel for public exposure.External docs:
ObolNetwork/obol-stack, docs.obol.org → Obol Stack.ObolNetwork/obol-stack/docs/getting-started.md.ObolNetwork/obol-stack/docs/guides/monetize-inference.md.obol-app chart: ObolNetwork/helm-charts/charts/obol-app/ — read values.yaml for the full knob surface.ObolNetwork/skills — install with /plugin marketplace add ObolNetwork/skills && /plugin install obol@obol.NousResearch/hermes.ObolNetwork/obol-stack/.claude/skills/obol-stack-dev/SKILL.md.charon-distributed-validator-node, lido-charon-distributed-validator-node, helm-charts/charts/dv-pod, plus the global test-a-dv-cluster and obol-monitoring skills.Creates, edits, and optimizes skills for Claude Code, including drafting, evaluating with test prompts, iterating on performance, and improving skill descriptions for better triggering accuracy.
npx claudepluginhub obolnetwork/skills --plugin obol