@openclaw-cloud/agent-controller 0.1.5 → 0.1.7

package/BIZPLAN.md

@@ -0,0 +1,530 @@
+# OpenClaw Cloud — Бизнес-план
+
+> Персональный AI-агент для каждого. Managed platform + standalone.
+> Версия: 2.0 | Дата: 2026-02-22
+
+---
+
+## 1. Executive Summary
+
+**OpenClaw Cloud** — платформа, позволяющая любому пользователю запустить персонального AI-агента на базе Claude (Anthropic). Агент разворачивается в изолированном окружении, подключается к Telegram/Discord/Slack/WhatsApp и работает 24/7 с персональной памятью, инструментами и интеграциями.
+
+**Три модели деплоя:**
+1. **Managed K8s** — pod в нашем кластере, zero-ops для юзера
+2. **Managed VM** — выделенный EC2 инстанс, больше ресурсов
+3. **Standalone (BYOH)** — пользователь ставит openclaw на свой сервер/Mac/ПК, подключается к нашей платформе для биллинга, marketplace, updates
+
+**Ключевое отличие от ChatGPT/Claude.ai:** это не чат-окно, а **агент** — с памятью между сессиями, доступом к интернету, файлам, API, умному дому, календарю. Личный цифровой помощник, а не одноразовый чат.
+
+| Метрика | Цель (12 мес.) |
+|---------|---------------|
+| Платящие пользователи | 5 000 |
+| MRR | $150 000 |
+| Средний чек | $30/мес |
+| Gross margin | 55-65% |
+| Breakeven | месяц 8-10 |
+
+**Модель монетизации:** подписка (SaaS) + usage-based overage + standalone license fee.
+
+---
+
+## 2. Проблема и решение
+
+### Проблема
+
+| Боль | Кто страдает |
+|------|-------------|
+| Claude/ChatGPT — одноразовый чат без памяти и автономности | Все пользователи AI |
+| Настроить своего бота с памятью, инструментами, интеграциями — нужны DevOps навыки | Не-технические пользователи, малый бизнес |
+| Существующие решения (Lindy, CustomGPT) — ограничены: нет code execution, браузера, файловой системы | Power users, разработчики |
+| Хочу AI-агента на СВОЁМ железе (приватность, контроль), но с удобством managed платформы | Параноики по безопасности, enterprise, devs |
+| API Anthropic дорого если использовать напрямую без оптимизаций | Разработчики ботов |
+
+### Решение
+
+OpenClaw Cloud даёт каждому пользователю:
+
+1. **Изолированное окружение** с персональным Claude-агентом (K8s pod, VM, или свой сервер)
+2. **Persistent memory** — агент помнит всё между сессиями (файлы, заметки, контекст)
+3. **Инструменты из коробки:** браузер, shell, файловая система, TTS, поиск, камера
+4. **Мессенджер-интеграции:** Telegram, Discord, Slack, WhatsApp — агент живёт там, где пользователь
+5. **Marketplace ролей и личностей** — установка навыков в один клик с onboarding wizard
+6. **Три модели деплоя** — от zero-ops managed до полного контроля на своём железе
+7. **Оптимизированная стоимость** — model routing, prompt caching, shared infrastructure
+
+---
+
+## 3. Архитектура
+
+### 3.1 Общая схема
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                    OpenClaw Cloud Platform                    │
+│                                                               │
+│  ┌──────────────┐  ┌──────────────┐  ┌────────────────────┐ │
+│  │  Auth + JWT   │  │  Billing     │  │  Anthropic Proxy   │ │
+│  │  Service      │  │  Stripe +    │  │  (streaming, token │ │
+│  │              │  │  Tinkoff     │  │   counting, model  │ │
+│  └──────────────┘  └──────────────┘  │   routing)         │ │
+│                                       └────────────────────┘ │
+│  ┌──────────────┐  ┌──────────────┐  ┌────────────────────┐ │
+│  │  Marketplace  │  │  Board       │  │  Messages Broker   │ │
+│  │  Roles +      │  │  (Kanban)    │  │  (RabbitMQ)        │ │
+│  │  Identities   │  │              │  │                    │ │
+│  └──────────────┘  └──────────────┘  └────────────────────┘ │
+│                                                               │
+│  ┌────────────────── Centrifugo (JWT auth) ─────────────────┐│
+│  │  Real-time WebSocket: heartbeat, board, presence          ││
+│  └───────────────────────────────────────────────────────────┘│
+│                          │                                    │
+│        ┌─────────────────┼─────────────────────┐             │
+│        ▼                 ▼                     ▼             │
+│  ┌───────────┐  ┌──────────────┐  ┌────────────────────┐    │
+│  │ K8s Pods  │  │ EC2 VMs      │  │ Standalone Agents  │    │
+│  │ (managed) │  │ (managed)    │  │ (BYOH)             │    │
+│  │           │  │              │  │                    │    │
+│  │ openclaw  │  │ openclaw     │  │ openclaw (user's   │    │
+│  │ + agent-  │  │ + agent-     │  │ hardware) +        │    │
+│  │ controller│  │ controller   │  │ agent-controller   │    │
+│  └───────────┘  └──────────────┘  └────────────────────┘    │
+│                                                               │
+│  ┌──────────────────────────────────────────────────────────┐│
+│  │  Frontend: React 19 + Vite                                ││
+│  │  Dashboard, Marketplace, Billing, Admin, Board            ││
+│  └──────────────────────────────────────────────────────────┘│
+└─────────────────────────────────────────────────────────────┘
+```
+
+### 3.2 Три модели деплоя
+
+| | **K8s Managed** | **VM Managed** | **Standalone (BYOH)** |
+|---|---|---|---|
+| **Где работает** | EKS pod (наш кластер) | EC2 инстанс (наш аккаунт) | Сервер/Mac/ПК пользователя |
+| **Provisioning** | Helm chart, автоматический | user-data script, SSM | `npm install -g openclaw` + agent-controller |
+| **Ресурсы** | Shared nodes, 256-512MB RAM | Dedicated, t4g.small+ | Зависит от железа юзера |
+| **Storage** | PersistentVolume (EBS gp3) | EBS volume | Локальный диск |
+| **Networking** | ClusterIP + webhook proxy | Public IP + direct webhook | Outbound WS к платформе |
+| **Стоимость инфры** | ~$3.50/мес (наша) | ~$8-15/мес (наша) | $0 (юзера) |
+| **Scaling** | Автоматический (Karpenter) | Manual (resize) | N/A |
+| **Идеально для** | Starter/Pro планы | Power users, heavy workloads | Privacy-first, enterprise, devs |
+| **Cold storage** | Pod → replicas=0 | VM stop | Always on (юзер контролирует) |
+
+### 3.3 Standalone (BYOH) — как это работает
+
+```
+Пользователь:
+1. Регистрируется на openclaw-cloud.io
+2. Получает agent token + license key
+3. Устанавливает: npm install -g openclaw @openclaw-cloud/agent-controller
+4. Запускает: agent-controller connect --token <TOKEN>
+
+Agent-controller:
+- Подключается к Centrifugo WS (нашей платформы)
+- Получает команды: file-write, package-install, reconfigure
+- Отправляет heartbeats
+- Проксирует Anthropic API через нашу платформу (биллинг + routing)
+- Получает роли/обновления из marketplace
+
+Для пользователя:
+- Полный контроль над данными (workspace на его диске)
+- Может использовать свой Anthropic API key (bypass нашего proxy)
+- Автообновления через agent-controller self-update
+```
+
+**Монетизация standalone:**
+- Platform fee: $5/мес (доступ к marketplace, board, updates, monitoring)
+- API proxy: usage-based (если через наш proxy)
+- BYOK (Bring Your Own Key): $5/мес flat (только platform features)
+
+### 3.4 Компоненты
+
+| Компонент | Технология | Назначение |
+|-----------|-----------|------------|
+| **Backend API** | Node.js + Express + TypeScript | Ядро платформы — auth, billing, agent management |
+| **Agent Runtime** | OpenClaw (Node.js) | Gateway бота — skills, memory, tools |
+| **Agent-Controller** | Node.js (npm package) | Связь agent↔platform через Centrifugo WS |
+| **Orchestration** | EKS (Kubernetes) + Karpenter | K8s managed agents |
+| **VM Provisioner** | AWS EC2 + SSM | VM managed agents |
+| **Real-time** | Centrifugo v6 (JWT auth) | WebSocket: heartbeats, board events, presence |
+| **Message Queue** | RabbitMQ | Webhook delivery с retry (6 attempts, exponential backoff) |
+| **Database** | PostgreSQL (RDS) | Основное хранилище |
+| **Object Storage** | S3 + CloudFront | Uploads, avatars, static |
+| **Auth** | JWT (custom) | Регистрация, сессии |
+| **Billing** | Stripe + Tinkoff | Подписки, usage metering |
+| **Frontend** | React 19 + Vite + Tailwind | Dashboard, marketplace, billing |
+| **CI/CD** | GitLab CI | Tests, build, deploy |
+| **Monitoring** | Prometheus + Grafana + Loki | Метрики, логи, алерты |
+| **DNS/CDN** | Route53 + CloudFront | `openclaw-cloud.io` |
+
+### 3.5 Scaling стратегия
+
+| Фаза | Пользователей | Инфраструктура |
+|------|--------------|----------------|
+| MVP | 0-100 | 2 ARM64 nodes, 1 RDS, shared namespace |
+| Early | 100-500 | 3-5 nodes, Karpenter autoscaling |
+| Growth | 500-2000 | 10-15 nodes, pod scale-to-zero для idle |
+| Scale | 2000-5000 | Multi-AZ, read replicas, отдельный proxy сервис |
+| Mature | 5000+ | Multi-region, dedicated clusters per tier |
+
+---
+
+## 4. Оптимизация расходов
+
+### 4.1 Prompt Caching (Anthropic)
+
+Каждый агент имеет большой system prompt (SOUL.md + AGENTS.md + TOOLS.md + контекст) — **5-15K токенов**.
+
+| Параметр | Без кэша | С кэшем |
+|----------|----------|---------|
+| System prompt | 10K tokens × $3/1M = $0.03 за каждый запрос | Первый раз: $0.0375 (write), далее: $0.003 (read) |
+| 100 сообщений/день | $3/день | $0.34/день |
+| **Экономия** | — | **~89%** на input tokens системного промпта |
+
+**Статус:** Не реализовано. Quick win — добавить `cache_control` к system prompt blocks в `anthropic-proxy.ts`.
+
+### 4.2 Model Routing (реализовано)
+
+Встроенный в backend `model-router.ts` — эвристический классификатор:
+
+| Правило | Модель | Триггер |
+|---------|--------|---------|
+| Extended thinking / "подумай" | Opus | Ключевые слова |
+| Длинный контекст (>20 сообщений) | Opus | Автоматически |
+| Код, файлы | Sonnet | Детекция паттернов |
+| Короткий запрос (<50 токенов), без кода | Haiku | Автоматически |
+| Default | Sonnet | Fallback |
+
+Tier enforcement: Starter → Haiku+Sonnet, Pro → все, Team → все + приоритет.
+
+### 4.3 Spot/ARM64 Instances
+
+| Ресурс | Тип | Стоимость |
+|--------|-----|-----------|
+| K8s nodes | t4g (ARM64, spot) | ~60% дешевле x86 on-demand |
+| Agent VMs | t4g.small (ARM64) | $0.013/hr (~$9.50/мес) |
+| Karpenter | Автовыбор cheapest instance | Оптимизирует автоматически |
+
+### 4.4 Pod Scale-to-Zero (roadmap)
+
+Если агент не получал сообщений >24ч:
+1. StatefulSet replicas → 0 (PV сохраняется)
+2. При новом сообщении → replicas=1, pod стартует за 15-30 сек
+3. Экономия compute при сохранении данных
+
+| Состояние | Стоимость на агента/мес |
+|-----------|------------------------|
+| Active (24/7) | ~$3.50 (compute) + $1.70 (10GB EBS) = **$5.20** |
+| Idle (PV only) | $1.70 (EBS) = **$1.70** |
+
+### 4.5 Standalone — нулевая стоимость инфры
+
+Standalone агенты работают на железе пользователя. Для нас:
+- $0 compute, $0 storage
+- Только Centrifugo WS connection + API proxy traffic
+- Gross margin ~90% на standalone plans
+
+### 4.6 Будущие оптимизации (roadmap)
+
+| Оптимизация | Экономия | Сложность | Когда |
+|-------------|----------|-----------|-------|
+| Prompt caching | 25-30% API costs | Низкая | Следующий спринт |
+| Pod scale-to-zero | 30-50% compute | Средняя | 500+ юзеров |
+| Anthropic Batches API | 50% на cron-задачи | Низкая | 1000+ юзеров |
+| Shared browser pool | 95% browser costs | Средняя | 1000+ юзеров |
+| ClickHouse для analytics | Снижение нагрузки PG | Средняя | 5000+ юзеров |
+| Локальные модели (STT, classify) | 5-10% API | Высокая | 5000+ юзеров |
+
+---
+
+## 5. Тарифные планы
+
+### Managed планы (K8s / VM)
+
+| | **Starter** | **Pro** | **Team** |
+|---|---|---|---|
+| **Цена** | **$9/мес** | **$29/мес** | **$79/мес** (до 5 юзеров) |
+| Deployment | K8s pod | K8s pod или VM | VM (dedicated) |
+| Токены/мес | 2M input + 500K output | 10M input + 3M output | 50M input + 15M output |
+| Модели | Haiku + Sonnet | Haiku + Sonnet + Opus | Все + приоритет |
+| Мессенджеры | 1 канал | 3 канала | Unlimited |
+| Memory (workspace) | 1 GB | 10 GB | 50 GB |
+| Браузер | ❌ | ✅ (50 сессий/день) | ✅ (unlimited) |
+| Code execution | ❌ | ✅ | ✅ |
+| Marketplace roles | 3 | Unlimited | Unlimited |
+| Board (Kanban) | ❌ | ✅ | ✅ |
+| Cron/Heartbeat | 2 задачи | 10 задач | Unlimited |
+| TTS | ❌ | 100/мес | Unlimited |
+| Поддержка | Community | Email | Priority |
+
+### Standalone планы (BYOH)
+
+| | **Standalone Basic** | **Standalone Pro** |
+|---|---|---|
+| **Цена** | **$5/мес** | **$19/мес** |
+| API proxy | Через нашу платформу (usage-based) | BYOK (свой API key) |
+| Marketplace | ✅ | ✅ |
+| Board | ❌ | ✅ |
+| Auto-updates | ✅ | ✅ |
+| Monitoring dashboard | Basic | Full |
+| Роли из marketplace | 5 | Unlimited |
+| Поддержка | Community | Email |
+
+### Overage (managed планы)
+
+| Ресурс | Цена сверх лимита |
+|--------|-------------------|
+| Input tokens | $5 / 1M tokens |
+| Output tokens | $20 / 1M tokens |
+| Storage | $0.50 / GB / мес |
+| Browser сессии | $0.05 / сессия |
+| TTS | $0.02 / сообщение |
+
+### Годовая подписка: скидка 20%
+
+---
+
+## 6. Unit-экономика
+
+### 6.1 Себестоимость по типам (Pro план, $29/мес)
+
+**K8s Managed:**
+
+| Статья | $/мес | % |
+|--------|-------|---|
+| Anthropic API (с routing, ~60% usage) | $8.50 | 56% |
+| Compute (pod, ARM64 spot) | $2.80 | 18% |
+| Storage (10GB EBS gp3) | $1.70 | 11% |
+| RabbitMQ/Centrifugo (доля) | $0.30 | 2% |
+| Bandwidth | $0.20 | 1% |
+| Stripe (2.9%) | $0.84 | 6% |
+| Support (доля) | $0.50 | 3% |
+| **Итого COGS** | **$14.84** | |
+| **Gross Profit** | **$14.16** | **49%** |
+
+**VM Managed (Team $79/мес):**
+
+| Статья | $/мес | % |
+|--------|-------|---|
+| Anthropic API | $25.00 | 56% |
+| EC2 t4g.small (dedicated) | $9.50 | 21% |
+| EBS 50GB | $4.00 | 9% |
+| Прочее | $2.00 | 4% |
+| Stripe (2.9%) | $2.29 | 5% |
+| **Итого COGS** | **$42.79** | |
+| **Gross Profit** | **$36.21** | **46%** |
+
+**Standalone Pro ($19/мес):**
+
+| Статья | $/мес | % |
+|--------|-------|---|
+| Centrifugo WS (доля) | $0.05 | 2% |
+| Platform infra (доля) | $0.50 | 15% |
+| Stripe (2.9%) | $0.55 | 17% |
+| Support (доля) | $0.50 | 15% |
+| **Итого COGS** | **$1.60** | |
+| **Gross Profit** | **$17.40** | **92%** |
+
+### 6.2 Средневзвешенная маржинальность
+
+Предполагаемый mix при 5000 юзеров:
+
+| Тип | % юзеров | Avg Revenue | Avg COGS | Avg GP |
+|-----|----------|-------------|----------|--------|
+| Starter ($9) | 30% | $9 | $3.20 | $5.80 |
+| Pro K8s ($29) | 30% | $29 | $14.84 | $14.16 |
+| Team VM ($79) | 10% | $79 | $42.79 | $36.21 |
+| Standalone Basic ($5) | 15% | $5 | $0.80 | $4.20 |
+| Standalone Pro ($19) | 15% | $19 | $1.60 | $17.40 |
+| **Средневзвешенный** | — | **$22.75** | **$9.85** | **$12.90 (57%)** |
+
+### 6.3 Операционные расходы (фиксированные)
+
+| Статья | $/мес |
+|--------|-------|
+| Команда (2-3 инженера) | $15 000 |
+| Базовая инфраструктура (EKS, RDS, Centrifugo, RabbitMQ, monitoring) | $2 500 |
+| SaaS (GitLab, Sentry, domains, etc.) | $500 |
+| Маркетинг | $2 000 |
+| Юридические/бухгалтерия | $1 000 |
+| **Итого OpEx** | **$21 000/мес** |
+
+### 6.4 Breakeven
+
+| Метрика | Значение |
+|---------|---------|
+| Средний Gross Profit на юзера | $12.90/мес |
+| Фиксированные OpEx | $21 000/мес |
+| **Breakeven** | **~1 630 платящих юзеров** |
+| При росте 25%/мес от 50 юзеров | **~месяц 9** |
+
+### 6.5 Прогноз на 12 месяцев
+
+| Месяц | Юзеры | MRR | COGS | Gross Profit | OpEx | Net |
+|-------|-------|-----|------|-------------|------|-----|
+| 1 | 50 | $1 138 | $493 | $645 | $21 000 | -$20 355 |
+| 3 | 150 | $3 413 | $1 478 | $1 935 | $21 000 | -$19 065 |
+| 6 | 600 | $13 650 | $5 910 | $7 740 | $23 000 | -$15 260 |
+| 9 | 1 800 | $40 950 | $17 730 | $23 220 | $25 000 | -$1 780 |
+| 10 | 2 200 | $50 050 | $21 670 | $28 380 | $26 000 | **+$2 380** |
+| 12 | 3 500 | $79 625 | $34 475 | $45 150 | $28 000 | **+$17 150** |
+
+**Необходимые инвестиции (runway до breakeven):** ~$150 000
+
+---
+
+## 7. Marketplace — Roles & Identities
+
+### Ключевая дифференциация
+
+OpenClaw Cloud не просто хостит ботов — это **платформа с экосистемой**.
+
+### Roles (что агент ДЕЛАЕТ)
+
+Роль = installable package с:
+- **Файлы** (AGENTS.md, TOOLS.md, HEARTBEAT.md + кастомные)
+- **Manifest** — зависимости (apt/npm/pip), onboarding questions, file policies
+- **Onboarding Wizard** — при установке спрашивает API ключи, настройки
+- **Template Engine** — `{{GITHUB_TOKEN}}` заменяется на реальные значения
+- **File Policies** — managed (автообновление), template (ре-генерация), user-owned (не трогать)
+- **Portable Memory** — переносимая память роли между агентами
+
+24 готовых роли при запуске: devops-engineer, full-stack-developer, crypto-trader, email-manager, и др.
+
+### Identities (кто агент ЕСТЬ)
+
+Личность = SOUL.md + IDENTITY.md. Определяет характер, стиль общения, голос.
+
+### Монетизация marketplace (roadmap)
+
+- Бесплатные роли (community) — привлечение
+- Premium роли (авторские) — 70/30 split
+- Enterprise роли (custom) — per-seat licensing
+
+---
+
+## 8. Конкуренты
+
+| Критерий | **OpenClaw Cloud** | **Lindy.ai** | **Poe** | **ChatGPT Teams** | **Self-hosted (raw)** |
+|----------|-------------------|-------------|---------|-----------------|---------------------|
+| Персональный агент 24/7 | ✅ | ✅ | ❌ | ❌ | ✅ (manual setup) |
+| Persistent memory | ✅ (файловая) | Ограниченно | ❌ | Ограниченно | ✅ (manual) |
+| Code execution | ✅ (full shell) | ❌ | ❌ | Sandbox | ✅ (manual) |
+| Мессенджеры | Telegram, Discord, Slack, WhatsApp | Slack, Email | ❌ | Slack | Manual |
+| Marketplace ролей | ✅ (24+ ролей, onboarding) | Шаблоны | ❌ | ❌ | ❌ |
+| Standalone (BYOH) | ✅ | ❌ | ❌ | ❌ | ✅ (это и есть) |
+| Managed + Self-hosted | ✅ (оба) | Только managed | Только cloud | Только cloud | Только self |
+| Board (Kanban) | ✅ | ❌ | ❌ | ❌ | ❌ |
+| Auto model routing | ✅ | ❌ | Multi-model | ❌ | ❌ |
+| Цена (Pro) | $29/мес | $49/мес | $20/мес | $25/user | $0 + API costs |
+
+### Конкурентные преимущества
+
+1. **Три модели деплоя** — единственная платформа с managed + standalone + VM
+2. **Marketplace ролей** — installable packages с onboarding, не просто промпты
+3. **Мессенджер-first** — агент живёт в Telegram/Discord
+4. **Open-source core** (openclaw) — доверие, extensibility
+5. **Claude-first** — лучшая интеграция с экосистемой Anthropic
+6. **Standalone монетизация** — даже self-hosted юзеры платят за платформу
+
+### Уникальная позиция: Standalone
+
+Standalone закрывает сегмент который **никто не покрывает**: юзеры, которые хотят AI-агента на своём железе, но не хотят разбираться в настройке, обновлениях, marketplace. Мы даём "managed experience" для self-hosted.
+
+---
+
+## 9. Текущий статус и Roadmap
+
+### ✅ Реализовано (февраль 2026)
+
+- [x] EKS кластер (eu-central-1, ARM64, Karpenter)
+- [x] K8s agent provisioning (helm chart, StatefulSet)
+- [x] VM agent provisioning (EC2, Ubuntu ARM64, SSM)
+- [x] Agent-controller (npm package, Centrifugo WS, self-update)
+- [x] Centrifugo real-time (JWT auth, heartbeat, board, presence)
+- [x] Messages Broker (RabbitMQ, webhook proxy с retry)
+- [x] Anthropic Proxy (streaming, token counting, usage tracking)
+- [x] Model Router (Haiku/Sonnet/Opus, tier enforcement)
+- [x] Usage Limiter (weighted units, budgets, notifications)
+- [x] Billing (Stripe + Tinkoff, starter/pro/team plans)
+- [x] Marketplace (24 roles, identities, install/update flow, onboarding wizard)
+- [x] Board (Kanban, real-time via Centrifugo)
+- [x] Frontend (React 19, dashboard, marketplace, billing, admin)
+- [x] CI/CD (GitLab, tests, auto-deploy)
+- [x] Monitoring (Prometheus, Grafana, Loki)
+- [x] Telegram bot pool management
+
+### 🔜 Фаза 1: Launch-ready (4 недели)
+
+- [ ] Landing page + sign-up flow
+- [ ] Prompt caching в Anthropic Proxy
+- [ ] Standalone agent onboarding (connect flow)
+- [ ] Usage dashboard (charts, per-model breakdown)
+- [ ] Email notifications (SES)
+- [ ] Overage billing через Stripe metered
+- [ ] Documentation (user-facing)
+
+### 🔮 Фаза 2: Growth (2-3 месяца)
+
+- [ ] Pod scale-to-zero для idle agents
+- [ ] Discord, Slack, WhatsApp каналы
+- [ ] Standalone BYOK (Bring Your Own Key)
+- [ ] Premium marketplace roles
+- [ ] Referral program
+- [ ] Mobile companion (node pairing)
+
+### 🚀 Фаза 3: Scale (6+ месяцев)
+
+- [ ] Multi-region (US, Asia)
+- [ ] Anthropic Batches API для cron-задач
+- [ ] Shared browser pool
+- [ ] Enterprise features (SSO, audit logs, SLA)
+- [ ] ClickHouse для usage analytics
+- [ ] API access для разработчиков
+
+---
+
+## 10. Риски
+
+| Риск | Вероятность | Импакт | Митигация |
+|------|-----------|--------|-----------|
+| Anthropic повышает цены | Средняя | Высокий | Model routing, prompt caching, multi-provider roadmap |
+| Anthropic запускает hosted agents | Высокая | Критический | Standalone (они не дадут self-host), marketplace, multi-model |
+| Docker Hub rate limits | Высокая | Средний | ECR mirror, authenticated pulls (уже реализовано) |
+| EADDRINUSE и баги openclaw | Средняя | Средний | Pin версии, тестировать перед upgrade |
+| Низкий retention | Средняя | Высокий | Onboarding flow, marketplace, memory lock-in |
+| Cash flow до breakeven | Средняя | Высокий | Lean team ($21K/мес OpEx), standalone (high margin) |
+| Регуляторные риски (EU AI Act) | Средняя | Средний | Standalone = data stays with user |
+
+### Ключевой hedge: Standalone
+
+Если Anthropic или другие запустят managed agents — наш standalone план остаётся уникальным. "Managed experience для self-hosted" — это ниша, которую гиганты не будут закрывать.
+
+---
+
+## Приложение A: Технический стек (актуальный)
+
+| Компонент | Технология | Версия                        |
+|-----------|-----------|-------------------------------|
+| Backend | Node.js + Express + TypeScript | Node 22, TS 5.x               |
+| Frontend | React + Vite + Tailwind | React 19, Vite 6, Tailwind v4 |
+| Agent-Controller | Node.js (npm package) | 0.1.5                         |
+| Agent Runtime | OpenClaw | 2026.2.21                     |
+| Database | PostgreSQL | 16                            |
+| Message Queue | RabbitMQ | 3.x                           |
+| Real-time | Centrifugo | v6                            |
+| K8s | EKS (AWS) | 1.31                          |
+| Autoscaler | Karpenter | 1.6.3                         |
+| VMs | EC2 ARM64 (Ubuntu 24.04) | t4g family                    |
+| Storage | S3 + CloudFront + EBS gp3 | —                             |
+| CI/CD | GitLab CI | —                             |
+| Monitoring | Prometheus + Grafana + Loki | —                             |
+| Billing | Stripe + Tinkoff | —                             |
+| DNS | Route53 | —                             |
+| VPN | AWS Client VPN | —                             |
+| IaC | Terraform | 1.x                           |
+
+---
+
+*Документ обновлён: 2026-02-22. Версия 2.0.*
+*Основано на реальной архитектуре проекта.*

package/CLAUDE.md

@@ -59,6 +59,64 @@ Ask if I want one of two options:
 
 FOR EACH STAGE OF REVIEW: output the explanation and pros and cons of each stage's questions AND your opinionated recommendation and why, and then use AskUserQuestion. Also NUMBER issues and then give LETTERS for options and when using AskUserQuestion make sure each option clearly labels the issue NUMBER and option LETTER so the user doesn't get confused. Make the recommended option always the 1st option.
 
+## Codebase Navigation
+
+### Project Structure
+```
+src/
+├── index.ts           # Entry point — parse args, start connection
+├── connection.ts      # Centrifugo WS client, command dispatcher
+├── heartbeat.ts       # Periodic heartbeat publisher
+├── api.ts             # HTTP client for backend API calls
+├── types.ts           # AgentCommand, AgentResponse, CommandType
+├── handlers/          # Command handlers (backend → agent)
+│   ├── file-write.ts      # Write file to workspace
+│   ├── file-delete.ts     # Delete file from workspace
+│   ├── package-install.ts # Install apt/npm/pip packages
+│   ├── restart.ts         # Restart openclaw gateway
+│   ├── stop.ts            # Stop agent
+│   ├── backup.ts          # Create workspace backup
+│   ├── config.ts          # Update config files
+│   ├── deploy.ts          # Deploy/redeploy
+│   ├── exec.ts            # Execute shell commands
+│   ├── chat.ts            # Chat relay
+│   ├── onboarding.ts      # Onboarding completion
+│   ├── pair.ts            # Node pairing
+│   ├── board-handler.ts   # Kanban board integration
+│   └── self-update.ts     # Self-update via npm
+├── commands/          # CLI subcommands (agent-controller <cmd>)
+│   └── self-update.ts # `agent-controller self-update`
+└── openclaw/          # OpenClaw gateway process management
+```
+
+### Command dispatch flow
+```
+Centrifugo WS message → connection.ts (handler map) → handlers/<type>.ts → AgentResponse → publish back
+```
+
+Handler map in `connection.ts`:
+```ts
+const handlers: Record<CommandType, Handler> = {
+  package_install: handlePackageInstall,
+  file_write: handleFileWrite,
+  file_delete: handleFileDelete,
+  restart: handleRestart,
+  // ...
+};
+```
+
+### Adding a new command handler
+1. Create `src/handlers/my-handler.ts` — export `async function handleMyHandler(cmd: AgentCommand): Promise<AgentResponse>`
+2. Add `'my_handler'` to `CommandType` union in `src/types.ts`
+3. Register in handler map in `src/connection.ts`
+4. Backend sends via `container.centrifugo.publishCommand(agentId, { type: 'my_handler', id, payload })`
+
+### Known Issues & Pitfalls
+- **WORKSPACE_DIR**: Defaults to `/etc/openclaw/workspace`. All file operations are sandboxed here (no `..`, no absolute paths).
+- **Command names must match backend exactly**: e.g. `package_install` not `install_packages`. Mismatches silently drop.
+- **npm publish required**: After changes, bump version in `package.json`, `npm publish`, then update agent Dockerfile + user-data.ts to pull new version.
+- **PID 1 kill**: If agent-controller crashes, it kills PID 1 to force K8s pod restart. Don't swallow fatal errors.
+
 ## Quick Reference
 
 ```bash
@@ -105,3 +163,9 @@ Agent-controller is delivered via **npm** (not Docker image copy):
 ### Docker
 
 The `Dockerfile` in this repo is for **local development and testing only**. It is NOT used in production. Production installs agent-controller from npm registry.
+
+
+## Business Context
+
+For full understanding of all platform components, architecture, deployment models, roadmap, and unit-economics — see `BIZPLAN.md` in this repo.
+