Kopern

The open-source platform to build, grade, and deploy AI agents — no code required.

Features · Quick Start · Why Kopern · Architecture · MCP · Contributing

Describe your agent in plain text. Kopern builds it, tests it, optimizes it, and deploys it — in under a minute.

Why Kopern?

Most AI agent tools are frameworks — they give you building blocks and wish you luck. Kopern is a platform: build, test, deploy, and monitor in one place.

Kopern is what you'd build if you started from the problem — "How do I ship a production AI agent today?" — instead of the technology.

Quick Start

Prerequisites

• Node.js >= 20
• A Firebase project (Firestore + Auth)
• At least one LLM API key (Anthropic, OpenAI, or Google)

Install

git clone https://github.com/berch-t/kopern.git
cd kopern
npm install
cp .env.example .env.local   # Edit with your keys
npm run dev                   # http://localhost:3000

Environment Variables

# Firebase Client (public)
NEXT_PUBLIC_FIREBASE_API_KEY=...
NEXT_PUBLIC_FIREBASE_AUTH_DOMAIN=your-project.firebaseapp.com
NEXT_PUBLIC_FIREBASE_PROJECT_ID=your-project
NEXT_PUBLIC_FIREBASE_STORAGE_BUCKET=your-project.firebasestorage.app
NEXT_PUBLIC_FIREBASE_MESSAGING_SENDER_ID=...
NEXT_PUBLIC_FIREBASE_APP_ID=...

# Firebase Admin (server-side only)
FIREBASE_PROJECT_ID=your-project
FIREBASE_CLIENT_EMAIL=firebase-adminsdk-...@your-project.iam.gserviceaccount.com
FIREBASE_PRIVATE_KEY="-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----\n"

# Stripe (optional — billing features)
STRIPE_SECRET_KEY=sk_...
STRIPE_WEBHOOK_SECRET=whsec_...
NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=pk_...

# LLM API Keys (add the ones you need)
ANTHROPIC_API_KEY=sk-ant-...
OPENAI_API_KEY=sk-...
GOOGLE_AI_API_KEY=AI...
OLLAMA_BASE_URL=http://localhost:11434

# Admin (optional)
NEXT_PUBLIC_ADMIN_UID=your-firebase-uid

# Service Connectors — OAuth (optional)
GOOGLE_OAUTH_CLIENT_ID=...
GOOGLE_OAUTH_CLIENT_SECRET=...
MICROSOFT_OAUTH_CLIENT_ID=...
MICROSOFT_OAUTH_CLIENT_SECRET=...
ENCRYPTION_KEY=...  # 64-char hex: node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"

# Slack Bot (optional)
SLACK_CLIENT_ID=...
SLACK_CLIENT_SECRET=...
SLACK_SIGNING_SECRET=...

# Rate Limiting (optional)
UPSTASH_REDIS_REST_URL=...
UPSTASH_REDIS_REST_TOKEN=...

Deploy Firestore Rules

firebase deploy --only firestore:rules,firestore:indexes

Tech Stack

Features

Agent Builder

• AI Agent Wizard — Describe your agent in plain text, get a fully configured agent (system prompt, skills, tools, extensions, grading suite) generated as structured JSON
• Zero-Code Onboarding — Template gallery (28 general + 9 vertical business templates) with guided questionnaire and 1-click deploy
• Visual Configuration — System prompts, markdown skills, custom tools (sandboxed JS), TypeScript extensions, branding (custom icons + colors)
• Multi-Model — Anthropic (Claude), OpenAI (GPT), Google (Gemini), Ollama (local) via unified streaming with key rotation failover (up to 5 keys/provider)
• Extended Thinking — 6 levels (off, minimal, low, medium, high, xhigh)
• Agent Memory — Persistent key-value memory across sessions, auto-injected in context, LRU eviction, cross-session search
• Context Compaction — Automatic Haiku-based summarization of old messages when context window fills up

Built-in Agent Tools

• web_fetch — Server-side HTTP fetch (GET/POST/PUT/DELETE), HTML-to-text extraction, anti-loop protection
• code_interpreter — Python, Node.js, and Bash execution via GCP Cloud Run (numpy, pandas, matplotlib pre-installed, auto-scale 0-10, 300s timeout)
• Agent Memory — remember, recall, forget, search_sessions tools
• Email (Gmail + Outlook) — read_emails, send_email, reply_email via OAuth
• Calendar (Google + Microsoft) — list_events, check_availability, create_event, update_event, cancel_event
• GitHub — read_file, search_files, create_branch, commit_files, create_pull_request
• Image Generation — Google Gemini gemini-3.1-flash-image-preview, auto-upload to Firebase Storage
• Social Media — social_create_post, social_create_thread, social_read_feed, social_get_metrics, social_search_mentions, social_reply (Bluesky AT Protocol)
• Bug Management — list_bugs, get_bug, update_bug_status, send_thank_you_email (admin-only)

Grading and Optimization Lab

• Deterministic Grading — 6 criteria: output match, schema validation, tool usage, safety check, custom script, LLM judge
• Improvement Notes — Post-grading LLM analysis generates actionable suggestions (system prompt, skill, tool, general) with quick-apply buttons and optimization pipeline integration
• Scheduled Grading — Vercel Cron with configurable schedule, score drop and threshold alerts via email/Slack/webhook
• AutoTune — Iterative prompt refinement via hill-climbing, guided by improvement notes from previous grading
• AutoFix — One-click diagnosis and patch for failed test cases (self-sufficient: generates its own test suite if needed), uses improvement notes as high-priority context
• Stress Lab — Automated red team: prompt injection, jailbreaks, hallucination traps, with auto-hardening
• Tournament — A/B model arena to find the best config
• Distillation — Same quality, fraction of the cost
• Evolution — Parallel search across prompt x model x config space

Deploy Everywhere

• Embeddable Widget — Drop-in <script> tag for any website (Shadow DOM, SSE, markdown, mobile-responsive)
• Slack Bot — OAuth install, @mention/DM, thread context, conversational tool approval
• Telegram Bot — Webhook-based, async processing, conversational tool approval
• WhatsApp — Cloud API (Meta Business), conversational tool approval
• Webhooks — Inbound (sync JSON, HMAC) + Outbound with anti-loop protection
• MCP Protocol — Real Streamable HTTP server for Claude Code, Cursor, and any MCP client
• n8n / Zapier / Make — Native integration via HTTP Request nodes

Visual Orchestration (React Flow)

• Flow Editor — Drag-and-drop node editor with 5 node types: Agent, Condition, Trigger, Output, Export
• Node Configuration — Double-click to edit any node; full agent config editing without leaving the page
• Agent Branding — Custom icons and colors visible on team flow nodes
• Export Node — Choose output format (JSON, CSV, Markdown, PDF) with auto-download
• Runtime Status — Live node status updates during team execution
• Auto-layout — Automatic parallel/sequential/conditional layout
• Activity Timeline — 8-action audit trail for team operations
• Kanban Board — 6-column drag-drop task management
• Goal Tree — Collapsible goal hierarchy with progress bars
• Org Chart — SVG organizational chart with Buchheim-Walker layout
• Routine Scheduler — CRON-based recurring team tasks
• Budget Enforcer — Team spend tracking and budget limits
• Pipelines — Multi-step workflows with input mapping and per-step tool calling
• Sub-agent Delegation — Coordinator agents delegate subtasks to specialists

Operator Dashboard

• KPI Cards — Messages, resolution rate, satisfaction, cost at a glance
• One-click AutoFix — Improve your agent with zero technical knowledge
• Simplified Edit Form — Re-answer onboarding questions to update agent behavior
• Memory Panel — View, add, delete agent memories with usage indicator
• Connector Status — See which channels are active with dedicated config pages
• Service Connector Panel — Connect/disconnect Google and Microsoft OAuth

Workflow Quality Monitor

• Public Diagnostic — Free /monitor page: 18 standardized prompts across 6 criteria (reasoning, instruction following, consistency, latency, edge cases, output quality)
• 29 Model Baselines — Hardcoded reference scores for Anthropic, OpenAI, Google, and Mistral models
• Animated Score Card — Count-up animation with SVG ring, radar chart (cyan user / amber baseline overlay)
• Insight Cards — [CRITICAL] and [SUGGESTION] parsed into expandable severity-coded cards
• Shareable Reports — Dedicated /monitor/{runId} page, JSON download, Twitter sharing, OG images
• Monitor Team — Auto-creates 4 specialized agents (Prompter, Scorer, Comparator, Reporter) on signup
• Phase 2 planned — Connected monitoring for your agents with drift detection, alerts, and 5 MCP tools

Agent Grader (Public)

• Free Prompt Grading — /grader page: paste a system prompt + test cases, get a radar chart scorecard
• Endpoint Mode — Grade external HTTP agent endpoints (OpenAI/Anthropic/Google format auto-detect)
• Shareable Scorecards — OG image generation for social sharing

Social Media Tools

• Bluesky Integration — AT Protocol V1: create posts/threads, read feed, search mentions, reply, get metrics
• Encrypted Credentials — AES-256-GCM stored in Firestore
• Daily Limits — Per-platform rate limiting for safety

Blog

• Integrated Blog — /blog with Markdown files (gray-matter), reading time, i18n locale fallback
• SEO — Article JSON-LD, breadcrumbs, speakable, dynamic sitemap

Billing and Security

• Stripe Billing — Subscriptions + usage-based meters, customer portal
• Plan Enforcement — Token, agent, grading, team, pipeline, MCP limits
• Rate Limiting — 8 Upstash Redis sliding window limiters
• Input Validation — Zod v4 schemas on all API routes
• Tool Approval — EU AI Act Art. 14 human oversight for destructive actions (interactive SSE + conversational on messaging channels)
• Encrypted OAuth Tokens — AES-256-GCM, daily limits (20 emails/day, 10 events/day per agent)
• CSP Headers — Content Security Policy on all routes

Platform

• Internationalization — Full English/French (800+ keys each)
• Dark Mode — OKLch color system
• Mobile Responsive — Sheet drawer sidebar
• Session Tracking — Conversation timelines, JSON export
• Version Control — Snapshot agents, track grading per version, auto-increment on prompt change
• Bug Fixer Agent — Autonomous dev agent: reads codebase, creates PR, sends thank-you email
• EU AI Act Compliance — Automated compliance reports (Art. 6, 12, 14, 52)

Architecture

                    +------------------+
                    |   Next.js App    |
                    |   (App Router)   |
                    +--------+---------+
                             |
              +--------------+--------------+
              |              |              |
        +-----+-----+  +-----+----+  +------+-----+
        | Dashboard |  |   API    |  |  Landing   |
        | (auth)    |  |  Routes  |  |  (public)  |
        +-----------+  +----+-----+  +------------+
                            |
       +--------------------+--------------------+
       |         |          |          |          |
  +----+---+ +--+-----+ +--+----+ +--+------+ +-+------+
  |  Chat  | |Grading | |  MCP  | |Connectors| | Teams |
  |  SSE   | |  Lab   | |Server | | (5 ch.)  | | (Flow)|
  +----+---+ +---+----+ +---+---+ +---+------+ +----+--+
       |         |          |         |             |
  +----+--------+-----------+---------+-------------+--+
  |                  runAgentWithTools()               |
  |         (shared agentic loop — all routes)         |
  +----+------------+------------+--------------+------+
       |            |            |              |
  +----+----+   +---+----+   +---+----+   +-----+------+
  |streamLLM|   |Firebase |  |Stripe  |   |GCP Cloud   |
  |(multi-  |   |Admin SDK|  |Billing |   |Run (code   |
  |provider)|   |Firestore|  |Meters  |   |interpreter)|
  +---------+   +---------+  +--------+   +------------+

Firestore Schema

users/{userId}
  /agents/{agentId}
    /skills, /tools, /extensions, /versions
    /memory/{key}                    # Agent memory (LRU eviction, keyword search)
    /gradingSuites/{suiteId}/cases, /runs/{runId}/results
    /autoresearchRuns/{runId}/iterations
    /pipelines/{pipelineId}, /sessions/{sessionId}
    /connectors/widget, /connectors/slackConnection
    /webhooks/{webhookId}, /webhookLogs/{logId}
    /mcpServers/{serverId}/usage/{yearMonth}
  /serviceConnectors/{provider}     # Encrypted OAuth tokens (AES-256-GCM)
  /agentTeams/{teamId}
    /activity/{activityId}          # 8-action audit trail
    /tasks/{taskId}                 # Kanban task board
    /routines/{routineId}           # CRON scheduled routines
  /goals/{goalId}
  /usage/{yearMonth}               # Token + cost tracking with agent breakdown
  /bugs/{bugId}
monitorRuns/{runId}                  # Workflow quality diagnostic results
apiKeys/{sha256Hash}                # MCP API keys (O(1) lookup)
slackTeams/{teamId}                 # Slack workspace index
telegramBots/{hash}                 # Telegram bot routing
whatsappPhones/{phoneId}            # WhatsApp phone routing

API Routes

MCP Integration

Kopern exposes its entire platform as an MCP server — 32 tools for the full agent lifecycle, from creation to deployment to monitoring. Works with Claude Code, Cursor, Windsurf, and any MCP client.

Setup

Option A — Platform key (recommended for most use cases):

1. Sign up on kopern.ai
2. Go to Settings > Personal API Key — generate a key
3. Add to your .mcp.json:

{
  "mcpServers": {
    "kopern": {
      "type": "http",
      "url": "https://kopern.ai/api/mcp/server",
      "headers": {
        "Authorization": "Bearer kpn_your_api_key_here"
      }
    }
  }
}

Option B — Agent-bound key (for chat + agent-specific tools):

1. Create an agent in Kopern
2. Go to MCP/API tab > generate an API key
3. Same .mcp.json format — this key unlocks kopern_chat and kopern_agent_info in addition to all platform tools.

Available MCP Tools (32)

Agent-Bound Only (require agent key)

Agent CRUD

Templates

Grading & Optimization

Teams & Pipelines

Connectors

Monitoring & Data

Plan Limits

Deployment

Vercel (Recommended for SaaS)

# 1. Push to GitHub
# 2. Import in Vercel
# 3. Add env vars in Vercel dashboard
# 4. Deploy

Self-Hosted (Docker)

Run Kopern on your own infrastructure. Ideal for enterprises with data sovereignty requirements or teams wanting full local operation with Ollama.

git clone https://github.com/berch-t/kopern.git
cd kopern
cp .env.example .env.local
# Edit .env.local with your Firebase + LLM keys
docker compose up -d
# Open http://localhost:3000

Full local mode (no cloud dependencies):

1. Uncomment the firebase-emulator service in docker-compose.yml
2. Uncomment the ollama service for local LLMs
3. Set FIRESTORE_EMULATOR_HOST=firebase-emulator:8080 in .env.local
4. Set OLLAMA_BASE_URL=http://ollama:11434 in .env.local
5. No Stripe keys needed — billing features are disabled without them

Enterprise LLM support:

• Ollama — already supported, full local, zero API calls
• Azure OpenAI — use azure-openai provider with your deployment endpoint
• Any OpenAI-compatible endpoint — use openai provider with custom OPENAI_BASE_URL for vLLM, TGI, or internal LLMs

Stripe Setup

1. Create products/prices in Stripe Dashboard
2. Create Billing Meters for usage tracking
3. Configure webhook: https://your-domain.com/api/stripe/webhook
4. Register events: checkout.session.completed, customer.subscription.*, invoice.*

Contributing

We welcome contributions of all kinds. See CONTRIBUTING.md for guidelines.

Good first issues:

• New vertical templates for specific industries
• Translations beyond EN/FR
• New LLM provider support
• Pre-built tool integrations (Notion, Linear, Discord...)
• Custom connector plugins (when Plugin SDK ships)
• Documentation and tutorials

Development

npm install       # Install dependencies
npm run dev       # Dev server on :3000
npm run build     # Production build
npm run lint      # ESLint
npx tsc --noEmit  # Type check

Security

See SECURITY.md for vulnerability reporting.

Roadmap

• Agent Builder + Playground
• Grading Engine (6 criteria)
• Optimization Lab (6 modes)
• 5 Connectors (Widget, Slack, Telegram, WhatsApp, Webhooks)
• MCP Protocol — 32 tools (Streamable HTTP, Vague 1 + 2)
• Agent Memory + Context Compaction
• Service Connectors (Gmail, Outlook, Google Calendar, Microsoft Calendar)
• Operator Dashboard (no-code agent management)
• EU AI Act Compliance Tools
• Zero-Code Onboarding + 37 Templates (28 general + 9 vertical)
• Code Interpreter (Python/Node/Bash via GCP Cloud Run)
• web_fetch builtin (server-side HTTP fetch)
• Agent Teams + Visual Orchestration (React Flow v12)
• Conversational Tool Approval (Telegram/WhatsApp/Slack)
• Scheduled Grading + Alerts (Vercel Cron)
• Self-Hosted Docker deployment (docker-compose + Ollama)
• Agent Export/Import (portable JSON)
• Agent Grader — public prompt grading + endpoint mode
• Social Media Tools (Bluesky AT Protocol)
• Prompt Cache Preservation (~90% cost reduction on repeated calls)
• Extended Thinking / Effort Levels (6 levels, 3 providers)
• Image Generation (Gemini, Firebase Storage)
• Blog Infrastructure (Markdown, JSON-LD, sitemap)
• Workflow Quality Monitor (18 prompts, 6 criteria, 29 model baselines)
• Improvement Notes Pipeline (LLM judge suggestions → AutoFix/AutoTune, quick-apply, MCP parity)
• Connected Monitoring (drift detection, alerts, 5 MCP tools)
• Template Marketplace
• Connector Plugin SDK
• TypeScript SDK
• Customer Discovery (Grenoble/Rhone-Alpes)
• Concierge Pilots + First Paying Customers

License

MIT — use it, fork it, build on it.

_{Built with coffee and ambition in Grenoble, France.}