KeeperHub

A Web3 workflow automation platform that enables users and Agents to create, manage, and execute blockchain automation workflows and tasks. Supports smart contract monitoring, token transfers, DeFi operations, and integrations with Discord, SendGrid, webhooks and more.

Core Value

Users and Agents can build and deploy Web3 automation workflows through a visual builder or via the MCP server without writing code.

Add KeeperHub to your Agent

Quick setup (no install needed):

claude mcp add --transport http keeperhub https://app.keeperhub.com/mcp

Then run /mcp inside Claude Code to authorize via browser. That's it.

Try asking Claude to "create a workflow that monitors a wallet".

Alternative: install the Claude Code plugin for skills and slash commands:

/plugin marketplace add KeeperHub/claude-plugins
/plugin install keeperhub@keeperhub-plugins
/keeperhub:login

Restart Claude Code after setup. Plugin source code.

What KeeperHub Does

• Visual Workflow Builder: Drag-and-drop interface for building blockchain automations
• Smart Contract Interactions: Read and write to smart contracts without writing code
• Multi-Chain Support: Ethereum Mainnet, Sepolia, Base, Arbitrum, and more
• Secure Wallet Management: Para-integrated MPC wallets with no private key exposure
• Notifications: Email, Discord, Slack, and webhook integrations
• Scheduling: Cron-based, event-driven, webhook, or manual triggers
• AI-Assisted Building: Describe automations in plain language

Key Features

Triggers

• Scheduled: Run at intervals (every 5 minutes, hourly, daily, custom cron)
• Webhook: Execute when external services call your workflow URL
• Event: React to blockchain events (token transfers, contract state changes)
• Manual: On-demand execution via UI or API

Actions

• Web3: Check Balance, Read Contract, Write Contract, Transfer Funds, Transfer Tokens
• Notifications: Send Email, Discord Message, Slack Message, Telegram Message
• Integrations: Send Webhook, custom HTTP requests

Conditions

• Low balance detection
• Value comparisons
• Custom logic with AND/OR operators

Development Setup

Prerequisites

• Node.js 22 (Next.js 16 requires >=20.9.0; Node 18 will not work)
• pnpm package manager
• PostgreSQL 16 (only for "Local Development" mode below; Docker and Hybrid modes start their own Postgres in a container)
• Docker Engine with the Compose plugin (only for Docker and Hybrid modes)
• A LocalStack auth token (only for Docker and Hybrid modes; the compose file uses the Pro image and refuses to boot without it). Free dev tokens are available at https://app.localstack.cloud.

Environment Variables

Copy .env.example to .env and fill in the keys you need. Use .env, not .env.local: drizzle-kit (used by pnpm db:push) reads .env only.

The minimum keys needed to boot the dev server are:

# Database
DATABASE_URL=postgresql://user:password@localhost:5432/keeperhub

# Authentication
BETTER_AUTH_SECRET=your-secret-key
BETTER_AUTH_URL=http://localhost:3000

# Required for Docker and Hybrid modes (LocalStack Pro license)
LOCALSTACK_AUTH_TOKEN=your-localstack-token

Feature-specific keys (AI, Para wallets, encryption, OAuth providers, etc.) are listed in .env.example and only need values when you exercise that feature.

Installation

pnpm install
pnpm db:push
pnpm dev

Visit http://localhost:3000 to get started. The first request triggers a Next.js dev compile that can take 30-60 seconds; subsequent requests are fast.

Running Modes

Local Development (Simplest)

For UI/API development without Docker. Requires PostgreSQL running on the host.

pnpm install
pnpm db:push
pnpm dev

Dev Mode with Docker

Full development stack with scheduled workflow execution.

The compose file declares four resources as external: true. Create them once before the first make dev-setup:

docker network create keeperhub-network
docker volume create keeperhub_db_data
docker volume create keeperhub_node_modules
docker volume create keeperhub_localstack_data

Then:

make dev-setup    # First time (starts services + migrations)
make dev-up       # Subsequent starts
make dev-logs     # View logs
make dev-down     # Stop services

Services: PostgreSQL (5433), LocalStack SQS (4566), Redis (6379), KeeperHub App (3000), Scheduler, Block Dispatcher, Event Tracker, Executor.

Hybrid Mode with K8s Jobs

For testing workflow execution in isolated K8s Job containers. Requires Docker, kubectl and minikube on the host. Run as a regular user, not root - Minikube refuses the docker driver under root.

Create the same four external Docker resources as for Dev mode (see above) before the first run:

docker network create keeperhub-network
docker volume create keeperhub_db_data
docker volume create keeperhub_node_modules
docker volume create keeperhub_localstack_data

Then:

make hybrid-setup     # Full setup
make hybrid-status    # View status
make hybrid-down      # Teardown

Common Commands

# Development
pnpm dev              # Start dev server
pnpm build            # Production build
pnpm type-check       # TypeScript check
pnpm check            # Run linter
pnpm fix              # Fix linting issues

# Database
pnpm db:push          # Push schema changes
pnpm db:studio        # Open Drizzle Studio
pnpm db:seed          # Seed chain data

# Plugins
pnpm discover-plugins # Scan and register plugins
pnpm create-plugin    # Create new plugin

# Testing
pnpm test             # Run all tests
pnpm test:e2e         # E2E tests

Codebase Understanding

This repo ships an Understand-Anything knowledge graph at .understand-anything/knowledge-graph.json plus a Claude Code plugin for exploring it. The graph is a structural map of files, functions, imports, and architectural layers; the dashboard is a force-directed visualization.

Install (one-time, per developer): in Claude Code at the repo root:

/plugin marketplace add Lum1104/Understand-Anything
/plugin install understand-anything

Restart Claude Code, then:

/understand-dashboard           # interactive graph at http://127.0.0.1:5173
/understand-chat <question>     # Q&A over the graph
/understand-diff                # impact analysis of uncommitted changes
/understand-onboard             # guided tour for new contributors
/understand --full              # full re-index after a large refactor

Auto-refresh on commit is intentionally off in this repo (it would couple the graph to every PR diff). Refresh on cadence: weekly /understand for incremental, /understand --full after wide-blast-radius refactors. See CLAUDE.md for when each command is most useful and the known caveats.

Architecture

Services

Long-running

Ephemeral

All trigger services (schedule dispatcher, block dispatcher, event tracker) send messages to a shared SQS queue. The executor consumes from this queue and runs workflows in isolated K8s Job containers using the workflow-runner image. The execution mode is configurable via EXECUTION_MODE: isolated (default, all workflows in K8s Jobs), complex (K8s Jobs for web3 writes, in-process for everything else), or process (all in-process, no K8s).

Tech Stack

• Framework: Next.js 16 (App Router) with React 19
• Language: TypeScript 5
• UI: shadcn/ui, Radix UI, Tailwind CSS 4
• Database: PostgreSQL with Drizzle ORM
• Workflow Engine: Workflow DevKit
• Authentication: Better Auth
• AI: Vercel AI SDK (OpenAI/Anthropic)
• Wallets: Para MPC integration

Plugin System

Plugins extend workflow capabilities. Located in keeperhub/plugins/:

• web3 - Blockchain operations (balance, transfers, contract calls)
• discord - Discord notifications
• sendgrid - Email via SendGrid
• webhook - HTTP integrations
• telegram - Telegram notifications

API

Base URL: https://app.keeperhub.com/api

Endpoints

See API Documentation for full reference.

Observability

Prometheus metrics exposed at /api/metrics:

• Workflow execution performance
• API latency
• Plugin action metrics
• User and organization stats

See Metrics Reference for details.

Documentation

Full documentation available at docs.keeperhub.com or in the docs/ directory:

• Quick Start Guide
• Core Concepts
• Workflow Examples
• API Reference
• Security Best Practices

License

Apache 2.0