Skip to content
Back to search

evotown

a middle platform for enterprise Agent runtime governance and capability assets — connect OpenClaw, Hermes, SkillLite, and custom runtimes in one place; accumulate Skills and enterprise knowledge; provide observability, review, and private distribution

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/exboys--evotown/badge.svg)](/listings/exboys--evotown)

HTML

<a href="/listings/exboys--evotown"><img src="/api/listings/exboys--evotown/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

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, ANTHROPIC_API_KEY (Coding Agent), and optional channel overrides

# 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](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](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.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 332 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # Evotown — Enterprise Agent Governance & Capability Platform
  2. > **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.
  3. **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**.
  4. 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.
  5. The repo also ships an **Evolution Arena** for benchmarks, team learning, and reproducible evolution experiments.
  6. **Language**: [English](en/README.md) | [中文](zh-CN/README.md)
  7. ## Product preview
  8. ![Evotown enterprise landing page](/docs/screenshots/evotown-home.png)
  9. *Homepage — enterprise Agent collaboration & governance platform.*
  10. ---
  11. ## Elevator pitch (30 seconds)
  12. Your company already runs Agents on laptops (OpenClaw, Hermes, …). Evotown gives IT a **self-hosted layer** to:
  13. 1. **Route models** through one gateway (identity, quotas, audit, cost attribution)
  14. 2. **Distribute Skills** from a private SkillHub (review, team scope, signed packages)
  15. 3. **Connect knowledge** (Feishu, Yuque, native KB) without locking a single vendor
  16. 4. **Observe runs** — engines, conversations, risk events — without moving execution into the cloud
  17. **IT deploys once; employees paste two lines of config.** Business apps (DingTalk/Feishu bots, internal copilots) consume the same APIs.
  18. → **Recommended path:** [Enterprise quickstart (IT one-click + employee config)](docs/zh-CN/ENTERPRISE_QUICKSTART.md)
  19. ---
  20. ## What Evotown is — and what it is not
  21. | Evotown **is** | Evotown **is not** |
  22. |----------------|-------------------|
  23. | Agent **governance & capability middle platform** | Universal “enterprise AI chat” for all staff |
  24. | **Runtime-neutral** control plane (OpenClaw / Hermes / SkillLite / custom) | Hosted Agent sandbox that replaces local runtimes |
  25. | Private **model gateway** + **SkillHub** + knowledge connectors | Competing with cloud LLM APIs (OpenAI, Azure, …) |
  26. | Open source, **self-hosted**, evidence-based asset promotion | Low-code iPaaS or generic integration bus |
  27. | Optional **Evolution Arena** for R&D and benchmarks | Required to use Agents in production |
  28. **Product principles:** runtime-neutral · evidence-based asset promotion · private deploy · control without lock-in.
  29. ---
  30. ## Architecture
  31. ```text
  32. Employee laptop / CI / server Your network (Docker / K8s)
  33. OpenClaw · Hermes · SkillLite ┌─────────────────────────────┐
  34. │ two-line env config │ Evotown control plane │
  35. │ OPENAI_BASE_URL → gateway │ · Gateway (→ LiteLLM) │
  36. │ manifest → SkillHub │ · Private Skills Market │
  37. └──────────────────────────────────►│ · Knowledge + Console │
  38. │ · Runs / cost / risk │
  39. └──────────────┬──────────────┘
  40. │
  41. Business apps (bots, copilots, CRM)
  42. ```
  43. | Layer | Role |
  44. |-------|------|
  45. | **Runtime** | OpenClaw / Hermes / SkillLite / custom agents execute **locally** |
  46. | **Evotown (this repo)** | Gateway, accounts, SSO; private Skills Market; knowledge; engine registry; runs, costs, risk |
  47. | **Business apps** | DingTalk/Feishu bots, internal copilots, CRM agents — consume skills & knowledge via API |
  48. ---
  49. ## Core capabilities (enterprise MVP)
  50. | Pillar | What you get |
  51. |--------|----------------|
  52. | **Govern** | Console accounts (`evk_` keys), OIDC SSO, team-scoped assets, skill review & deprecate, API key lifecycle |
  53. | **Route** | OpenAI-compatible gateway in front of [LiteLLM](https://github.com/BerriAI/litellm); alias-based model routing; streaming; quotas & burst limits |
  54. | **Distribute** | Private Skills Market — upload, manifest, employee download; package signing; OpenClaw official-format plugin |
  55. | **Accumulate** | Knowledge connectors (Feishu / Yuque) + native KB with chunk citation search |
  56. | **Observe** | Engine registry, runs timeline, gateway usage, conversations, cost & risk events |
  57. | **Land fast** | `scripts/enterprise-deploy.sh`, `evotown-agent-setup.py` (check / sync / watch), MDM install scripts |
  58. The **Arena** remains the visual simulation layer for evolution experiments and demos — optional for production Agent rollout.
  59. ---
  60. ## How Evotown compares (open source landscape)
  61. Many projects cover **part** of this stack; few combine **runtime-neutral local Agents + private SkillHub + gateway governance** in one self-hosted control plane.
  62. | Category | Examples | Overlap with Evotown |
  63. |----------|----------|----------------------|
  64. | LLM gateway only | LiteLLM, Portkey | Evotown **uses** LiteLLM for provider routing; adds enterprise identity, audit, SkillHub |
  65. | Chat / RAG for end users | Onyx, Dify, LibreChat | End-user chat UI; Evotown focuses on **Agent runtime governance**, not replacing ChatGPT |
  66. | Full-stack Agent platform | Synkora, LiteLLM Agent Platform | Often hosts agents & channels; Evotown **does not** host runtimes — they stay on employee machines |
  67. | Agent control plane | Keviq Core, Kagenti | Closer on governance/orchestration; Evotown is lighter and optimized for **OpenClaw/Hermes enterprise rollout** |
  68. | Skill / tool registry | MCP gateways, tool hubs | Partial overlap with private Skills Market only |
  69. **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.
  70. ---
  71. ## Platform surfaces (MVP)
  72. | Route | Purpose |
  73. |-------|---------|
  74. | `/` | Enterprise landing page |
  75. | `/login` | Console register / login (`evk_` API keys, optional OIDC SSO) |
  76. | `/dashboard` … `/risk` | Enterprise console (engines, runs, gateway, costs, risk, …) |
  77. | `/gateway` | Gateway usage + model route management |
  78. | `/accounts` | Gateway accounts & API keys |
  79. | `/market` | Skills catalog & employee install guidance |
  80. | `/skills` | Admin: upload, review, deprecate skills |
  81. | `/knowledge` | Knowledge sources (Feishu / Yuque / native), tree editor, chunk search |
  82. | `/arena` | Evolution arena (Phaser map, observer panel) |
  83. | `/task-history` | Task history and judge scores |
  84. | `/chronicle` | Organizational learning log |
  85. Specs: [spec/README.md](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)
  86. ---
  87. ## Enterprise landing (recommended)
  88. For teams with **OpenClaw / Hermes on employee laptops**:
  89. ```bash
  90. # IT — one-click deploy (see script for env vars)
  91. ./scripts/enterprise-deploy.sh
  92. ```
  93. Employee machine — two lines (from `deploy-output/evotown.agent.env`):
  94. ```bash
  95. OPENAI_BASE_URL=https://evotown.company.internal/api/gateway/v1
  96. OPENAI_API_KEY=evk_xxxxxxxx
  97. ```
  98. | Doc | Link |
  99. |-----|------|
  100. | Enterprise quickstart (中文) | [docs/zh-CN/ENTERPRISE_QUICKSTART.md](docs/zh-CN/ENTERPRISE_QUICKSTART.md) |
  101. | MDM rollout | [docs/zh-CN/MDM_AGENT_ROLLOUT.md](docs/zh-CN/MDM_AGENT_ROLLOUT.md) |
  102. | API key lifecycle | [docs/zh-CN/ENTERPRISE_KEY_LIFECYCLE.md](docs/zh-CN/ENTERPRISE_KEY_LIFECYCLE.md) |
  103. | OpenClaw plugin | [integrations/openclaw/evotown/](integrations/openclaw/evotown/) |
  104. | Private Skills Market | [docs/zh-CN/PRIVATE_SKILLS_MARKET_DEPLOYMENT.md](docs/zh-CN/PRIVATE_SKILLS_MARKET_DEPLOYMENT.md) |
  105. ---
  106. ## Evolution testing (original focus)
  107. Puts **evolution engines** in a controlled environment for **evolution effect validation** — OpenClaw-style stacks, Hermes, your own harness, or **optionally** [SkillLite](https://github.com/EXboys/skilllite). Evotown does not require a specific upstream; use the [ingest API](docs/en/EVOTOWN-ENGINE-INGEST-V0.1.md) to attach runners. Economy rules are configurable, reproducible, fully local, and **do not depend on virtual/cryptocurrency**.
  108. ---
  109. ## Prerequisites
  110. - Python 3.10+
  111. - Node.js 18+
  112. - **Skills workspace:** backend expects a project tree with `.skills` or `skills` (layout depends on the agent backend you wire in).
  113. - **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.
  114. ## Quick Start
  115. ### Option A — Docker (Recommended)
  116. Requires Docker Desktop (or Docker Engine + Compose plugin).
  117. ```bash
  118. cd evotown
  119. # 1. Create .env from the template (same directory as docker-compose.yml)
  120. cp .env.example .env
  121. # Edit API_KEY / BASE_URL / MODEL, ANTHROPIC_API_KEY (Coding Agent), and optional channel overrides
  122. # 2. First-time: build images and start
  123. docker compose up -d --build
  124. # Subsequent starts (no rebuild needed)
  125. docker compose up -d
  126. # Stop
  127. docker compose down
  128. ```
  129. Visit [http://localhost](http://localhost) — landing page; open **Console**, **Skills Market**, or **Arena** from the nav.
  130. > **Note**: `.env` must be placed in the `evotown/` directory (same level as `docker-compose.yml`).
  131. > Docker Compose reads it automatically on startup.
  132. ### Option B — Local Dev (two terminals)
  133. ```bash
  134. # Terminal 1 — Backend
  135. cd evotown/backend
  136. pip install -r requirements.txt
  137. uvicorn main:app --host 0.0.0.0 --port 8765
  138. # Terminal 2 — Frontend
  139. cd evotown/frontend
  140. npm install
  141. npm run dev
  142. ```
  143. Visit [http://localhost:5174](http://localhost:5174)
  144. > **Data directory**: Local dev and Docker both persist arena state, task history, and logs under `evotown/data/`. Override with `EVOTOWN_DATA_DIR` when needed.
  145. ## Configuration
  146. 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.
  147. 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`).
  148. Optional enterprise env vars:
  149. | Variable | Purpose |
  150. |----------|---------|
  151. | `EVOTOWN_PUBLIC_URL` | Public base URL for SSO callback and OpenClaw plugin manifest |
  152. | `EVOTOWN_OIDC_*` | OIDC SSO for console login |
  153. | `EVOTOWN_SKILL_SIGNING_SECRET` | HMAC signatures for skill packages |
  154. | `LITELLM_BASE_URL` / `LITELLM_MASTER_KEY` | Upstream model gateway (enable `litellm` Docker profile) |
  155. ## External engine ingest (v0.1 draft)
  156. 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.
  157. Implemented MVP endpoints include engine registration and completed-run ingest under `/api/v1` (`/engines/register`, `/engines`, `/runs/{run_id}/complete`, `/runs`, `/runs/{run_id}`).
  158. | Doc | Link |
  159. |-----|------|
  160. | Ingest API (English) | [docs/en/EVOTOWN-ENGINE-INGEST-V0.1.md](docs/en/EVOTOWN-ENGINE-INGEST-V0.1.md) |
  161. | 引擎接入 API(中文) | [docs/zh-CN/EVOTOWN-ENGINE-INGEST-V0.1.md](docs/zh-CN/EVOTOWN-ENGINE-INGEST-V0.1.md) |
  162. | OpenAPI draft | [docs/openapi/evotown-engine-ingest-v0.1.yaml](docs/openapi/evotown-engine-ingest-v0.1.yaml) |
  163. ## Centralized model gateway (LiteLLM-backed MVP)
  164. 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.
  165. ```bash
  166. OPENAI_BASE_URL=http://localhost:8765/api/gateway/v1
  167. OPENAI_API_KEY=evk_xxxxxxxx # issued from /accounts console or API
  168. ```
  169. MVP endpoints:
  170. - `POST /api/gateway/v1/chat/completions` — OpenAI-compatible chat completion proxy (**non-streaming and SSE streaming**).
  171. - `GET /api/gateway/v1/model-routes` — alias → target model routing (admin).
  172. - `GET /api/gateway/v1/usage/summary` — gateway requests, cost, token, model, and agent summary.
  173. - `GET /api/gateway/v1/conversations` — conversation-level gateway rollup.
  174. - `GET /api/gateway/v1/api-keys` — managed + legacy env key metadata.
  175. ### Gateway accounts & API keys
  176. 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.
  177. | Method | Path | Auth | Purpose |
  178. |--------|------|------|---------|
  179. | POST | `/api/v1/accounts` | X-Admin-Token | Create gateway account |
  180. | GET | `/api/v1/accounts` | X-Admin-Token | List accounts |
  181. | PATCH | `/api/v1/accounts/{account_id}` | X-Admin-Token | Update / disable account |
  182. | POST | `/api/v1/accounts/{account_id}/keys` | X-Admin-Token | Issue new API key (returns `secret`) |
  183. | GET | `/api/v1/accounts/{account_id}/keys` | X-Admin-Token | List keys (metadata + monthly usage) |
  184. | PATCH | `/api/v1/keys/{key_id}` | X-Admin-Token | Update label, scopes, monthly quotas |
  185. | POST | `/api/v1/keys/{key_id}/revoke` | X-Admin-Token | Revoke a key |
  186. **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.
  187. **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.
  188. **CI:** GitHub Actions runs backend tests and frontend build on push/PR to `main` (`.github/workflows/ci.yml`).
  189. ## Planning & specs
  190. | Doc | Link |
  191. |-----|------|
  192. | Spec index | [spec/README.md](spec/README.md) |
  193. | Enterprise control plane | [spec/enterprise-control-plane.md](spec/enterprise-control-plane.md) |
  194. | Knowledge connector | [spec/knowledge-connector.md](spec/knowledge-connector.md) |
  195. | Skills market | [spec/skills-market-and-connectors.md](spec/skills-market-and-connectors.md) |
  196. | Roadmap | [spec/roadmap.md](spec/roadmap.md) |
  197. | Product planning doc (English) | [docs/en/ENTERPRISE_CONTROL_PLANE_PRODUCT_SPEC.md](docs/en/ENTERPRISE_CONTROL_PLANE_PRODUCT_SPEC.md) |
  198. | 产品规划(中文) | [docs/zh-CN/ENTERPRISE_CONTROL_PLANE_PRODUCT_SPEC.md](docs/zh-CN/ENTERPRISE_CONTROL_PLANE_PRODUCT_SPEC.md) |
  199. ## Arena UI notes
  200. The arena frontend uses WebSocket for live updates. REST fallback polls `/agents` when the socket is down (~15s) or connected (~60s).
  201. Arena economy and evolution knobs live in `backend/evotown_config.json` (see `backend/evotown_config.json.example`).
  202. ## Economy Rules (Jungle Law)
  203. Configurable via `evotown_config.json` or environment variables:
  204. | Config | Default | Env Var |
  205. |--------|---------|---------|
  206. | initial_balance | 100 | EVOTOWN_INITIAL_BALANCE |
  207. | cost_accept | -5 | EVOTOWN_COST_ACCEPT |
  208. | reward_complete | 10 | EVOTOWN_REWARD_COMPLETE |
  209. | penalty_fail | -5 | EVOTOWN_PENALTY_FAIL |
  210. | eliminate_on_zero | true | EVOTOWN_ELIMINATE_ON_ZERO |
  211. Query current config via `GET /config/economy`.
  212. ## Directory Structure
  213. ```
  214. evotown/
  215. ├── backend/ # FastAPI backend
  216. ├── frontend/ # React + Phaser 3 frontend
  217. ├── integrations/ # OpenClaw plugin bundle
  218. ├── scripts/ # enterprise-deploy.sh, evotown-agent-setup.py, MDM
  219. ├── data/ # Default persistence (override with EVOTOWN_DATA_DIR)
  220. ├── .env.example # LLM + arena env template
  221. ├── docker-compose.yml
  222. ├── docs/
  223. │ ├── en/ # English docs
  224. │ └── zh-CN/ # 中文文档
  225. ├── en/README.md # English README
  226. ├── zh-CN/README.md # 中文 README
  227. └── README.md # This file (default)
  228. ```
  229. ## Related Docs
  230. - [Evotown spec index](spec/README.md)
  231. - [Engine ingest API v0.1](docs/en/EVOTOWN-ENGINE-INGEST-V0.1.md) | [引擎接入 API v0.1](docs/zh-CN/EVOTOWN-ENGINE-INGEST-V0.1.md) · [OpenAPI](docs/openapi/evotown-engine-ingest-v0.1.yaml)
  232. - [Enterprise Control Plane Product Spec](docs/en/ENTERPRISE_CONTROL_PLANE_PRODUCT_SPEC.md) | [企业控制面产品规格](docs/zh-CN/ENTERPRISE_CONTROL_PLANE_PRODUCT_SPEC.md)
  233. - [Enterprise quickstart](docs/zh-CN/ENTERPRISE_QUICKSTART.md) | [Solution overview (中文)](docs/zh-CN/SOLUTION.md)
  234. - [Reward Mechanism](docs/en/REWARD_MECHANISM.md) | [奖励机制](docs/zh-CN/REWARD_MECHANISM.md)
  235. - [Agent Task Acceptance](docs/en/AGENT_TASK_ACCEPTANCE_ANALYSIS.md) | [任务接受逻辑](docs/zh-CN/AGENT_TASK_ACCEPTANCE_ANALYSIS.md)
  236. - [Evolution Mechanism](docs/en/EVOLUTION_MECHANISM_ANALYSIS.md) | [进化机制](docs/zh-CN/EVOLUTION_MECHANISM_ANALYSIS.md)

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.