Skip to content

docs: Add 100-star launch playbook, interactive make demo, and Enterprise README header #34

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
rekurt merged 1 commit into from
Oct 26, 2026
Merged

docs: Add 100-star launch playbook, interactive make demo, and Enterprise README header #34

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 5 additions & 1 deletion Makefile
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
.PHONY: add-user remove-user bulk-import fleet-status bootstrap deploy restart logs backup status quota-report quota-reset set-limit security-check monitor monitor-alerts add-service service-health service-skills install-hooks admin-overview benchmark-1k
.PHONY: add-user remove-user bulk-import fleet-status bootstrap deploy restart logs backup status quota-report quota-reset set-limit security-check monitor monitor-alerts add-service service-health service-skills install-hooks admin-overview benchmark-1k demo

# ── Управление инстансами ──────────────────────────────────────────────────

Expand Down Expand Up @@ -31,6 +31,10 @@ fleet-status:
benchmark-1k:
@python3 scripts/benchmark-1000-users.py

# make demo — быстрое 5-секундное интерактивное демо без Docker и внешних ключей
demo:
@bash scripts/quickstart-demo.sh

# ── Деплой ────────────────────────────────────────────────────────────────

deploy: bootstrap
Expand Down
57 changes: 32 additions & 25 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,42 +1,49 @@
# 🐒 CortexForge — toy project, not production-safe
# ⚡ CortexForge — Enterprise Multi-Tenant Control Plane for Hermes Agent

<p align="center">
<img src="assets/banner.jpg" alt="CortexForge — isolated AI personas for every team member" width="1200"/>
<img src="assets/banner.jpg" alt="CortexForge — isolated Hermes Agent personas for every team member" width="1200"/>
</p>

> **Experimental / entertainment project. Do not use in production.**
> CortexForge is a Docker Compose playground for trying isolated AI assistant instances, quota proxies, message routing, and personal personas. It is **not audited**, **not hardened enough for real employee data**, and includes intentionally powerful local-admin capabilities such as Docker socket access and project write mounts. Treat it as a lab, not an enterprise security product.
>
> **Language / Язык:** English | [Русский](README.ru.md)
<p align="center">
<b>One Cortex. Many Minds. Zero API Key Leakage.</b><br/>
Run from 1 to 1,000+ isolated <a href="https://github.com/NousResearch/hermes-agent">Hermes Agent</a> instances with per-user &amp; per-department token quotas (including live SSE streams), inter-agent messaging, and zero-trust credential isolation — on pure Docker Compose.
</p>

[![Version](https://img.shields.io/github/v/tag/example-org/cortex-forge?label=version&color=blue)](https://github.com/example-org/cortex-forge/releases)
[![CI Security](https://github.com/example-org/cortex-forge/actions/workflows/security.yml/badge.svg)](https://github.com/example-org/cortex-forge/actions/workflows/security.yml)
[![License: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE)
<p align="center">
<a href="https://github.com/rekurt/cortex-forge/stargazers"><img src="https://img.shields.io/github/stars/rekurt/cortex-forge?style=social" alt="GitHub Stars"/></a>
<a href="https://github.com/rekurt/cortex-forge/releases"><img src="https://img.shields.io/github/v/tag/rekurt/cortex-forge?label=version&color=blue" alt="Version"/></a>
<a href="https://github.com/rekurt/cortex-forge/actions/workflows/security.yml"><img src="https://github.com/rekurt/cortex-forge/actions/workflows/security.yml/badge.svg" alt="CI Security"/></a>
<a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-green" alt="License: MIT"/></a>
<a href="docs/ENTERPRISE_1000_USERS.md"><img src="https://img.shields.io/badge/scale-1,000%20users%20%40%20355%20RPS-blueviolet" alt="1000-User Benchmark"/></a>
</p>

CortexForge is an experimental AI-assistant infrastructure sandbox built on [Hermes Agent](https://github.com/NousResearch/hermes-agent).
> **Language / Язык:** English | [Русский](README.ru.md) · [Project website](https://rekurt.github.io/cortex-forge/) · [Enterprise 1,000-User Guide](docs/ENTERPRISE_1000_USERS.md)

[Project website](https://rekurt.github.io/cortex-forge/) · [All projects by rekurt](https://rekurt.github.io/projects/)
---

The idea is simple: run several isolated Telegram-bot assistant instances on one host, each with its own workspace, persona, token quota, and message inbox.
## ⚡ Try It in 10 Seconds (Zero Docker / Zero API Keys Needed)

---
Want to see `quota-proxy` (with live SSE streaming token accounting), `message-broker` (with instant broadcast), and multi-tenant quota enforcement in action right now?

## What This Project Is
```bash
git clone https://github.com/rekurt/cortex-forge.git && cd cortex-forge
make demo
```

This repository is useful for:
---

- experimenting with per-user AI assistant containers
- testing quota enforcement in front of model APIs
- trying a simple broker for inter-assistant messages
- exploring persona/workspace-based assistant behavior
- prototyping internal automation skills behind a small HTTP service
## Why CortexForge?

This repository is **not** suitable for:
[Hermes Agent](https://github.com/NousResearch/hermes-agent) gives you a powerful self-improving autonomous agent. **CortexForge** turns it into a multi-tenant team & enterprise platform where **no agent container ever sees your real upstream `ANTHROPIC_API_KEY`**.

@chatgpt-codex-connector chatgpt-codex-connector Bot Oct 26, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Scope the credential-isolation guarantee to generated user agents

In the default Compose deployment, assistant-admin explicitly receives the real ANTHROPIC_API_KEY and OPENAI_API_KEY (docker-compose.yml:135–137), mounts the project directory, and has writable Docker socket access. Consequently, the new guarantee that no agent container ever sees the upstream key is false for a shipped agent configuration. Qualify this claim in both READMEs and the launch copy to cover generated user instances, and retain an explicit warning about the privileged admin trust boundary so operators do not rely on nonexistent credential isolation.

Useful? React with 👍 / 👎.


- production employee assistants
- regulated data, secrets, customer data, or confidential documents
- multi-tenant deployments with real trust boundaries
- environments where Docker socket access, broad bind mounts, or OAuth proxy experiments are unacceptable
| Capability | Raw Single-Agent Setup | CortexForge v2.0 Enterprise |
|---|---|---|
| **Upstream API Key Isolation** | API key stored inside agent `.env` | **Zero exposure:** agents only see opaque `QUOTA_KEY_<NAME>` tokens; `quota-proxy` swaps keys on the fly |
| **SSE Streaming Token Quotas** | Unmetered or post-hoc billing | **Real-time `SSEUsageParser`:** meters Anthropic & OpenAI `text/event-stream` chunks on the fly + hard cutoff (`429`) |

@chatgpt-codex-connector chatgpt-codex-connector Bot Oct 26, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Distinguish stream accounting from mid-stream quota enforcement

For a request admitted with some quota remaining, quota-proxy does not stop an SSE response when its token usage crosses the limit: _proxy() checks quota before contacting upstream, while _stream_sse() forwards the response until EOF or client disconnect and records usage only in finally (quota-proxy/proxy.py:952–976). The new description of real-time streaming quotas with a hard 429 cutoff therefore promises a spending bound that is not implemented; one admitted response can exceed the remaining budget, and only subsequent requests are rejected. Clarify this admission-time behavior in both READMEs and the launch copy rather than implying an in-stream cutoff.

Useful? React with 👍 / 👎.

| **Hierarchical Quotas** | None | **Per-user & per-department caps** with thread-safe concurrent admission guards |
| **Hot Key Registration** | Restart required | **Zero-downtime `POST /quota/register-key` & `POST /admin/register-key`** |
| **Inter-Agent Collaboration** | Isolated silos | **SQLite WAL `message-broker`:** P2P `/send`, priority queues, `peek=1`, and 1,000-agent `/broadcast` in 14 ms |
| **Fleet Scale** | Manual per-bot setup | **`scripts/bulk-users.py`:** provision 1,000 users in 0.5s with Compose shard profiles (`shard-0..shard-9`) |

---

Expand Down
57 changes: 33 additions & 24 deletions README.ru.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,40 +1,49 @@
# 🐒 CortexForge — игрушечный проект, небезопасен для production
# ⚡ CortexForge — Enterprise-платформа управления парком Hermes Agent

<p align="center">
<img src="assets/banner.jpg" alt="CortexForge — изолированные AI-персонажи для каждого сотрудника" width="1200"/>
<img src="assets/banner.jpg" alt="CortexForge — изолированные AI-персонажи на базе Hermes Agent для каждого сотрудника" width="1200"/>
</p>

> **Экспериментальный проект для развлечения. Не использовать в production.**
> CortexForge — это Docker Compose playground для экспериментов с изолированными AI-инстансами, квотами, мессенджером и персонажами. Проект **не проходил аудит**, **не рассчитан на реальные данные сотрудников** и содержит намеренно мощные admin-возможности: доступ к Docker socket, rw-монтирование всего проекта и OAuth-proxy эксперименты. Это лаборатория, а не enterprise security product.
>
> **Language / Язык:** [English](README.md) | Русский

[![Version](https://img.shields.io/github/v/tag/example-org/cortex-forge?label=версия&color=blue)](https://github.com/example-org/cortex-forge/releases)
[![CI Security](https://github.com/example-org/cortex-forge/actions/workflows/security.yml/badge.svg)](https://github.com/example-org/cortex-forge/actions/workflows/security.yml)
[![License: MIT](https://img.shields.io/badge/лицензия-MIT-green)](LICENSE)
<p align="center">
<b>One Cortex. Many Minds. Zero API Key Leakage.</b><br/>
От 1 до 1 000+ изолированных инстансов <a href="https://github.com/NousResearch/hermes-agent">Hermes Agent</a> с персональными и департаментными квотами токенов (включая потоковый учёт SSE-стримов), шиной сообщений между агентами и полной изоляцией мастер-ключей — на чистом Docker Compose.
</p>

CortexForge — экспериментальная песочница AI-ассистентов на базе [Hermes Agent](https://github.com/NousResearch/hermes-agent).
<p align="center">
<a href="https://github.com/rekurt/cortex-forge/stargazers"><img src="https://img.shields.io/github/stars/rekurt/cortex-forge?style=social" alt="GitHub Stars"/></a>
<a href="https://github.com/rekurt/cortex-forge/releases"><img src="https://img.shields.io/github/v/tag/rekurt/cortex-forge?label=версия&color=blue" alt="Version"/></a>
<a href="https://github.com/rekurt/cortex-forge/actions/workflows/security.yml"><img src="https://github.com/rekurt/cortex-forge/actions/workflows/security.yml/badge.svg" alt="CI Security"/></a>
<a href="LICENSE"><img src="https://img.shields.io/badge/лицензия-MIT-green" alt="License: MIT"/></a>
<a href="docs/ENTERPRISE_1000_USERS.md"><img src="https://img.shields.io/badge/масштаб-1%20000%20пользователей%20%40%20355%20RPS-blueviolet" alt="1000-User Benchmark"/></a>
</p>

Идея простая: поднять на одном хосте несколько изолированных Telegram-ботов, у каждого — свой workspace, персонаж, квота токенов и inbox.
> **Language / Язык:** [English](README.md) | Русский · [Сайт проекта](https://rekurt.github.io/cortex-forge/) · [Архитектура на 1 000 пользователей](docs/ENTERPRISE_1000_USERS.md)

---

## Что это за проект
## ⚡ Интерактивное демо за 10 секунд (без Docker и без внешних API-ключей)

Проект полезен для:
Хотите увидеть работу `quota-proxy` (с подсчётом токенов в SSE-стримах на лету), `message-broker` (с мгновенным broadcast) и блокировку при превышении квоты прямо сейчас?

- экспериментов с персональными AI-инстансами в контейнерах
- проверки квотирования перед model API
- простого мессенджера между ассистентами
- прототипирования persona/workspace-based поведения
- локального запуска automation skills через HTTP API
```bash
git clone https://github.com/rekurt/cortex-forge.git && cd cortex-forge
make demo
```

---

Проект **не подходит** для:
## Почему CortexForge?

- production-ассистентов сотрудников
- регулируемых данных, секретов, клиентских данных и конфиденциальных документов
- multi-tenant сценариев с реальными trust boundaries
- окружений, где недопустимы Docker socket, широкие bind mounts или OAuth-proxy эксперименты
[Hermes Agent](https://github.com/NousResearch/hermes-agent) даёт мощного автономного агента. **CortexForge** превращает его в корпоративную multi-tenant платформу, где **ни один пользовательский контейнер никогда не видит ваш настоящий `ANTHROPIC_API_KEY`**.

| Возможность | Обычный запуск Hermes Agent | CortexForge v2.0 Enterprise |
|---|---|---|
| **Изоляция API-ключей** | Ключ лежит в `.env` контейнера | **Нулевая утечка:** контейнеры получают только `QUOTA_KEY_<NAME>`, а `quota-proxy` подменяет ключ на лету |
| **Учёт токенов в SSE-стримах** | Нет или постфактум | **Потоковый `SSEUsageParser`:** считает `text/event-stream` (Anthropic и OpenAI) на лету + отсечка `429` |
| **Иерархические квоты** | Нет | **Лимиты на сотрудника и на департамент** с защитой от конкурентного пробития (`_admission_guard`) |
| **Горячая регистрация ключей** | Требует рестарта | **Без даунтайма:** `POST /quota/register-key` и `POST /admin/register-key` |
| **Общение между ботами** | Изолированные боты | **SQLite WAL `message-broker`:** P2P `/send`, приоритеты, `peek=1` и `/broadcast` на 1 000 агентов за 14 мс |
| **Масштаб до 1 000 инстансов** | Ручная настройка | **`scripts/bulk-users.py`:** импорт 1 000 сотрудников за 0.5 с + шардирование сетей `corp-shard-<N>` |

---

Expand Down
2 changes: 2 additions & 0 deletions broker/broker.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,6 +14,8 @@
composite indexes, throttled batch purge, ThreadingHTTPServer)
"""

from __future__ import annotations

import hashlib
import hmac
import json
Expand Down
Loading
Loading