Ctrlk
SDKAPI
Edit

Quickstart

Get started with the Obol Stack in under 10 minutes

This guide walks you through installing the Obol Stack, chatting with your default agent, and selling your first payment-gated service.

Prerequisites

  • Docker installed and running on your machine.

  • macOS or Linux operating system.

  • At least 8 GB of RAM available.

Verify Docker is running with docker info before proceeding.

Optional but recommended: install Ollama and pull a tool-call-capable model so your agent has a free, local LLM to talk to:

ollama pull qwen3.5:4b   # or qwen3.5:9b on a 16 GB+ machine

If you'd rather route through Anthropic or OpenAI, you can configure that with obol model setup after the cluster is up.

Step 1: Install the Obol Stack

Run the bootstrap installer:

bash <(curl -s https://stack.obol.org)

The installer will:

  1. Validate that Docker is running.

  2. Install the obol CLI binary and dependencies (kubectl, helm, k3d, helmfile, k9s).

  3. Configure your PATH and add obol.stack to /etc/hosts.

  4. Offer to start the cluster immediately.

Files are installed to:

  • Config: ~/.config/obol/

  • Data: ~/.local/share/obol/

  • Binaries: ~/.local/bin/

Step 2: Start the stack

obol stack up does a lot on first run — 2–5 minutes is normal — and ends with a default Hermes agent running in the hermes-obol-agent namespace, with its own Ethereum signing wallet.

First startup pulls several Docker images. If it stalls, check obol kubectl get pods -A to see what's still pending.

Step 3: Chat with your agent

Hermes is the default Obol Agent runtime. Talk to it directly from your terminal:

That drops you into a TUI chat session against the in-cluster Hermes gateway, using whichever LLM obol stack up auto-configured (your local Ollama models if available, otherwise the cloud provider you set up with obol model setup).

A few useful pass-through commands:

Want the agent to message you on Telegram, Discord, or Slack? Run obol hermes setup and follow the prompts to wire up a chat-app integration. Hermes will then notify you when long-running work finishes. The full Telegram bot flow (which involves talking to @BotFather and @userinfobot first) is covered in Build a profitable Obol Stack.

The agent has its own Ethereum wallet — back it up before you put anything on it:

Step 4: Sell your first service (obol sell demo)

This is the headline feature of the v0.9 release. obol sell demo deploys a tiny HTTP service behind an x402 payment gate, registers it on a Cloudflare quick tunnel, and prints copy-paste instructions to test it as a buyer.

The output walks you through:

  1. The public URL where the gated endpoint lives (https://<tunnel>.trycloudflare.com/services/demo-hello/...).

  2. A curl snippet that hits the endpoint and gets back HTTP 402 Payment Required with the price.

  3. A python snippet using the x402 SDK to pay and consume the response.

Other demo types ship in the same command:

Once you've watched a demo settle end-to-end, the same machinery lets you sell anything:

The mental model is: anything in your cluster that exposes a Service can be wrapped in a ServiceOffer and gated behind x402. The goal of v0.9 is to make that loop short enough that you can actually iterate on what's worth selling.

See Selling agent services for the full orientation on the three sell shapes (http, inference, agent), x402 economics, ERC-8004 registration, and marketplaces.

Why $OBOL on mainnet?

Buyers paying in $OBOL on Ethereum mainnet sign an EIP-2612 permit off-chain, and the Obol-operated facilitator batches that permit with the on-chain transfer at settlement time. Buyers never need ETH for gas, and they skip the one-time approve step that most ERC-20 payment flows require.

Sellers receive $OBOL directly into their agent wallet. Read more about the OBOL token.

List on the agent registry (ERC-8004)

obol sell demo skips on-chain registration by default (to avoid double-register reverts and the need for ETH on the agent wallet). When you're ready to be discoverable on a public agent registry:

This publishes the agent's wallet + service catalog to the ERC-8004 Identity Registry on the chain you specify.

Step 5: Drive the stack from Claude Code (optional)

The Obol team publishes a Claude Code plugin with skills for installing, operating, and selling on the Obol Stack. If you use Claude Code, install it once and let Claude run the playbook for you next time.

The run-obol-stack skill teaches Claude how to drive the CLI end-to-end — bring-up, debugging stuck pods, deploying services, registering on ERC-8004, and pointing buyers at your tunnel URL. Source: github.com/ObolNetwork/skills.

Step 6: Deploy a blockchain network (optional)

The stack ships with built-in eRPC routing to public Ethereum mainnet and Hoodi RPCs — no node required. If your agent makes a lot of requests, or you want a Consensus Layer client to run a distributed validator, run your own local node:

This creates the deployment ethereum/hoodi and registers the local node as the primary RPC upstream, with the built-in public RPCs as automatic fallback. See Installing Networks for the full set of supported networks and clients.

Step 7: Explore

Stopping and cleaning up

obol stack purge -f is irreversible. It removes all cluster data and configuration — including any agent wallets that aren't backed up outside ~/.config/obol/.

Next steps

  • Build a profitable Obol Stack — the end-to-end narrative: sync a bounded archive node, build an index, wrap it as a paid service, and turn it into a specialized agent business.

  • Selling agent services — depth on the three sell shapes, x402 economics, and getting listed on marketplaces.

  • Installing Networks — sync local Ethereum / Aztec nodes (including bounded archives via --since).

  • Installing Apps — deploy any Helm chart.

  • FAQ — common questions and troubleshooting.

PreviousIntroductionNextBuild a Profitable Obol Stack

Last updated

Was this helpful?