Evotown — Enterprise Agent Governance & Capability Platform

In one sentence: Evotown is the private control plane for enterprise Agents — employees keep running OpenClaw, Hermes, or SkillLite on their machines; IT uses Evotown to unify models, Skills, knowledge, and compliance in one place.

Evotown is a middle platform for enterprise Agent runtime governance and capability assets — connect multiple runtimes, accumulate Skills and enterprise knowledge, and provide observability, review, and private distribution.

Runners stay where they are (laptops, CI, servers, containers). Evotown is the control plane above them — not an IM suite, not a ChatGPT clone for every employee, and not a replacement for your Agent runtime.

The repo also ships an Evolution Arena for benchmarks, team learning, and reproducible evolution experiments.

Language: English | 中文

---

Elevator pitch (30 seconds)

Your company already runs Agents on laptops (OpenClaw, Hermes, …). Evotown gives IT a self-hosted layer to:

1. Route models through one gateway (identity, quotas, audit, cost attribution)
2. Distribute Skills from a private SkillHub (review, team scope, signed packages)
3. Connect knowledge (Feishu, Yuque, native KB) without locking a single vendor
4. Observe runs — engines, conversations, risk events — without moving execution into the cloud

IT deploys once; employees paste two lines of config. Business apps (DingTalk/Feishu bots, internal copilots) consume the same APIs.

→ Recommended path: Enterprise quickstart (IT one-click + employee config)

---

What Evotown is — and what it is not

Evotown is	Evotown is not
Agent governance & capability middle platform	Universal “enterprise AI chat” for all staff
Runtime-neutral control plane (OpenClaw / Hermes / SkillLite / custom)	Hosted Agent sandbox that replaces local runtimes
Private model gateway + SkillHub + knowledge connectors	Competing with cloud LLM APIs (OpenAI, Azure, …)
Open source, self-hosted, evidence-based asset promotion	Low-code iPaaS or generic integration bus
Optional Evolution Arena for R&D and benchmarks	Required to use Agents in production

Product principles: runtime-neutral · evidence-based asset promotion · private deploy · control without lock-in.

---

Architecture

  Employee laptop / CI / server          Your network (Docker / K8s)
  OpenClaw · Hermes · SkillLite              ┌─────────────────────────────┐
       │  two-line env config                │  Evotown control plane       │
       │  OPENAI_BASE_URL → gateway           │  · Gateway (→ LiteLLM)       │
       │  manifest → SkillHub               │  · Private Skills Market     │
       └──────────────────────────────────►│  · Knowledge + Console       │
                                             │  · Runs / cost / risk        │
                                             └──────────────┬──────────────┘
                                                            │
                                             Business apps (bots, copilots, CRM)

Layer	Role
Runtime	OpenClaw / Hermes / SkillLite / custom agents execute locally
Evotown (this repo)	Gateway, accounts, SSO; private Skills Market; knowledge; engine registry; runs, costs, risk
Business apps	DingTalk/Feishu bots, internal copilots, CRM agents — consume skills & knowledge via API

---

Core capabilities (enterprise MVP)

Pillar	What you get
Govern	Console accounts (evk_ keys), OIDC SSO, team-scoped assets, skill review & deprecate, API key lifecycle
Route	OpenAI-compatible gateway in front of LiteLLM; alias-based model routing; streaming; quotas & burst limits
Distribute	Private Skills Market — upload, manifest, employee download; package signing; OpenClaw official-format plugin
Accumulate	Knowledge connectors (Feishu / Yuque) + native KB with chunk citation search
Observe	Engine registry, runs timeline, gateway usage, conversations, cost & risk events
Land fast	scripts/enterprise-deploy.sh, evotown-agent-setup.py (check / sync / watch), MDM install scripts

The Arena remains the visual simulation layer for evolution experiments and demos — optional for production Agent rollout.

---

How Evotown compares (open source landscape)

Many projects cover part of this stack; few combine runtime-neutral local Agents + private SkillHub + gateway governance in one self-hosted control plane.

Category	Examples	Overlap with Evotown
LLM gateway only	LiteLLM, Portkey	Evotown uses LiteLLM for provider routing; adds enterprise identity, audit, SkillHub
Chat / RAG for end users	Onyx, Dify, LibreChat	End-user chat UI; Evotown focuses on Agent runtime governance, not replacing ChatGPT
Full-stack Agent platform	Synkora, LiteLLM Agent Platform	Often hosts agents & channels; Evotown does not host runtimes — they stay on employee machines
Agent control plane	Keviq Core, Kagenti	Closer on governance/orchestration; Evotown is lighter and optimized for OpenClaw/Hermes enterprise rollout
Skill / tool registry	MCP gateways, tool hubs	Partial overlap with private Skills Market only

Differentiation: compose with existing runtimes · private SkillHub as a first-class asset · IT one-click deploy + employee two-line config · optional Evolution Arena for R&D.

---

Platform surfaces (MVP)

Route	Purpose
/	Enterprise landing page
/login	Console register / login (evk_ API keys, optional OIDC SSO)
/dashboard … /risk	Enterprise console (engines, runs, gateway, costs, risk, …)
/gateway	Gateway usage + model route management
/accounts	Gateway accounts & API keys
/market	Skills catalog & employee install guidance
/skills	Admin: upload, review, deprecate skills
/knowledge	Knowledge sources (Feishu / Yuque / native), tree editor, chunk search
/arena	Evolution arena (Phaser map, observer panel)
/task-history	Task history and judge scores
/chronicle	Organizational learning log

Specs: spec/README.md · enterprise control plane · knowledge connector · Skills market

---

Enterprise landing (recommended)

For teams with OpenClaw / Hermes on employee laptops:

# IT — one-click deploy (see script for env vars)
./scripts/enterprise-deploy.sh

Employee machine — two lines (from deploy-output/evotown.agent.env):

OPENAI_BASE_URL=https://evotown.company.internal/api/gateway/v1
OPENAI_API_KEY=evk_xxxxxxxx

Doc	Link
Enterprise quickstart (中文)	docs/zh-CN/ENTERPRISE_QUICKSTART.md
MDM rollout	docs/zh-CN/MDM_AGENT_ROLLOUT.md
API key lifecycle	docs/zh-CN/ENTERPRISE_KEY_LIFECYCLE.md
OpenClaw plugin	integrations/openclaw/evotown/
Private Skills Market	docs/zh-CN/PRIVATE_SKILLS_MARKET_DEPLOYMENT.md

---

Evolution testing (original focus)

Puts evolution engines in a controlled environment for evolution effect validation — OpenClaw-style stacks, Hermes, your own harness, or optionally SkillLite. Evotown does not require a specific upstream; use the ingest API to attach runners. Economy rules are configurable, reproducible, fully local, and do not depend on virtual/cryptocurrency.

---

Prerequisites

• Python 3.10+
• Node.js 18+
• Skills workspace: backend expects a project tree with .skills or skills (layout depends on the agent backend you wire in).
• SkillLite (optional): only if you drive agents with the SkillLite CLI — then skilllite evolution run / skilllite agent-rpc and the default per-agent copy under ~/.skilllite/arena/{agent_id}/.skills apply. Other engines use their own install paths and report via HTTP ingest instead.

Quick Start

Option A — Docker (Recommended)

Requires Docker Desktop (or Docker Engine + Compose plugin).

cd evotown

# 1. Create .env from the template (same directory as docker-compose.yml)
cp .env.example .env
# Edit API_KEY / BASE_URL / MODEL, and optional per-channel overrides (JUDGE, DISPATCHER, SOCIAL, CHRONICLE)

# 2. First-time: build images and start
docker compose up -d --build

# Subsequent starts (no rebuild needed)
docker compose up -d

# Stop
docker compose down

Visit http://localhost — landing page; open Console, Skills Market, or Arena from the nav.

Note: .env must be placed in the evotown/ directory (same level as docker-compose.yml). Docker Compose reads it automatically on startup.

Option B — Local Dev (two terminals)

# Terminal 1 — Backend
cd evotown/backend
pip install -r requirements.txt
uvicorn main:app --host 0.0.0.0 --port 8765

# Terminal 2 — Frontend
cd evotown/frontend
npm install
npm run dev

Visit http://localhost:5174

Data directory: Local dev and Docker both persist arena state, task history, and logs under evotown/data/. Override with EVOTOWN_DATA_DIR when needed.

Configuration

Copy .env.example to .env and fill in at least the main BASE_URL, API_KEY, and MODEL. Optional per-channel overrides (JUDGE_*, DISPATCHER_*, SOCIAL_*, CHRONICLE_*) let high-frequency flows use a cheaper model while judge and chronicle keep a stronger one. Docker Compose also accepts OPENAI_API_KEY / OPENAI_BASE_URL as aliases for the main channel.

External engine ingest uses bearer auth. Set EVOTOWN_ENGINE_INGEST_TOKEN for OpenClaw / Hermes / custom runners. For local dev only, EVOTOWN_DEV_ALLOW_ADMIN_TOKEN_FALLBACK=1 allows ingest writes to fall back to ADMIN_TOKEN. Console APIs accept X-Admin-Token or Bearer evk_ keys with console.read / console.write scopes (register at /login).

Optional enterprise env vars:

Variable	Purpose
EVOTOWN_PUBLIC_URL	Public base URL for SSO callback and OpenClaw plugin manifest
EVOTOWN_OIDC_*	OIDC SSO for console login
EVOTOWN_SKILL_SIGNING_SECRET	HMAC signatures for skill packages
LITELLM_BASE_URL / LITELLM_MASTER_KEY	Upstream model gateway (enable litellm Docker profile)

External engine ingest (v0.1 draft)

Independent engines (OpenClaw-style runners, Hermes, custom harnesses, …) can report runs into Evotown over HTTP. Evotown remains the system of record for results and scoring signals.

Implemented MVP endpoints include engine registration and completed-run ingest under /api/v1 (/engines/register, /engines, /runs/{run_id}/complete, /runs, /runs/{run_id}).

Doc	Link
Ingest API (English)	docs/en/EVOTOWN-ENGINE-INGEST-V0.1.md
引擎接入 API（中文）	docs/zh-CN/EVOTOWN-ENGINE-INGEST-V0.1.md
OpenAPI draft	docs/openapi/evotown-engine-ingest-v0.1.yaml

Centralized model gateway (LiteLLM-backed MVP)

Evotown sits in front of LiteLLM as an enterprise API gateway. Agents call Evotown's OpenAI-compatible endpoint; Evotown records ownership, conversations, usage, cost, and risk context before forwarding to LiteLLM.

OPENAI_BASE_URL=http://localhost:8765/api/gateway/v1
OPENAI_API_KEY=evk_xxxxxxxx   # issued from /accounts console or API

MVP endpoints:

• POST /api/gateway/v1/chat/completions — OpenAI-compatible chat completion proxy (non-streaming and SSE streaming).
• GET /api/gateway/v1/model-routes — alias → target model routing (admin).
• GET /api/gateway/v1/usage/summary — gateway requests, cost, token, model, and agent summary.
• GET /api/gateway/v1/conversations — conversation-level gateway rollup.
• GET /api/gateway/v1/api-keys — managed + legacy env key metadata.

Gateway accounts & API keys

Managed keys live in data/accounts.db (override data dir with EVOTOWN_DATA_DIR). Admins create accounts and issue keys via the enterprise console /accounts tab or the REST API below. Secrets are shown once at creation (evk_… prefix); only SHA-256 hashes are stored.

Method	Path	Auth	Purpose
POST	/api/v1/accounts	X-Admin-Token	Create gateway account
GET	/api/v1/accounts	X-Admin-Token	List accounts
PATCH	/api/v1/accounts/{account_id}	X-Admin-Token	Update / disable account
POST	/api/v1/accounts/{account_id}/keys	X-Admin-Token	Issue new API key (returns secret)
GET	/api/v1/accounts/{account_id}/keys	X-Admin-Token	List keys (metadata + monthly usage)
PATCH	/api/v1/keys/{key_id}	X-Admin-Token	Update label, scopes, monthly quotas
POST	/api/v1/keys/{key_id}/revoke	X-Admin-Token	Revoke a key

Gateway chat auth: managed keys must include scope gateway.chat. Exceeding per-key monthly token or cost limits returns HTTP 429. Optional burst RPM limits requests per 60s window. After a successful call that pushes usage over the monthly cap, the response stays 200 but sets X-Evotown-Quota-Exceeded and marks the audit row; the next request is blocked by pre-check.

Backward compatibility: EVOTOWN_GATEWAY_API_KEYS supplies legacy env bearer tokens. Set LITELLM_BASE_URL and LITELLM_MASTER_KEY for production. Docker Compose includes an optional LiteLLM service under the litellm profile.

CI: GitHub Actions runs backend tests and frontend build on push/PR to main (.github/workflows/ci.yml).

Planning & specs

Doc	Link
Spec index	spec/README.md
Enterprise control plane	spec/enterprise-control-plane.md
Knowledge connector	spec/knowledge-connector.md
Skills market	spec/skills-market-and-connectors.md
Roadmap	spec/roadmap.md
Product planning doc (English)	docs/en/ENTERPRISE_CONTROL_PLANE_PRODUCT_SPEC.md
产品规划（中文）	docs/zh-CN/ENTERPRISE_CONTROL_PLANE_PRODUCT_SPEC.md

Arena UI notes

The arena frontend uses WebSocket for live updates. REST fallback polls /agents when the socket is down (~15s) or connected (~60s).

Arena economy and evolution knobs live in backend/evotown_config.json (see backend/evotown_config.json.example).

Economy Rules (Jungle Law)

Configurable via evotown_config.json or environment variables:

Config	Default	Env Var
initial_balance	100	EVOTOWN_INITIAL_BALANCE
cost_accept	-5	EVOTOWN_COST_ACCEPT
reward_complete	10	EVOTOWN_REWARD_COMPLETE
penalty_fail	-5	EVOTOWN_PENALTY_FAIL
eliminate_on_zero	true	EVOTOWN_ELIMINATE_ON_ZERO

Query current config via GET /config/economy.

Directory Structure

evotown/
├── backend/              # FastAPI backend
├── frontend/             # React + Phaser 3 frontend
├── integrations/         # OpenClaw plugin bundle
├── scripts/              # enterprise-deploy.sh, evotown-agent-setup.py, MDM
├── data/                 # Default persistence (override with EVOTOWN_DATA_DIR)
├── .env.example          # LLM + arena env template
├── docker-compose.yml
├── docs/
│   ├── en/               # English docs
│   └── zh-CN/            # 中文文档
├── en/README.md          # English README
├── zh-CN/README.md       # 中文 README
└── README.md             # This file (default)

Related Docs

• Evotown spec index
• Engine ingest API v0.1 | 引擎接入 API v0.1 · OpenAPI
• Enterprise Control Plane Product Spec | 企业控制面产品规格
• Enterprise quickstart | Solution overview (中文)
• Reward Mechanism | 奖励机制
• Agent Task Acceptance | 任务接受逻辑
• Evolution Mechanism | 进化机制