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

{% hint style="info" %}
Verify Docker is running with `docker info` before proceeding.
{% endhint %}

**Optional but recommended:** install [Ollama](https://ollama.com) and pull a tool-call-capable model so your agent has a free, local LLM to talk to:

```shell
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:

```shell
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.

{% tabs %}
{% tab title="Default installation" %}

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

Files are installed to:

* Config: `~/.config/obol/`
* Data: `~/.local/share/obol/`
* Binaries: `~/.local/bin/`
  {% endtab %}

{% tab title="Specific version" %}

```shell
OBOL_RELEASE=v0.9.0 bash <(curl -s https://stack.obol.org)
```

{% endtab %}

{% tab title="Development mode" %}

```shell
git clone https://github.com/ObolNetwork/obol-stack.git
cd obol-stack
OBOL_DEVELOPMENT=true ./obolup.sh
```

Development mode uses a local `.workspace/` directory and runs `go run` instead of a compiled binary.
{% endtab %}
{% endtabs %}

## Step 2: Start the stack

```shell
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.

{% hint style="info" %}
First startup pulls several Docker images. If it stalls, check `obol kubectl get pods -A` to see what's still pending.
{% endhint %}

## Step 3: Chat with your agent

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

```shell
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:

```shell
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
```

{% hint style="success" %}
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.
{% endhint %}

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

```shell
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](https://www.x402.org/) payment gate, registers it on a Cloudflare quick tunnel, and prints copy-paste instructions to test it as a buyer.

```shell
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](https://github.com/coinbase/x402) SDK to pay and consume the response.

Other demo types ship in the same command:

```shell
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:

```shell
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.

### Why $OBOL on mainnet?

Buyers paying in `$OBOL` on Ethereum mainnet sign an [EIP-2612](https://eips.ethereum.org/EIPS/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](/next/community-and-governance/obol-token.md).

### 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:

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

This publishes the agent's wallet + service catalogue to the [ERC-8004](https://eips.ethereum.org/EIPS/eip-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](https://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:

```shell
# 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](/next/obol-stack/installing-networks.md) for the full set of supported networks and clients.

## Step 7: Explore

```shell
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
```

## Stopping and cleaning up

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

{% hint style="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/`.
{% endhint %}

## Next steps

* [Installing Networks](/next/obol-stack/installing-networks.md) — sync local Ethereum / Aztec nodes.
* [Installing Apps](/next/obol-stack/installing-apps.md) — deploy any Helm chart.
* [FAQ](/next/obol-stack/faq.md) — common questions and troubleshooting.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.obol.org/next/obol-stack/quickstart.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.