AIMeter

AIMeter is a self-hosted dashboard for tracking AI provider usage, quota, and historical trends.

English | 简体中文 | 繁體中文 | 日本語 | Français | Deutsch | Español | Português | Русский | 한국어

Features

• React frontend dashboard
• Express backend API
• Multi-provider adapter architecture
• Runtime modes: node and serverless
• Database-backed storage and bootstrap flow
• Unified dashboard across multiple AI providers
• Provider credential management and quota display
• Usage history and chart pages
• Endpoint/proxy related API pages
• Bootstrap + admin route initialization flow
• Multiple database engines: sqlite, d1, postgres, mysql
• Cloudflare Cron Triggers support via scheduled handler

Supported Providers

Aliyun	Antigravity	Claude	Codex	Kimi	MiniMax
z.ai	Copilot	OpenRouter	Ollama	OpenCode	Cursor

Provider-specific examples and integration notes: docs/providers

Tech Stack

• Frontend: React 18, TypeScript, Vite, Tailwind CSS
• Backend: Node.js, Express, TypeScript
• Storage: SQLite / Cloudflare D1 / PostgreSQL / MySQL

Project Structure

.
├─ src/                  # Frontend app
├─ server/               # Backend API, auth, jobs, storage
├─ deploy/               # Deployment guides by platform
├─ docs/                  # API docs, provider examples, translations, config docs
├─ config.all.yaml       # Full config template
├─ config.yaml           # Active local config (create by copy)
└─ .env.all              # Full env template

Quick Start

Option 1: Container (Docker)

Single-container deployment with nginx + Node.js. Data is persisted via a volume mount.

mkdir -p ~/aimeter/db ~/aimeter/log
docker run -d --name aimeter \
  -p 3000:3000 \
  -e AIMETER_DATABASE_ENGINE=sqlite \
  -e AIMETER_DATABASE_CONNECTION=/aimeter/db/aimeter.db \
  -e AIMETER_SERVER_PORT=3000 \
  -e AIMETER_BACKEND_PORT=3001 \
  -e AIMETER_RUNTIME_MODE=node \
  -v ~/aimeter/db:/aimeter/db \
  -v ~/aimeter/log:/aimeter/log \
  bugwz/aimeter:latest

Then open: http://localhost:3000

For Docker Compose, HTTPS, MySQL/PostgreSQL, or multi-arch builds: deploy/container/README.md

Option 2: Vercel

Serverless deployment on Vercel. Requires an external MySQL or PostgreSQL database.

Mode	Deploy
MySQL
PostgreSQL

Set env vars, complete bootstrap, then configure an external cron service to call /api/system/jobs/refresh every 5 minutes.

For cron setup and full configuration: deploy/vercel/README.md

Option 3: Cloudflare Workers

Serverless deployment on Cloudflare Workers. Supports Cloudflare D1, MySQL, or PostgreSQL.

After deploying, set runtime env vars by database mode:

Mode	Required env vars
D1	AIMETER_RUNTIME_MODE=serverless AIMETER_SERVER_PROTOCOL=https AIMETER_DATABASE_ENGINE=d1 AIMETER_DATABASE_CONNECTION=DB
MySQL	AIMETER_RUNTIME_MODE=serverless AIMETER_SERVER_PROTOCOL=https AIMETER_DATABASE_ENGINE=mysql AIMETER_DATABASE_CONNECTION=mysql://USER:PASSWORD@HOST:3306/DATABASE
PostgreSQL	AIMETER_RUNTIME_MODE=serverless AIMETER_SERVER_PROTOCOL=https AIMETER_DATABASE_ENGINE=postgres AIMETER_DATABASE_CONNECTION=postgres://USER:PASSWORD@HOST:5432/DATABASE?sslmode=require

Cron Triggers are built-in — wrangler.jsonc schedules a refresh every 5 minutes automatically.

For D1 binding, Hyperdrive, and full setup steps: deploy/cloudflare/README.md

Scripts

npm run dev            # frontend only
npm run start:server   # backend only
npm run dev:all        # frontend + backend
npm run dev:mock:all   # frontend + backend (mock mode)
npm run build          # type-check and build frontend
npm run preview        # preview frontend build
npm run cf:dev         # local Cloudflare Workers dev (Wrangler)
npm run cf:deploy      # deploy to Cloudflare Workers

Configuration

Config sources and priority in current implementation:

1. config.yaml (or path from AIMETER_CONFIG_FILE)
2. Environment variables
3. Built-in defaults

Important:

• database.engine / AIMETER_DATABASE_ENGINE is required.
• database.connection / AIMETER_DATABASE_CONNECTION is required.
• In serverless mode, in-process scheduler is disabled; use CF Cron Triggers or an external scheduler.
• In node mode, in-process scheduler starts automatically.

Detailed field mapping and explanations:

• docs/conf/README.md

Deployment

Supported deployment modes and links:

• deploy/README.md
• deploy/container/README.md
• deploy/cloudflare/README.md
• deploy/vercel/README.md

API Documentation

• docs/api/README.md

Security Notes

• Session secret and encryption-related settings are initialized and persisted by system storage during bootstrap in database mode.
• AIMETER_CRON_SECRET and AIMETER_ENDPOINT_SECRET are optional integration secrets; when provided, use strong 32-char random values.
• Use AIMETER_SERVER_PROTOCOL=https in production to enable strict transport-related security headers.