Prerequisites

• Python 3.12+
• Node.js 20+ (with npm)
• PostgreSQL 15+
• Hetzner Cloud account (for VM provisioning)
• Stripe account (for billing)
• Telegram Bot (created via @BotFather)
• OpenClaw installed on target VMs

Install dependencies

pip install -r requirements.txt

Install dependencies

npm install

Getting Started

2. Backend Setup

```bash cd backend

3. Frontend Setup

```bash cd frontend

Deployment

Production Setup (recommended)

Butlr is designed to run on a management server that orchestrates customer VMs:

Management Server (your server)
├── Caddy (reverse proxy + HTTPS)
├── PM2 (process manager)
│   ├── Butlr API (FastAPI on port 8000)
│   └── Butlr Frontend (Next.js on port 3000)
├── PostgreSQL
└── Cron Jobs
    ├── collect-usage.py (hourly)
    └── expire-addons.py (hourly)

Customer VMs (Hetzner Cloud)
├── OpenClaw agent runtime
├── Telegram bot connector
└── ClawShield security

Usage Statistics — Full Transparency

<p align="center"> <img src="docs/screenshots/usage-stats.png" width="800" alt="Usage Statistics" /> </p>

Complete visibility into how the butler is being used — no surprises on the bill:

• Daily Counters — messages sent today, API calls made, tokens consumed (input + output + total), all with month-over-month comparisons
• Uptime Badge — prominent 99.9% uptime indicator with exact VM uptime duration, so customers always know their butler is running
• Activity Heatmap — GitHub-style contribution grid showing daily usage intensity across the entire year. Darker squares = more activity. Hover to see exact date and message count
• System Resources — live CPU and memory usage bars with percentage labels, pulled directly from the VM
• Monthly Summary — sidebar with aggregated stats: messages this month, tokens this month, API calls this month

Usage data is collected by the scripts/collect-usage.py cron job that SSH-es into every customer VM hourly, parses OpenClaw's JSONL session logs, and writes aggregated metrics to the usage_tracking table. The frontend fetches via /api/usage/stats with date range filters.

---

Usage collection (every hour)

0 cd /path/to/butlr/backend && /path/to/venv/bin/python scripts/collect-usage.py

Create virtual environment

python -m venv venv source venv/bin/activate

Configure environment

cp .env.example .env

Edit .env with your actual values (see Environment Variables section)

Configure environment

cp .env.example .env.local

Edit .env.local — set NEXT_PUBLIC_API_URL to your backend

Environment Variables

Save PM2 config

pm2 save pm2 startup ```

Caddy Configuration

yourdomain.com {
    handle /api/* {
        reverse_proxy localhost:8000
    }
    handle {
        reverse_proxy localhost:3000
    }
}

---

Start the API server

uvicorn main:app --host 0.0.0.0 --port 8000 --reload ```

API Reference

Full interactive API docs are available at /docs when running the backend.

Key Endpoints

---

OpenClaw Integration

Butlr is a complete managed wrapper around OpenClaw. OpenClaw is the open-source AI agent framework that provides the core intelligence — Butlr wraps it with everything needed to run it as a commercial SaaS product.