FAQ

Frequently asked questions about Obol Stack

General

What is Obol Stack?

The Obol Stack is a local Kubernetes-based environment for running AI agents alongside blockchain infrastructure. It uses k3d (Kubernetes in Docker) to provide a lightweight cluster where you can deploy an AI agent (OpenClaw), Ethereum nodes, Layer 2 networks, and other applications.

Is Obol Stack suitable for production?

No. Obol Stack is designed for local development, testing, and experimentation. For production deployments, use dedicated infrastructure with proper security, redundancy, and monitoring.

What operating systems are supported?

• macOS (Darwin) - Intel and Apple Silicon

• Linux - amd64 and arm64 architectures

Windows is not currently supported. Windows users can use WSL2 to run the Obol Stack.

What are the hardware requirements?

Resource	Minimum	Recommended
CPU	4 cores	8+ cores
RAM	8 GB	16+ GB
Storage	50 GB	500 GB - 2 TB (depends on networks)

Running multiple networks or full Ethereum mainnet nodes significantly increases resource requirements.

Installation

The installer fails with "Docker daemon not running"

Ensure Docker is installed and running:

# Check Docker status
docker info

# Start Docker (macOS)
open -a Docker

# Start Docker (Linux)
sudo systemctl start docker

How do I update the Obol Stack?

Re-run the installer:

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

The installer will update the CLI binary while preserving your configuration and data.

How do I uninstall Obol Stack?

obol stack purge -f
rm -f ~/.local/bin/{obol,kubectl,helm,k3d,helmfile,k9s,obolup.sh}
rm -rf ~/.config/obol ~/.local/share/obol

The installer cannot modify /etc/hosts

Manually add the entry:

echo "127.0.0.1 obol.stack" | sudo tee -a /etc/hosts

AI Agent (OpenClaw)

How do I set up the agent?

obol agent init

This runs the interactive OpenClaw onboard flow, which prompts you to choose a model provider (Ollama, Anthropic, or OpenAI).

How do I change the model provider?

obol openclaw setup

Or configure the global model gateway directly:

obol model setup

How do I open the agent dashboard?

obol openclaw dashboard

This starts a port-forward and opens the web UI in your browser.

How do I get the gateway token?

obol openclaw token

When only one OpenClaw instance is installed, the instance ID is auto-selected. With multiple instances, specify the name: obol openclaw dashboard my-agent.

Stack operations

The cluster fails to start

Port conflicts:

Obol Stack uses ports 80, 443, 8080, and 8443. Check for conflicts:

lsof -i :8080
lsof -i :8443

If ports 80/443 conflict, edit ~/.config/obol/k3d.yaml and remove the 80:80 and 443:443 entries (keep 8080:80 and 8443:443). Access at http://obol.stack:8080 instead.

Previous cluster not cleaned up:

k3d cluster delete --all
obol stack init --force
obol stack up

Can I use my existing kubectl configuration?

Obol Stack uses an isolated kubeconfig at ~/.config/obol/kubeconfig.yaml. To use it with standard kubectl:

export KUBECONFIG=~/.config/obol/kubeconfig.yaml
kubectl get nodes

How do I persist data across cluster restarts?

Data is automatically persisted. obol stack down stops the cluster but keeps data in ~/.local/share/obol/. Only obol stack purge -f deletes persistent data.

Networks

How do I know which deployment ID was generated?

The deployment ID is displayed when you run obol network install. You can also list deployments:

ls ~/.config/obol/networks/

Can I run multiple instances of the same network?

Yes. Each deployment gets a unique namespace:

obol network install ethereum --id=mainnet --network=mainnet
obol network install ethereum --id=hoodi --network=hoodi

How long does it take to sync an Ethereum node?

Network	Client	Approximate Time
Hoodi	Reth	2-6 hours
Hoodi	Geth	4-12 hours
Mainnet	Reth	1-3 days
Mainnet	Geth	3-7 days

Sync times depend on hardware, network connection, and chain state.

My network deployment is stuck in Pending state

obol kubectl describe pod -n <namespace> <pod-name>
obol kubectl get events -n <namespace>
obol kubectl get pvc -n <namespace>

Common causes: insufficient Docker resources, PVC not bound, image pull errors.

Troubleshooting

Error: "stack not running, use 'obol stack up' first"

Start the cluster:

obol stack up

Error: "deployment not found"

Check your deployment ID:

ls ~/.config/obol/networks/
obol network sync ethereum/correct-id

How do I report a bug?

Report issues on GitHub: https://github.com/ObolNetwork/obol-stack/issues

Include:

• Obol Stack version (obol version)

• Operating system and architecture

• Docker version (docker version)

• Steps to reproduce

• Relevant logs

Need more help?

Head over to our Discord where a member of our team or the community will be happy to assist you.