Skip to main content
Version: v1.10

Quickstart

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.
info

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.
bash <(curl -s https://stack.obol.org)

Files are installed to:

  • Config: ~/.config/obol/
  • Data: ~/.local/share/obol/
  • Binaries: ~/.local/bin/

Step 2: Start the stack​

obol stack init
obol stack up

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.

info

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:

obol hermes chat

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:

obol hermes skills list           # see the agent's installed skills
obol hermes config show           # inspect the runtime config
obol hermes --help                # full Hermes CLI surface
tip

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:

obol agent wallet address         # print the agent's wallet address
obol agent wallet backup -o ~/obol-wallet-backup.json --passphrase "..."

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.

obol sell demo                    # deploys "hello" demo @ 1 OBOL/req on Ethereum mainnet

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:

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)

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

obol sell inference my-model --model qwen3.5:9b --per-mtok 0.01 --token USDC --chain base
obol sell http my-api --upstream my-svc --port 8080 --namespace my-ns \
  --per-request 0.001 --chain base --wallet <your-wallet>

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:

obol sell register --chain mainnet --name my-service --private-key-file <path>

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.

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

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:

# Install an Ethereum node on Hoodi testnet
obol network install ethereum --network=hoodi

# Deploy to the cluster
obol network sync ethereum

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​

obol k9s                          # interactive cluster TUI (press '0' to view all)
obol kubectl get pods -A          # all pods across all namespaces
obol tunnel status                # public tunnel URL
obol sell list                    # services you're selling
obol sell status <name>           # ServiceOffer reconciliation state
info

obol stack up gives you a temporary tunnel URL that changes on every restart. When you're ready to sell, give your stack a stable hostname — see Set up a permanent URL.

Stopping and cleaning up​

obol stack down                   # stop the cluster (preserves data)
obol stack up                     # restart
obol stack purge -f               # remove everything, including data
warning

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.