🔄 Synced from the canonical monorepo — live history. alexar76/aicom is a trimmed public mirror of AI-Factory (satellites live in their own repos). History here is append-only (no force-push). Pull requests are welcome — merged PRs are imported back into the monorepo (scripts/import_factory_pr.sh) and re-synced here, so your contribution becomes canonical. 💬 Issues · Pull requests both welcome.

AI-Factory

Not sure where to start? Eleven ways into the ecosystem, by what brought you here: check your agents' tools, trade with agents, or run it yourself.

Own a weather station or air-quality sensor? Sell your readings through your own Hub + GAIA.

Build with n8n? Run a read-only order-check service on your own hub: English · Русский · Español · Français · 中文.

MIT · self-hosted · idea → shippable web product
Part of the AICOM research and demo ecosystem.
Factory & storefront: magic-ai-factory.com · Community: Ask Castor (bot) · Castor channel · Discord · Pollux · THEOROS canon
Factory landing · Ecosystem landing · Demo video · Build Replays · Factory hold · Gallery · Factory IQ · Ecosystem · Quick start

Reviewing MCP tool changes? See a recorded change in HISTOR, scan a tool list with WARDEN, or implement the tool-set digest.

English · Русский · Español · Français · 中文 · Glossary

Agents can already pay each other. We make it possible for them to trust each other.

⚠️ Pay-on-Verified — read before relying on it. A buyer can make payment conditional on an independent verdict: the hub holds the price and pays the seller only if the delivery passes; a failing delivery is refunded. The verdict comes from an LLM jury (Metis) judging the delivery against the intent the buyer wrote — evidence, not proof. It works only on escrow-backed payment channels, for capabilities the hub executes itself, from $0.05. → What it does not promise · How to enable it · A run on real money

Discussions: Roadmap · Q&A · Show & Tell · Announcements: Roadmap updates

🟢 Try the live MCP demo — no wallet, no Docker, no clone

Paste this one URL into any MCP client (Claude Desktop, Cursor, Windsurf, …):

   https://modelmarket.dev/mcp

Two tools do the work against the live hub: market_search finds a capability in the published catalogue, market_invoke runs one and hands back the hub's signed receipt (the server lists a few more: direct weather, air quality, sensors, randomness, multi-step pipelines and your balance). A few trial invokes per caller are free — no key, no account, no wallet, nothing to install. When the allowance runs out the hub answers 402 and the on-chain escrow path begins, which is where the wallet finally matters.

Setup snippets per client, the trial rules, and how to verify a receipt → docs/hosted-mcp-endpoint.md

🔴 Live on Base MAINNET (demo) — not a testnet

The full contract suite — escrow, lottery, capability-NFT, ACEX (vault/registry/lending/AMM/ audit-pool), and the ZK verifier — is deployed and source-verified on Base MAINNET (chainId 8453, real USDC + ETH, small demo sums). Every deploy + transaction is documented, with Basescan links, in → docs/onchain-journal.md. This is not Base Sepolia / a testnet and not the local UNI/anvil simulation.

A general production launch for users is still gated on operator items tracked in docs/known-issues.md (KI-3 load test, KI-4 multisig; KI-2 external audit waived for pet project — see docs/pet-project-trust.md). KI-1 ZK trusted-setup resolved (PLONK). The self-hosted pipeline + storefront are usable today.

AI-Factory turns one prompt into a shippable web product — a multi-agent pipeline (research → design → code → QA → deploy) with a built-in storefront, payment rails, and live observability. Self-hosted: your keys, your infra, your data.

↑ Watch on YouTube — same hero clip as magic-ai-factory.com

---

▶ Demo video

Primary: YouTube — Idea → agents → shippable product (embedded on the live homepage hero).

GitHub’s README viewer does not embed YouTube iframes — use the thumbnail above or open the link. For an offline / admin UI clip, use the MP4 below (recorded from production Admin).

Where	How
YouTube	youtu.be/Gg9a52-ZbNA — marketing walkthrough
Live site	magic-ai-factory.com — hero embed + guest landing try-out
Admin replay	Login → Live Monitor or Settings → Demo replay (when published)
Public API	GET /api/public/pipeline-demo-replay (uploaded clip, no auth)
Download	.mp4 · .webm
Regenerate admin clip	python scripts/record_pipeline_demo_video.py → python scripts/sync_demo_replay_from_recording.py

---

🧠 Factory IQ — watch the factory get smarter

A self-learning autonomous factory, made visible. Realized Expected Value per build over time (live vs a frozen-control cohort — the gap is the value of learning), the validated playbook the agents distill from their own outcomes, ship-rate, cost, and AI-gatekeeper calibration. The number should climb.

Public demo	https://magic-ai-factory.com/iq
API	GET /api/analytics/factory-iq (snapshot) · GET /api/public/factory-iq (gated by AIFACTORY_PUBLIC_IQ=1)
How it works	docs/effective-self-learning.md — EV objective, 4 learning loops, distilled playbook, calibration, proof
Source	pulse-terminal · acex

📢 Ecosystem companions

Separate repos — not part of the factory install. Full map: ecosystem.modelmarket.dev · knowledge base. One line Links 🛡️ ARGUS-3 Demand-side agent · WARDEN MCP firewall · crypto off by default landing · argus · npm i -g @alexar76/[email protected] 🧱 MCP tool firewall (WARDEN) Review advertised tool definitions or enforce pins in a stdio wrapper. Zero runtime dependencies @aimarket/warden · source MCP tool history (HISTOR) Signed observations of what servers advertised and when their tool definitions changed history and checks Solidity scanner (BASANOS) Signed findings for Solidity at a pinned source commit source 👽 Alien Monitor 3D graph of Hub, Factory, chain metrics LIVE · UNI · split · alien-monitor 🔮 Oracles 17 signed math capabilities (randomness, VDF, reputation, …) portal · oracles 🌍 GAIA Physical-world oracle gateway · attested IoT sensors · plausibility verify gaia 📜 SYMMARTYS Signed public-record facts: VAT, LEI, exchange rates, sanctions lists and timestamps symmartys.modelmarket.dev 🗺 ATLAS Planetary sensor map over GAIA · LIVE/SIM pins · Analyst live · atlas 🧠 Metis Cognition / verification tier — factory uses it as a confidence gate demo · metis 🧿 LOGOS Read-only federation analytics — measured settlement volume, rolling z-score anomalies, cross-source correlations, guarded NL assistant live · landing · logos 🛰️ SKOPOS Fleet observability — nginx/Apache analytics, Security Center, AI analyst live · skopos 🔌 aimarket-mcp Shared MCP: web_fetch · web_search · metis_verify Glama · aimarket-mcp 📈 Pulse (ACEX) CapShare NAV · Proof-of-Audit · live pricing live · pulse-terminal Experiment, not a product. 🎰 Lottery: a verifiable draw among the demo agents on a private test chain ("machine UBI" for mesh agents). Nobody plays for money: paid tickets are off on Base and the live lottery held 0 ETH on 2026-11-11; it is not paused (the contract paused on 2026-11-05 is a superseded one). demo · lottery Monorepo operators: ./scripts/deploy_ecosystem.sh can co-deploy Factory + Hub + ARGUS + Monitor + lottery relayer — see deploy-ecosystem.md. You do not need any of this to run AI-Factory alone.

---

One sentence → a shippable web product (landing or full stack). Self-hosted.

Attested Memory SaaS family

A separate customer-facing SaaS contour is built on the Attested Memory Hub (attestedmemory.net, source: attested-memory). It provides one public edge for Personal Memory, Team Memory and Expert Memory Market. Crypto checkout uses exact canonical USDC on Base through the independent KOVA adapter; the SaaS gateway never holds wallet private keys. Its user guides and use cases, in ten languages, are kept with the Attested code.

Typical wall-clock (DeepSeek, no QA rework loops): marketing_landing ~20–25 min to first previewable code; full_software ~25–45 min for a simple brief, hours when gates iterate — FAQ & scope. Not a 15-second generator.

Typical LLM API cost: ~$0.30–$2 landing first pass; tiny full_software can land under ~$0.20 to first COMPLETED (measured); ~$3–$15+ when QA/repair loops pile up. Bring your own keys; host ~$7/mo separate.

Pipeline roles (one Python class each under agents/): Analyst, PM, Methodologist, Architect, Design Critic, Developer, DevOps, Evolution Analyst, Hardening, Marketing, Product Profile, QA, Sales, Security, Spec Quality Gate, plus base_agent.py. Most run in order; Methodologist / Design Critic / Hardening are conditional gates. The canonical sequence is config/pipeline_flow.json. Runtime adds a test gate, Playwright E2E, security scans, and storefront deployment.

Quick start

Three ways in, by how much you want to run:

You want	Run	You need
An agent that uses the live economy	paste https://modelmarket.dev/mcp into any MCP client (setup per client)	nothing
Your own hub: sell your API, join the federation	pip install "aimarket-hub[pqc]" → aimarket quickstart --name "My hub" → aimarket serve (guide)	Python 3.11+
The Factory in a browser	Open the hosted demo	nothing
The Factory on your machine	the commands below	Git, Bash, Python 3, curl, Docker with Compose v2, and an LLM key for agent builds

git clone https://github.com/alexar76/aicom.git
cd aicom
cp .env.demo .env          # Add a provider key such as DEEPSEEK_API_KEY for agent builds.
./start.sh                 # builds + boots, opens the browser
# → Factory  http://localhost:9080         idea → real AI build
# → admin/login: user admin, password printed by start.sh

From this public repository ./start.sh runs the Factory (with Prometheus and Grafana). The Hub, Service Mesh and Alien Monitor are published as their own repositories — aimarket-hub, ai-service-mesh, alien-monitor — and run from there. Every secret is generated for you; crypto/mainnet stays off — no wallet, no real funds (core/crypto_config.py).

The Factory uses templated output until you configure an LLM key.

Checkout	Command	What comes up
Public AICOM clone	./start.sh	Factory, Prometheus and Grafana.
Public AICOM clone	Open in a Dev Container / Codespaces	The Factory stack in a Linux box with ports forwarded and .env prepared.
Complete monorepo	./start.sh	Factory + Hub + Mesh + Alien Monitor.
Complete monorepo	./start.sh --full	The 15-satellite fleet via scripts/quickstart_ecosystem.sh.
Complete monorepo	./start.sh --everything	All three prod hosts on one machine, about 40 containers. Needs ≥60 GB disk, ≥16 GB RAM, 4+ cores and Linux x86-64 (runbook).

Handy: ./start.sh --down (stop, keep data) · --logs · --no-build · --no-open · --help.

📖 Every launch option — what runs when, and what gets deployed (services, ports, safe-defaults): docs/running.md.

Which docker-compose.*.yml is which?

File	Purpose
docker-compose.yml	Root Factory stack — app + Prometheus + Grafana. The single-container "batteries-included" self-host.
docker-compose.core.yml	Core overlay (used by ./start.sh in the complete monorepo). Adds Hub, Mesh and Alien Monitor on the shared bridge.
docker-compose.prod.yml	Production overrides (TLS, external URLs).
docker-compose.pg.yml	Switch the pipeline store to PostgreSQL.
docker-compose.secrets.yml	File-based secrets overlay (keys as Docker secrets, not env).
docker-compose.dind.yml / .host-docker.yml	Sandbox Docker access: DinD sidecar (default) vs host socket (escape risk).
docker-compose.host-gateway.yml	Reach a host-local LLM (e.g. Ollama) from the container.
docker-compose.split.yml	Run API / worker / web as separate containers instead of one.

Admin access

🌐 Live Demo

Try it out: https://magic-ai-factory.com

Production metrics (RPS, latency, incidents): docs/production-metrics.md · live JSON GET /api/public/ecosystem-status

Demo Admin Access:

• URL: https://magic-ai-factory.com/admin/login
• Username: admin — no password on the shared public demo (click Enter admin demo)

⚠️ Public demo disclaimer: applies only to magic-ai-factory.com — a shared site, not your private factory. Production .env must include AIFACTORY_DEMO_READONLY=1 so visitors cannot change settings, save Settings, or run factory backup/restore. See docs/security.md.
Self-hosted: bootstrap password (data/secrets/bootstrap_admin.txt or TTY prompt); leave AIFACTORY_DEMO_READONLY unset or 0.

Self-hosted (first install)

There is no default password in the repo. On an empty data/ volume, the entrypoint runs bootstrap — password from the interactive console (TTY) or data/secrets/bootstrap_admin.txt on headless up -d. See docs/security.md.

Faster after the stack is up: ./demo.sh "SaaS for managing remote teams" (set DEMO_ADMIN_PASSWORD to your bootstrap password; opens Pipeline).

Positioning

AI-Factory is a different shape from hosted builders like Bolt.new, Lovable, v0, or Devin: it’s a self-hosted MIT pipeline you run on your own box with your own LLM keys, and it persists artifacts, state, and gates on disk you control. Those products are polished hosted experiences and ship features we don’t have (cloud editor, team accounts, prebuilt integrations); we trade that for transparency, no per-seat pricing, and the option to fork. If you want zero-ops and a managed UI, use them. If you want the agents, gates, and storefront under your control, keep reading.

Part of the AIMarket ecosystem

Shipped products can sync to the AIMarket Hub (protocol v2, SDKs, desktop apps). Sibling projects — ARGUS, lottery, oracles, Monitor, Metis, MCP gateway — live in their own repos; see Ecosystem map. Map: ecosystem.modelmarket.dev.

The pipeline

flowchart LR
  A[💡 Idea] --> B[🔍 Discovery]
  B --> C[📋 Analyst]
  C --> D[📝 PM]
  D --> E[🎨 Architect]
  E --> F[👨‍💻 Developer]
  F --> G[🧪 QA + E2E]
  G --> H[🔒 Security]
  H --> I[🚀 DevOps]
  I --> J[📢 Marketing]
  J --> K[💰 Sales]
  K --> L[🔄 Evolution]

Loading

Full diagrams (runtime architecture, state machine, discovery, storefront gates, comparison tables): docs/architecture-diagrams.md.

Module boundaries, sandbox facade, scaling path: docs/architecture/module-boundaries.md, docs/architecture/scaling.md. Production startup guard: AIFACTORY_PROD=1 (refuses demo123 / admin123) — see docs/security.md.

Ship-then-keep-improving

AI-Factory is built around a ship-then-keep-improving loop — not “one shot and forget”:

1. Ship — agents run the full pipeline (spec → code → QA/E2E → security → DevOps). A product reaches COMPLETED / DEPLOYED when it passes the gates at that moment.
2. Gate failures before ship — demo/TZ, browser crawl, security, or methodologist findings send the product to BUG_FOUND → DEV_FIXING. The developer agent retries with repair hints until gates pass or the repair budget is exhausted.
3. Keep improving after ship — already-shipped products are re-audited when marketplace/demo rules tighten (policy audit) or when they no longer meet storefront readiness (storefront remediation). Eligible products reopen on the same repair path instead of staying stale on the catalog.
4. Bounded effort — AIFACTORY_MAX_QUALITY_LOOPS caps how many remediation cycles one product may take before FAILED (config default 8 in quality settings; override in .env / Compose).
5. Stronger model on hard repairs (optional) — AIFACTORY_GATE_FAILING_MODEL sets a provider-specific model id used only on repair rounds after at least one QA gate failure (quality_repair_round ≥ 1). It does not switch providers — only overrides the model name on the routed provider (e.g. DeepSeek-only: deepseek-v4-pro or deepseek-reasoner; leave unset to use normal heavy/light routing).

The public homepage shows live counts via GET /api/public/pipeline-status (products in pipeline vs shipped) — same operational truth as Admin → Pipeline.

Details: docs/pipeline-operations.md (policy audit, storefront remediation, QA E2E).

⏸️ Factory hold — soft pause vs hard stop

Admin → Settings → Factory hold lets you pause the factory without shutting anything down. There are two distinct levels, and they behave differently on purpose:

Level	How to set	What pauses	What keeps running
Soft hold	UI toggle / config general.factory_on_hold	Director auto-enqueue (new autonomous ideas), batch-queue drain, and post-ship improvement work (market monitoring, refactor sprints, storefront re-remediation). In-flight autonomous products freeze on disk and resume when you switch back to RUNNING.	✅ On-demand builds — anything a human explicitly requested: admin “New product” and the public guest fast-path landing generator. These keep building so the “type an idea → watch it build” experience (and the live demo) never silently stalls.
Hard stop	env AIFACTORY_FACTORY_ON_HOLD=1	Everything, including on-demand work. A true emergency kill switch — the pipeline worker bails out of every cycle.	—

Why fast generation works under a soft hold: the soft hold is, by design, a pause on autonomous and post-ship work — not on work you explicitly asked for. Products created through the web API are tagged on_demand at creation (web/backend/main.py → _append_product_to_pipeline); the worker partitions each cycle and advances only those while a soft hold is active, re-attaching the paused (held) products before every save so nothing is lost. Classification lives in core/product_origin.py; the soft-vs-hard distinction in core/factory_hold.py (is_factory_on_hold vs is_factory_hard_stopped); the worker logic in pipeline_worker.py (_process_cycle).

Operator note: if you need to stop all spend/work immediately (incident, runaway cost), use the env hard stop — the UI soft hold intentionally still serves explicit on-demand requests. Soft hold is allowed in public demo mode (AIFACTORY_DEMO_READONLY=1), so guests can still generate a landing while autonomous work is paused.

Full table, persistence, and admin banner behavior: docs/pipeline-operations.md.

Broader recovery (backup/restore, migration rollback, pipeline reopen, ZK artifacts, fleet redeploy): docs/recovery-mechanisms.md.

🎬 Build Replays — shareable, public

Every build gets a public, shareable replay of how the agents made it — research → design → code → QA → security → deploy — as a step-by-step timeline you can scrub and play. No login.

One build	https://magic-ai-factory.com/build/{id} — playable agent timeline + social card
Gallery feed	https://magic-ai-factory.com/builds — recent builds, one card each
JSON (one)	GET /api/public/build/{id} — sanitized stage timeline (no prompts/secrets/raw output)
JSON (feed)	GET /api/public/builds?limit=24 — slim cards for the gallery
Social card	auto-generated opengraph-image (1200×630 PNG) per build — link previews on X/Telegram/Slack

The replay surface is a hard public boundary: it only ever emits a whitelist of safe scalar highlights (verdict, score, files, stack, findings, …) plus durations, gate/retry badges, and pass/fail — never agent prompts, raw output, error text, paths, or keys. Boundary lives in web/backend/services/build_replay.py; coverage in tests/test_build_replay_public.py.

Try without Docker: docs/sample-output/build-replay-spliteasy.json (static example). One command: ./scripts/quickstart.sh after clone.

Gallery

Built pages only (1440×900 WebP): screenshots are /api/sandbox/file/…/index.html — refresh with python scripts/capture_gallery_landings.py (stack on http://127.0.0.1:9080). Details: docs/gallery/README.md.

Full-stack demo tiles (fullstack-01.webp … 04): python scripts/capture_gallery_fullstack_packaging_demo.py — see docs/gallery/README.md.

---

Deploy & production

Deploy (Docker Compose)

./scripts/deploy.sh appends missing keys to .env only (optional --public-url sets NEXT_PUBLIC_SITE_URL and AIFACTORY_CORS_ORIGINS; generates AIFACTORY_FIREWALL_RULES_FERNET_KEY when possible; defaults AIFACTORY_SANDBOX_PREVIEW_NETWORK_ISOLATION=1), then runs docker compose build + up -d app. Logic: scripts/fill_production_env.py (--dry-run supported).

chmod +x scripts/deploy.sh   # once
cp -n .env.example .env      # if you do not have .env yet
./scripts/deploy.sh --public-url https://your-factory.example.com

Why not fully automatic: the script cannot infer your real public URL without you (or your reverse proxy). Existing .env assignments are never overwritten so we do not clobber secrets you already set.

North star: turn a short plain-language brief into a presentable web page you can share — with quality gates (demo/TZ, browser smoke, optional marketplace rules) so sloppy stubs get reworked. One pipeline for everyone: autonomous mode starts with a dedicated Discovery layer (external signals → validation → scoring/ranking) before creating IDEA_RECEIVED; on-demand runs the same downstream stages.

See docs/product-concept.md for positioning, guarantees, default ~$4.99 USDT landing pricing when no product price is set, i18n (NEXT_PUBLIC_MARKETING_LOCALE), and fork branding. Homepage → Admin: phrase prefill and /admin?tab=new-product&idea=… — docs/marketing.md.

Production hostname notes: docs/production-domain.md (magic-ai-factory.com, nginx → Compose 9080).

Default endpoints (Compose)

What	URL
App	http://localhost:9080
API health	http://localhost:9081/api/health
Prometheus	http://localhost:9090
Grafana	http://localhost:9082

Try it — prompts, demo.sh, packaging

Prompt starters (Admin → New Product)

Default mode is full product (full_software). Use What to ship for brochure-only, or ./demo.sh --landing from CLI.

💡 Prompt	Notes
SaaS for managing remote teams — dashboard, auth, API	Default = full stack
Echo / voice notes app with backend sync	Full product
Landing page for resume builder	Marketing landing page only in Admin, or ./demo.sh --landing "…"

One command — enqueue + open Pipeline

chmod +x demo.sh    # once
./demo.sh "SaaS for managing remote teams"          # default: full_software
./demo.sh --landing "Landing page for resume tool"   # brochure-only (faster)
./demo.sh --compose "Attested SaaS family"            # Docker UI on :9080

Requires Docker + LLM keys in the container env. Opens Admin → Pipeline; a full run takes several minutes — visible autonomy, not instant magic.

Packaging & live URLs

• Auto-publish — After DevOps, optionally deploy data/code/<product_id>/ to Vercel, Netlify, or Cloudflare Pages (Admin → Settings → Auto-publish). Tokens via env (VERCEL_TOKEN, NETLIFY_AUTH_TOKEN, CLOUDFLARE_API_TOKEN). docs/auto-publish.md. Manual: python3 scripts/publish_product_now.py prod-….
• Full_software → cloud (e.g. Railway) — docs/deploy-full-software-cloud.md.
• Demo replay video — python3 scripts/sync_demo_replay_from_recording.py.
• Batch demos — ./batch-demo.sh.
• “Built with AI-Factory” badge — Admin → Settings.

Gallery — full_software capture

.venv/bin/python -m playwright install chromium   # once
.venv/bin/python scripts/capture_gallery_fullstack_packaging_demo.py

From a real pipeline product:

GALLERY_FS_PRODUCT_ID=prod-xxxxxxxxxxxx \
  .venv/bin/python scripts/capture_gallery_full_software.py

End-to-end demo seed: ./scripts/demo_seed_fullstack.sh

CI/CD, smoke tests & Discovery

Screen recordings & Git remotes

Before screen recordings or streaming, avoid showing git remote -v if the URL embeds credentials. Prefer:

git remote set-url origin https://github.com/<you>/<repo>.git

CI/CD

• Gitea: .gitea/workflows/deploy.yml
• GitHub: .github/workflows/ci.yml runs pytest and the frontend build. The backend job attaches its coverage report to the run.
• Pre-release: docs/github-release-checklist.md

Full Pipeline Smoke

docker compose exec -T app /app/venv/bin/python3 /app/scripts/full_pipeline_smoke.py <product_id>

Enforces API/frontend health, tests/test_demo_quality_gates.py, and scripts/real_e2e_smoke.py (static / FastAPI / Docker preview — docs/pipeline-operations.md).

Policy audit: worker re-checks COMPLETED products when marketplace rules tighten (AIFACTORY_POLICY_AUDIT_* in .env.example).

Discovery (pre-pipeline)

• Engine: director/discovery_pipeline.py
• Flow: Signal Collector → Need Validation → Idea Scorecard → Ranked ideas → IDEA_RECEIVED
• Artifacts: /app/data/discovery/signals.jsonl, ranked_ideas.json, weekly_digest.md
• Continuous mode: AIFACTORY_DISCOVERY_INTERVAL_HOURS

ai-company discover --top-k 5 --enqueue
POST /api/admin/discovery/run   # JWT; see OpenAPI /api/docs

Documentation index

• docs/USER_GUIDE.md — illustrated user guide
• External diagnostics — optional AIMarket purchases for repeated repair failures; budgets, provider contract and recovery (EN / RU / ES / FR / ZH)
• docs/owner-guide.md — platform owner handbook
• docs/api-integration-guide.md — REST auth, curl examples
• docs/cli-reference.md — container CLI
• docs/README.md — index, admin navigation map
• docs/admin-guide.md — every Admin tab
• docs/FAQ.md · docs/FAQ.ru.md
• docs/known-issues.md — open items (KI-1…KI-10: audit, oracle crypto, Factory/Metis/ARGUS/Hub maturity) — review before mainnet
• docs/ecosystem-maturity-review.ru.md — external scorecard validation + action plan
• Screenshots: cd web/frontend && npm run capture-docs-screenshots

Licensing: LICENSE (MIT), CONTRIBUTING.md, CODE_OF_CONDUCT.md, SECURITY.md

Quick Start (run.sh, data persistence)

1. Prepare data directory (first time only)

mkdir -p ~/aicom-data

2. Build & run

chmod +x run.sh
./run.sh               # build image & start container
./run.sh --no-build    # skip rebuild if image exists

⚠️ Always use run.sh for persistence: ~/aicom-data:/app/data bind mount — products, LLM configs, and logs survive rebuilds.

3. Manual docker run

docker run -d --name ai-factory --restart unless-stopped \
  -p 8080:8080 -p 8081:8081 \
  -v ~/aicom-data:/app/data \
  ai-factory:latest

Host Ollama: docker compose -f docker-compose.yml -f docker-compose.host-gateway.yml up -d

🚨 Use bind mount ~/aicom-data:/app/data, NOT a Docker named volume — named volumes hide data from the host filesystem.

4. Stop & restart

docker stop ai-factory && docker rm ai-factory
./run.sh --no-build

5. Migrate from a named volume

docker run -d --name temp-migrate \
  -v aicom_data:/old-data:ro -v ~/aicom-data:/new-data alpine tail -f /dev/null
docker exec temp-migrate cp -a /old-data/. /new-data/
docker stop temp-migrate && docker rm temp-migrate

Docker Compose (Prometheus + Grafana)

Service	Published	Description
App	9080 / 9081	Frontend + backend + metrics
Prometheus	9090	Metrics
Grafana	9082	Dashboards

cp .env.example .env
chmod +x run-compose.sh scripts/init-compose-volumes.sh
./scripts/init-compose-volumes.sh
./run-compose.sh --build

Service	URL	Credentials
App	http://localhost:9080	admin — password from first-run bootstrap
Grafana	http://localhost:9082	GRAFANA_ADMIN_USER / GRAFANA_ADMIN_PASSWORD

Production checklist: set Grafana password, LLM keys in .env only, HTTPS reverse proxy, Stripe/webhook vars if billing — see docs/security.md.

Grafana: auto-provisioned AI Factory Overview dashboard (pipeline stats, task duration, Director decisions, LLM health).

./run-compose.sh --build
./run-compose.sh --down
./run-compose.sh --logs

SQLite is on by default in Compose (USE_SQLITE=true); entrypoint migrates pipeline.json when present. Data in ./data bind mount.

Access, Admin API, agents & states

Access

Service	URL (Compose)	Port
Frontend	http://localhost:9080	9080
Backend API	http://localhost:9081	9081

Admin Panel

• URL: http://localhost:9080/admin/login
• Login: admin — password from first-run bootstrap (console or data/secrets/bootstrap_admin.txt)

API Endpoints

Public

• GET /api/health — Health check
• GET /api/products — List published products
• GET /api/products/{id} — Product details
• POST /api/feedback/submit — Submit feedback
• POST /api/payment/create — Create payment

Admin (requires auth)

• POST /api/admin/auth/login — JWT
• GET /api/admin/dashboard — Metrics
• GET /api/admin/pipeline/products — Pipeline status
• POST /api/admin/products/create — Create product idea
• Swagger: /api/docs

Pipeline Agents

Admin → AI Agents — 12 roster rows (11 pipeline stages + Evolution Analyst; SSOT config/pipeline_flow.json → web/frontend/lib/pipelineStages.ts):

Analyst → PM → Marketing → Methodologist → Architect → Designer → Developer → QA → Security → DevOps → Sales → Evolution Analyst

Worker also loads Design critic and Hardening (AIFACTORY_EXTENDED_PIPELINE in .env.example).

Pipeline States

IDEA_RECEIVED → SPEC_WRITTEN → ARCH_DESIGNED → CODE_COMMITTED → QA_TESTED → SECURITY_SCANNED → DEVOPS_DEPLOYED → MARKET_CONTENT_READY → SALES_ACTIVE → DEPLOYED_PRODUCTION → EVOLUTION_ANALYZING → COMPLETED

Architecture

High-level runtime layout:

flowchart TB
  subgraph clients["Clients"]
    U["Public storefront"]
    AD["Admin console"]
  end

  subgraph web["Web tier"]
    FE["Next.js :8080"]
    BE["FastAPI :8081"]
  end

  subgraph workers["Background workers"]
    PW["Pipeline worker"]
    DW["Director AI worker"]
  end

  subgraph agents["Specialized agents"]
    AG["12 Admin roster rows + optional Design critic / Hardening (worker)"]
  end

  subgraph llm["Model routing"]
    RT["LLM router"]
    PR["Providers OpenAI-compatible · local"]
  end

  subgraph data["Persistent workspace: host `./data` mounted at `/app/data`"]
    DB["SQLite pipeline state (JSON fallback in tests)"]
    ART["Specs · arch · code · telemetry · logs"]
  end

  subgraph ops["Observability optional"]
    PRM["Prometheus"]
    GRA["Grafana"]
  end

  U --> FE
  AD --> FE
  FE -->|"HTTP `/api/*`"| BE
  BE --> DB
  BE --> ART
  PW --> DB
  PW --> ART
  PW --> AG
  DW --> DB
  DW --> RT
  AG --> RT
  RT --> PR
  CLI["CLI · ai-company"] -.->|"orchestration"| PW
  BE --> PRM
  PRM --> GRA

Loading

Compose maps container 8080/8081 → host 9080/9081.

More diagrams (state machine, discovery, storefront gates, comparison): docs/architecture-diagrams.md.

Ecosystem

Monorepo & AIMarket ecosystem

This repository is the AICOM monorepo: a self-hosted AI-Factory pipeline plus the AIMarket federated commerce layer (hub, protocol, SDKs, 8 desktop apps, 15 plugins).

Factory landing: modeldev.modelmarket.dev — what AICOM builds, how the autonomous company works, and when it uses subcontractors.

Public ecosystem landing: ecosystem.modelmarket.dev — the machine economy, its projects, and how they work together.

Working factory & storefront: magic-ai-factory.com — use the factory and explore its products.

Ecosystem documentation: Knowledge base (RU · ES · FR · ZH) · Whitepaper (RU · ES · FR · ZH) — full guide to every component, MCP, oracles, deploy, and admin.

flowchart TB
  subgraph factory["AI-Factory · magic-ai-factory.com"]
    DISC["Discovery"]
    PIPE["13-agent pipeline"]
    SHIP["Shipped products"]
    DISC --> PIPE --> SHIP
  end

  subgraph aimarket["AIMarket · modelmarket.dev"]
    HUB["AIMarket Hub"]
    PROT["Protocol v2 spec"]
    PLG["15 plugins"]
    HEPHA["HEPHAESTUS studio"]
    HUB --- PLG
    HUB --- PROT
    HUB --- HEPHA
  end

  subgraph hearth["HESTIA · hosted runtime"]
    HESTIA["HESTIA hearth<br/>signed deploy · listen"]
  end

  subgraph amem["Attested Memory"]
    AMEM["Attested Memory<br/>verifiable agent memory"]
  end

  subgraph records["Public-record facts"]
    SYMMARTYS["SYMMARTYS<br/>VAT · LEI · exchange rates · sanctions · timestamps"]
  end

  subgraph security["Admission & assurance"]
    THEMIS["THEMIS admission"]
    BASANOS["BASANOS · Solidity scan"]
  end

  subgraph consume["Consumers"]
    DSK["8× Flutter desktop"]
    WGT["Embed widget"]
    SDK["aimarket_agent SDK"]
  end

  subgraph intelligence["Federation intelligence"]
    LOGOS["LOGOS · read-only analytics"]
    MOMUS["MOMUS findings"]
    SKOPOS["SKOPOS remediation"]
    TREASURY["Treasury balance"]
  end

  SHIP -->|"scaffold · signed deploy"| HESTIA
  HESTIA -->|"explicit announce"| HUB
  SHIP -->|"factory_bridge · sync"| HUB
  THEMIS -->|"admit before catalogue"| HUB
  BASANOS -.->|"assurance pack"| HUB
  DSK --> SDK --> HUB
  WGT --> HUB
  SDK --> AMEM
  HUB -->|"invoke"| SYMMARTYS
  SYMMARTYS -->|"signed answer · source evidence"| HUB
  HUB -->|"stats · manifest · peers"| LOGOS
  MOMUS -->|"finding digest"| LOGOS
  SKOPOS -->|"remediation stats"| LOGOS
  TREASURY -->|"vault · ledger"| LOGOS

Loading

Published packages

Package	Registry	Install	Purpose
aimarket-agent	PyPI	pip install aimarket-agent	Python consumer SDK (AIMarket Protocol v2)
@aimarket/agent	npm	npm install @aimarket/agent	TypeScript SDK — Electron, Node.js, web
aimarket-agent	crates.io	aimarket-agent = "0.2.1"	Rust SDK — Tauri, native CLI
aimarket_agent	pub.dev	dart pub add aimarket_agent	Dart SDK — Flutter desktop/mobile

Ecosystem map

Package	Path	Docs
AI-Factory (this README)	web/ · agents/ · orchestrator/	architecture-diagrams.md
AIMarket Hub	aimarket-hub	README
Oracles	oracles	17 signed math oracles · README
GAIA 🌍 (physical oracles)	gaia	Physical-world oracle gateway — attested IoT sensors, plausibility verify · iot-physical-oracles.md
SYMMARTYS 📜 (public-record facts)	symmartys.modelmarket.dev	VAT, LEI, exchange rates, sanctions lists and timestamps · signed answers with source evidence
ATLAS 🗺 (sensor map)	atlas	Planetary MapLibre map over GAIA — LIVE/SIM pins, Analyst, Alien Monitor embed · atlas.modelmarket.dev · GUIDE
LOGOS 🧿 (federation analytics)	logos	Read-only snapshots, measured settlement volume, rolling z-score anomalies, cross-source insights · live dashboard · README
Protocol v2	aimarket-protocol	spec.md
Hub plugins	aimarket-plugins	README + docs/ per plugin
Desktop SKUs	aimarket-desktop	8 apps · value.md pattern
AIMarket School	aimarket-school	13 free clip lessons (EN/RU/ES/FR/ZH) · edu.modelmarket.dev ↗
AIMarket Courses	aimarket-courses	13 academies (EN/RU/ES/FR/ZH, Colab + Pages): orchestration, sensors, federation, PQC hybrid, verifiable randomness, MCP security, agent economy, trust math, optimization with proofs, smart-contract lotteries, AI Factory pipeline, 3D viz, physics-inspired computing · portal ↗
LinkedIn Profile Coach	linked-in-profile-coach (coach/ in monorepo)	Example integrated app — same class as desktop SKUs (Flutter + AIMarket SDK), focused on LinkedIn profile improvement · linked-in-profile-coach
Dart SDK	aimarket-sdks/dart	Consumer SDK for desktop apps
Widget	aimarket-widget	Drop-in search + invoke
ACEX	acex	Agent Listing Protocol · CapShares · Proof-of-Audit · Pulse Terminal
ARGUS 🛡️ (demand-side agent)	argus	WARDEN MCP firewall + AIMarket consumer/provider; runs fully autonomously, crypto opt-in. Landing · README
WARDEN 🧱 (MCP firewall, library)	warden	The gate chain extracted from ARGUS as a zero-dependency package, so a host can vet third-party MCP servers without adopting an agent: static scan → signed threat feed → origin → tool-def pinning, returning a recorded verdict. ARGUS is its reference host; MOMUS publishes into its feed · npm i @aimarket/warden
HESTIA 🔥 (hearth)	hestia	Isolated hosted runtime for capability providers — not Hub, not Factory, not a job board. Signed deploy; empty roster ≠ empty market · hestia.modelmarket.dev · landing
Attested Memory 🧠	attested-memory	Verifiable memory for AI agents — Memory Market, Truth Layer, Provenance Ledger, MCP. Self-hosted, Docker · attestedmemory.net · landing

Full ecosystem reference (C4, sequences, deployment): docs/ecosystem-architecture.md

Auto-Mesh Pipeline

AI-Factory writes products with its own agents. Its optional external diagnosis flow can buy source-grounded advice through AIMarket after repeated internal repair attempts. The internal developer applies the advice and the existing QA gates remain in charge. It is off until an operator configures an approved provider and budget.

What	Repeated QA finding → approved Hub offer → bounded purchase → internal repair → QA
Why	Shipped products become discoverable capabilities for later runs
Deep dive	Factory vs. separate Auto-Mesh service · Purchase configuration and limits

Production split: Factory :9080 · Hub :9083 → production-modelmarket-dev.md

Full core fleet on one VPS: ./scripts/quickstart_ecosystem.sh (preflight wrapper) or ./scripts/deploy_ecosystem.sh — Factory → Hub → Mesh → ARGUS → Monitor → lottery relayer → landing → verify. Hub step is ./scripts/deploy_hub.sh only. Runbook: docs/quickstart-ecosystem-deploy.md · deploy-ecosystem.md. Oracles (L4), Metis, on-chain are separate.

SQLite, testing & tech stack

SQLite / JSON Backend

PipelineStateMachine uses JSON when a state_file path is passed (tests); otherwise follows USE_SQLITE (SQLite-first in production).

python -m orchestrator.migrate \
  --json /app/data/state/pipeline.json \
  --db /app/data/state/pipeline.db

Tables: products, tasks — nested fields stored as JSON.

Testing

Open a CI run for its commit and look for the coverage-report artifact after the backend job passes. The local .coveragerc includes core/, llm/, security/, web/, agents/, orchestrator/, director/, and pipeline_worker.py. To measure coverage locally, run:

USE_SQLITE=true pytest -q --cov --cov-report=term --cov-report=json:coverage.json
python scripts/generate_coverage_badge.py

Full local suite (backend pytest + frontend Vitest):

./scripts/run_all_tests.sh

See also testing rules, the 2026-10-23 quality audit, and pipeline operations (Testing).

Payment tests and transactions: EN · RU · ES · FR · ZH. Covers checkout, refunds, crash recovery and SQLite/PostgreSQL verification.

Quick smoke (Docker):

docker exec ai-factory python -m pytest tests/test_pipeline.py tests/test_pipeline_sqlite.py -v

Tech Stack

• Backend: Python FastAPI + Uvicorn
• Frontend: Next.js 16 + TypeScript + Tailwind + Framer Motion
• Container: Docker (Python 3.12 + Node 20)
• Security: JWT, TOTP 2FA, audit logging
• LLM: Pluggable providers (OpenAI-compatible, Ollama)

---

FAQ & scope

What is AI-Factory? An autonomous AI software company in a box: discovery → spec → code → QA/E2E → security → deploy → marketing — self-hosted, MIT.

How fast / how much to first COMPLETED? Measured on the live pipeline DB + data/state/pipeline_product_cost.json (Aug 2026):

Profile	Milestone	Observed (this fleet)
marketing_landing	CODE_COMMITTED (previewable HTML)	~21 min (e.g. prod-39fa6ca11222)
marketing_landing	Through QA / fix loops	~40–90+ min when gates fail
full_software (simple brief)	CODE_COMMITTED	~22 min (e.g. prod-9c6296662041)
full_software (complex SaaS)	CODE_COMMITTED after QA blocks	~10 h+ (e.g. FleetMind prod-46e66fe613f7, still in DEV_FIXING)
full_software (tiny habit SaaS)	First COMPLETED	~91 min wall-clock · ~$0.18 LLM · PulseBoard Mini prod-a25224bcb746 (DeepSeek; includes repair loops + operator complete). Source: task timestamps created_at → __complete__, cost ledger pipeline_product_cost.json
Storefront catalog (live check)	Listed products	3 COMPLETED marketing_landing + 1 full_software card (PulseBoard Mini) that later returned to DEV_FIXING / not marketplace-eligible — do not read the catalog as “1 completed full product forever”

Reproduce timing: enqueue via ./demo.sh / Admin → Pipeline, then python scripts/wait_pipeline_product.py --product-id …. Card: PulseBoard Mini.

LLM cost? Per-product totals live in data/state/pipeline_product_cost.json. First fleet full_software to reach COMPLETED: PulseBoard Mini $0.181 ($0.18). Short DeepSeek first-pass ships can stay sub‑dollar when the brief stays tiny; long repair loops and heavy models still climb to dollars. Older fleet-wide averages ($8.5/product including failed loops) remain a useful upper bound, not a promise.

Not a 30-second landing toy. If you only need a fast marketing page, use aicom-landing. AI-Factory targets real products (full stack, gates, evolution).

Who is it for? Operators who want their keys, their data, their host and are OK running Docker + configuring LLM providers.

Who is it not for? Anyone wanting a hosted no-ops builder with zero setup — use Bolt/Lovable/v0 instead.

Questions: docs/FAQ.md · docs/FAQ.ru.md

---

Community

The DIOSCURI twins answer questions from synced GitHub docs. THEOROS publishes the weekly Agent Sovereignty Canon in #the-canon.

Channel	Agent	Best for
Telegram	Castor	Releases, digests, quick news
Discord	Pollux	Help, ideas, show-and-tell
Discord #the-canon	Theoros	Weekly canon column · CANON.md
Discord #canon-debate	Community	Debate precepts · Council vs Solo

Project	Role
theoros	Seven precepts, granite landing, amendable corpus
dioscuri	Runtime — twins + Theoros canon slot (Sun ~16 UTC)

Ecosystem map: ecosystem.modelmarket.dev · AICOM factory · Content playbook

Release announcements are syndicated by KERYX (post-only, no spam automation).

YouTube: HELIOS renders and uploads ecosystem videos — private by default until approve. Landing + gallery · @My-AI-Factory. Click HELIOS on Alien Monitor for live channel stats.

---

Disclaimer

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND. See LICENSE for the full terms.

Smart contracts (contracts/evm/, contracts/solana/) use Ownable-gated admin functions — only the contract owner can authorize hubs and whitelist tokens. The escrow holds funds in a non-custodial model: users deposit directly into the contract; channel participants control their funds; and there is a 24-hour auto-refund path that does not depend on any privileged account. No upgradeable proxies are used.

Deployment: always use the provided deploy scripts (contracts/evm/script/Deploy.s.sol for EVM, contracts/solana/ Anchor scripts for Solana). Do not deploy from a personal EOA — use a dedicated deployer key or the project's multisig to avoid key leaks and ensure deterministic CREATE2 addresses across chains.

• Factory / ecosystem website architecture — EN / RU / ES / FR / 中文.

• Visitor journey: try the factory, review the result, explore the ecosystem — EN / RU / ES / FR / 中文.