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.
Badge for your README
Markdown
[](/listings/exboys--evotown)HTML
<a href="/listings/exboys--evotown"><img src="/api/listings/exboys--evotown/badge.svg" alt="findsafeskills safety rating" /></a>Install
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)
- # 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](en/README.md) | [中文](zh-CN/README.md)
- ## Product preview
- 
- *Homepage — enterprise Agent collaboration & governance platform.*
- ---
- ## 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)](docs/zh-CN/ENTERPRISE_QUICKSTART.md)
- ---
- ## 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
- ```text
- 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](https://github.com/BerriAI/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](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)
- ---
- ## Enterprise landing (recommended)
- For teams with **OpenClaw / Hermes on employee laptops**:
- ```bash
- # IT — one-click deploy (see script for env vars)
- ./scripts/enterprise-deploy.sh
- ```
- Employee machine — two lines (from `deploy-output/evotown.agent.env`):
- ```bash
- 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](docs/zh-CN/ENTERPRISE_QUICKSTART.md) |
- | MDM rollout | [docs/zh-CN/MDM_AGENT_ROLLOUT.md](docs/zh-CN/MDM_AGENT_ROLLOUT.md) |
- | API key lifecycle | [docs/zh-CN/ENTERPRISE_KEY_LIFECYCLE.md](docs/zh-CN/ENTERPRISE_KEY_LIFECYCLE.md) |
- | OpenClaw plugin | [integrations/openclaw/evotown/](integrations/openclaw/evotown/) |
- | Private Skills Market | [docs/zh-CN/PRIVATE_SKILLS_MARKET_DEPLOYMENT.md](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](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**.
- ---
- ## 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).
- ```bash
- 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)
- ```bash
- # 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.
- ## 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](docs/en/EVOTOWN-ENGINE-INGEST-V0.1.md) |
- | 引擎接入 API(中文) | [docs/zh-CN/EVOTOWN-ENGINE-INGEST-V0.1.md](docs/zh-CN/EVOTOWN-ENGINE-INGEST-V0.1.md) |
- | OpenAPI draft | [docs/openapi/evotown-engine-ingest-v0.1.yaml](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.
- ```bash
- 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](spec/README.md) |
- | Enterprise control plane | [spec/enterprise-control-plane.md](spec/enterprise-control-plane.md) |
- | Knowledge connector | [spec/knowledge-connector.md](spec/knowledge-connector.md) |
- | Skills market | [spec/skills-market-and-connectors.md](spec/skills-market-and-connectors.md) |
- | Roadmap | [spec/roadmap.md](spec/roadmap.md) |
- | Product planning doc (English) | [docs/en/ENTERPRISE_CONTROL_PLANE_PRODUCT_SPEC.md](docs/en/ENTERPRISE_CONTROL_PLANE_PRODUCT_SPEC.md) |
- | 产品规划(中文) | [docs/zh-CN/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](spec/README.md)
- - [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)
- - [Enterprise Control Plane Product Spec](docs/en/ENTERPRISE_CONTROL_PLANE_PRODUCT_SPEC.md) | [企业控制面产品规格](docs/zh-CN/ENTERPRISE_CONTROL_PLANE_PRODUCT_SPEC.md)
- - [Enterprise quickstart](docs/zh-CN/ENTERPRISE_QUICKSTART.md) | [Solution overview (中文)](docs/zh-CN/SOLUTION.md)
- - [Reward Mechanism](docs/en/REWARD_MECHANISM.md) | [奖励机制](docs/zh-CN/REWARD_MECHANISM.md)
- - [Agent Task Acceptance](docs/en/AGENT_TASK_ACCEPTANCE_ANALYSIS.md) | [任务接受逻辑](docs/zh-CN/AGENT_TASK_ACCEPTANCE_ANALYSIS.md)
- - [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 inFree to use. If it’s helped, pass it on.