☕ KOPI Agent Documentation

Singapore Coffee × AI — One command to set up your AI assistant

Introduction

KOPI Agent is a deeply customized AI agent platform based on Hermes Agent, built for Singapore and Southeast Asian users. As simple as ordering coffee at a kopitiam — pick your flavor, one command to install.

Product Line

Installation

KOPI O (Classic)

curl -fsSL https://kopiaiagent.com/install.sh | bash

KOPI Siew Dai (Less Sugar)

curl -fsSL https://kopiaiagent.com/install-siew-dai.sh | bash

Provide API Key Manually

curl -fsSL https://kopiaiagent.com/install.sh | KOPI_API_KEY=kp-xxx bash

System Requirements

• Operating System: Ubuntu 20.04+, Debian 11+, CentOS 8+, Fedora, Arch, macOS 12+
• Architecture: x86_64 / arm64 (Apple Silicon supported)
• Python: 3.11+ (auto-installed by script)
• Memory: 1GB+ recommended
• Disk: 2GB+ free space
• Network: Requires access to kopiaiagent.com

macOS Installation

Full support for Mac — no sudo required, no systemd needed.

curl -fsSL https://kopiaiagent.com/install-siew-dai.sh -o install-siew-dai.sh
bash install-siew-dai.sh

Quick Start

Interactive Chat

kopi

Chat with AI directly in your terminal. Supports tool calls, code execution, file operations, and more.

One-Shot Query

kopi "Write a Python script to batch rename files"

Switch Models

/model kopi-gau       # Switch to strong reasoning version
/model kopi-o-flash   # Switch to fast version
/model kopi-o         # Switch back to classic

CLI Commands

All commands are run from the terminal as kopi <command>. Use kopi --help for full options.

🚀 Core

🔧 Diagnostics & Configuration

🌐 Gateway & Platforms

🧩 Skills & Tools

🧠 Session & Memory

🔐 Auth & Model

📊 Other

In-Chat Commands

Slash commands available during a conversation (type /help for full list):

💬 Session Management

⚙️ Configuration

🧰 Tools & Skills

📋 Control & Info

Gateway (Messaging Gateway)

KOPI Agent can interact with you via Telegram and WeChat — use AI like chatting with a friend.

Telegram Setup

1. Search for @BotFather
2. Send /newbot to create a Bot
3. Copy the Token you receive
4. Run kopi gateway setup and enter the Token

systemd Service

systemctl start kopi-gateway     # Start
systemctl stop kopi-gateway      # Stop
systemctl status kopi-gateway    # Status
journalctl -u kopi-gateway -f    # Logs

Models

All models are proxied through KOPI Proxy — no need to bring your own API Key. Use /model <name> to switch in chat.

Skills

Automatically installs 100+ skills during setup, covering:

🔌 MCP — Model Context Protocol

What is MCP?

MCP (Model Context Protocol) is a universal standard for connecting AI models to external tools — like a USB port for the AI world.

Before MCP, every AI-tool integration required custom development. With MCP, any tool that provides an MCP Server can be plugged in instantly.

What Can MCP Do?

MCP transforms your AI from a "chat bot" into a digital worker that connects to real systems:

Native MCP in KOPI Agent

KOPI Agent has a built-in MCP client. No plugin development needed — just configure which MCP Servers to connect in your config file:

# ~/.kopi/config.yaml
mcp_servers:
  time:
    command: "uvx"
    args: ["mcp-server-time"]
  filesystem:
    command: "uvx"
    args: ["mcp-server-filesystem", "/path/to/folder"]

After configuration, when you ask "What time is it in Singapore?", the agent automatically calls the MCP time tool — no guessing, real data.

How It Works

You: "What time is it in Singapore?"
  ↓
KOPI Agent detects the question needs real-time data
  ↓
Calls MCP Server (time tool)
  ↓
Gets accurate answer from the time server
  ↓
Responds: "It's 3:45 PM SGT (UTC+8)"

The Bottom Line

📋 Use Cases

Case 1: Customer Service Automation

A retail company uses KOPI Agent to handle customer inquiries via WhatsApp. The agent connects to their order database via MCP, so when a customer asks "Where is my order #1234?", it queries the database directly and responds with real tracking info — no human needed.

Case 2: Developer Productivity

A software team connects KOPI Agent to their GitHub repos via MCP. Developers can ask "What PRs are open?" or "Summarize the latest issues" directly in Telegram. The agent reads GitHub in real-time and provides summaries.

Case 3: Business Intelligence

A SME owner connects their sales database via MCP. Every morning, they ask KOPI Agent "What were yesterday's sales?" and get instant reports — no need to log into dashboards or write SQL queries.

Case 4: Document Management

A law firm uses MCP to connect their document folder. Lawyers can ask "Find all contracts mentioning Company X" and the agent searches through files instantly, returning relevant documents with summaries.

Case 5: Multi-Platform Monitoring

A media company connects Telegram, WhatsApp, and Email via MCP. Their KOPI Agent monitors all channels and can respond, forward messages, or alert the team when urgent matters arise.

Case 6: YouTube Subtitle Archive Live

A content creator built a Subtitle Archive (字幕档案馆) powered by KOPI Agent + MCP. The system extracts YouTube video subtitles via MCP SSE Bridge, generates AI-powered content summaries, and presents them in a searchable, beautifully formatted web interface. Features include one-click subtitle extraction, automatic topic tagging, and visual content cards — all orchestrated by KOPI Agent behind the scenes.

🔗 View Live Demo →

Case 7: Quantitative Strategy Rankings Pro

A quant trading team uses KOPI Agent to automate backtesting and strategy ranking. The agent runs 320+ backtests across 16 assets and 8 strategies on 15-minute timeframes, then generates interactive ranking dashboards with Chart.js visualizations. Scoring factors include total return, Sharpe ratio, max drawdown, and win rate — all computed and published by KOPI Agent without manual intervention.

🔗 View Live Rankings →

Case 8: AI-Generated Knowledge Comics Creative

KOPI Agent generates full manga-style knowledge comics from a single topic prompt. Using the baoyu-comic skill, it creates dramatic storylines, AI-generated artwork, and multi-panel comic layouts — turning complex topics like Singapore's bird conservation crisis into engaging visual narratives. One command, complete comic book.

🔗 Read the Comic →

Case 9: Intelligent Trading Dashboard Pro

AMT Capital uses KOPI Agent to power a real-time quantitative trading dashboard. Connected to Alpaca Markets API, the system tracks portfolio value, P&L, buying power, and position details — all updated every 30 seconds. Features include a Trading Masters strategy library, Vanderbilt AI portfolio analysis, interactive equity curve charts, and one-click investment report generation. KOPI Agent orchestrates market data fetching, risk computation, and strategy execution in the background.

🔗 View Live Dashboard →

Getting Started with MCP

Ready to connect your tools? Run kopi mcp to manage MCP servers, or check the Configuration section for setup details.

Configuration

Config file is located at ~/.kopi/config.yaml:

# Model Configuration
model:
  default: kopi-o              # Default model
  provider: custom
  base_url: https://kopiaiagent.com/kp/v1
  api_key: kp-xxxxxxxx         # Auto-provisioned during install
  context_length: 256000

# Agent Configuration
agent:
  max_turns: 90

# Terminal Configuration
terminal:
  timeout: 180

# Display Configuration
display:
  skin: default
  show_cost: true

# Memory Configuration
memory:
  memory_enabled: true
  user_profile_enabled: true

Troubleshooting

Installation Failed

API Issues

Gateway Issues

Billing & Finance

KOPI includes a built-in billing engine that tracks token usage, calculates costs, generates invoices, and manages payments. All financial data is stored separately from the proxy database.

Architecture

request_logs (raw API calls, read-only)
    ↓ daily aggregation (4:00 AM)
daily_usage (per client × model × day)
    ↓ monthly invoice generation
invoices (draft → finalized, immutable)
    ↓ payment recording
payment_ledger (bank-grade audit trail)

Pricing

Finance Dashboard

Access the admin billing dashboard at https://readinghero.xyz/finance/. Features:

• Real-time revenue, cost, and margin tracking
• Daily usage charts with 14-day history
• Per-client breakdown by model
• Invoice generation and management
• Payment recording with audit trail
• Company P&L statements

Reconciliation

The billing engine includes a built-in reconciliation system that verifies request_logs matches daily_usage aggregates. Run manually:

python3 /opt/kopi-finance/billing_engine.py reconcile 2026-05-15
# → {"status": "PASS", "discrepancies": 0}

Topup System

When a client approaches or exceeds their daily token limit, the system can generate a payment link for instant topup. After payment, the client's limit is automatically increased.

Topup Packages

Flow

Client hits limit (100% usage)
    ↓
System generates payment link
    ↓
Client pays (Stripe / manual)
    ↓
Limit auto-upgraded (old + new tokens)
    ↓
Client resumes usage

API Endpoints

Client Statements

KOPI generates bank-grade client statements with full audit trail. Every financial transaction is recorded with before/after balance states.

Statement Contents

• Account Summary — Total charges, payments received, balance due
• Usage by Model — Token breakdown per AI model
• Daily Breakdown — Day-by-day usage with cost per model
• Invoice History — All invoices with payment status
• Payment Ledger — Every payment with balance_before → balance_after

Ledger Integrity

Every entry in the payment ledger includes:

• entry_type — charge, payment, refund, credit, adjustment
• balance_before — account balance before this entry
• balance_after — account balance after this entry
• source — stripe, manual, system
• reference — Stripe payment ID or manual reference

Charges do not affect the account balance — only actual payments/refunds do.

Invoice Lifecycle

draft → finalized → sent → paid
                      ↘ void (if cancelled)

Once an invoice is finalized, it cannot be edited. Adjustments are made via new ledger entries.

API Endpoints

Mockup Previews

Three statement UI styles are available for review:

• 📄 Classic Invoice — Traditional paper invoice, printable
• 📊 Modern Dashboard — Charts, cards, data-rich
• 📱 Minimal Mobile — Card-based, mobile-first