{
  "$schema": "https://kdcube.tech/agents.schema.json",
  "name": "KDCube",
  "tagline": "Self-hosted Python platform for AI applications.",
  "description": "KDCube creates the environment where AI applications live: agents, tools, surfaces (chat widgets, smart APIs, dashboards, MCP servers, scheduled jobs), runtime, storage, identity, governance, and economics — all on infrastructure you own. MIT-licensed.",
  "homepage": "https://kdcube.tech/",
  "repository": "https://github.com/kdcube/kdcube-ai-app",
  "discussions": "https://github.com/kdcube/kdcube-ai-app/discussions",
  "license": "MIT",
  "language": ["Python", "TypeScript"],
  "audience": "Developers and platform teams building AI applications they want to host themselves",
  "manifest_version": "1.0",
  "manifest_kind": "agentic-programmer-guide",
  "updated": "2026-05-05",

  "elevator_pitch": [
    "You build a useful agent. Share it with a colleague — they love it.",
    "Try to roll it out company-wide and the fun ends: security, cost control, compliance, per-customer configs, deployment, governance.",
    "KDCube absorbs that work — one self-hosted runtime, MIT-licensed."
  ],

  "core_concepts": {
    "technosystem": {
      "definition": "A self-contained technical environment that hosts everything one or more AI applications need to live: agents, tools, surfaces, runtime, storage, identity, governance, and economics.",
      "coined_at_kdcube": true,
      "url": "https://kdcube.tech/glossary.html#technosystem"
    },
    "bundle": {
      "definition": "Hot-loadable unit of agent definition: Python code, tools, skills, prompts, widgets, configs, secrets, storage layout, scheduled jobs — all packaged as one application unit. Versioned and rollable without restarting the platform.",
      "url": "https://kdcube.tech/glossary.html#bundle"
    },
    "surface": {
      "definition": "User- or system-visible exposure point of a bundle: chat widget, embedded copilot, smart API, full UI, MCP endpoint, scheduled @cron job, real-time dashboard.",
      "url": "https://kdcube.tech/glossary.html#surface"
    },
    "tenant_project": {
      "definition": "(tenant, project) is the deployment scope. One environment = one tenant/project, can host many bundles. Use distinct tenant/project values for customer isolation or for dev/staging/prod stages.",
      "boundary_enforcement": "five layers: gateway admission, runtime context, Postgres queries, file storage paths, Redis namespaces"
    },
    "react_v2": {
      "definition": "Production agent runtime — timeline-first decision loop. Reason, Act, Observe, recorded as ordered blocks in conv.timeline.v1.",
      "url": "https://kdcube.tech/docs/react-agent.html"
    },
    "iso_runtime": {
      "definition": "Five-layer isolation model for untrusted code execution: read-only FS, unshared network namespace, dropped privileges (UID 1001), supervisor-only tool mediation via UID-verified Unix socket, deployment-level resource constraints. As of Apr 30 2026, supervisor and executor run in separate containers by default.",
      "url": "https://kdcube.tech/docs/security.html"
    }
  },

  "architecture": {
    "ingress": {
      "name": "chat-ingress",
      "port": 8010,
      "responsibility": "API gateway: JWT/Cognito auth, rate limits, ClamAV scanning, admission, RBAC, per-customer budgets, feature gates. Enforced before anything is queued."
    },
    "processor": {
      "name": "chat-proc",
      "port": 8020,
      "responsibility": "Bundle execution: dequeues from Redis, loads bundle singleton, runs the agent loop (ReAct v2 / Claude Code / BYO), serves Operations API for bundle widgets and custom views.",
      "scaling": "horizontally scalable; each Uvicorn worker is an independent queue consumer; no sticky worker-to-conversation affinity"
    },
    "isolated_execution": {
      "name": "py-code-exec",
      "responsibility": "Runs untrusted (LLM-generated) Python in ephemeral Docker sandboxes (or Fargate for distributed). @venv declarations pin per-task dependencies."
    },
    "metrics": {
      "name": "metrics",
      "port": 8002,
      "responsibility": "Metrics aggregation; pluggable autoscaling backend"
    },
    "data_plane": ["PostgreSQL (with pgvector)", "Redis", "S3 or local FS for files"]
  },

  "navigation": {
    "narrative": [
      {"title": "Why KDCube", "url": "https://kdcube.tech/why.html", "purpose": "Why we built it — the developer-journey arc (build → share → company-wide rollout → productization burden → KDCube absorbs it)."},
      {"title": "What is KDCube", "url": "https://kdcube.tech/what.html", "purpose": "What it is — the environment your agents live in. Pillar grid of capabilities."},
      {"title": "How it works", "url": "https://kdcube.tech/how.html", "purpose": "Runtime architecture pillars — ingress, processor, isolated execution, timeline, streaming relay, deploy modes."},
      {"title": "Q&A", "url": "https://kdcube.tech/faq.html", "purpose": "Honest answers to questions that come up between sharing a prototype and shipping it company-wide."},
      {"title": "Compare", "url": "https://kdcube.tech/compare.html", "purpose": "KDCube vs LangGraph, CrewAI, AutoGen, Bedrock AgentCore, Dify, Flowise. Sources cited per cell. Methodology at /compare.html#methodology."}
    ],
    "reference": [
      {"title": "Glossary", "url": "https://kdcube.tech/glossary.html", "purpose": "Canonical term definitions; words coined here marked explicitly."},
      {"title": "Docs hub", "url": "https://kdcube.tech/docs.html", "purpose": "Index of technical reference pages."},
      {"title": "Application SDK", "url": "https://kdcube.tech/docs/sdk.html", "purpose": "Bundle anatomy, decorators, ReAct + ISO runtime, deployment."},
      {"title": "Quick Start", "url": "https://kdcube.tech/docs/quickstart.html", "purpose": "First running bundle in minutes."},
      {"title": "Platform Architecture", "url": "https://kdcube.tech/docs/platform.html", "purpose": "Ingress + processor + isolated execution layered model."},
      {"title": "Communication", "url": "https://kdcube.tech/docs/communication.html", "purpose": "Channeled streaming protocol over Socket.IO and SSE."},
      {"title": "Client Integration", "url": "https://kdcube.tech/docs/client-integration.html", "purpose": "How browser clients and MCP-aware agents talk to KDCube."},
      {"title": "Configuration", "url": "https://kdcube.tech/docs/configuration.html", "purpose": "assembly.yaml, bundles.yaml, secrets resolution."},
      {"title": "Deployment", "url": "https://kdcube.tech/docs/deployment.html", "purpose": "Compose, Kubernetes, ECS/Fargate via Terraform."},
      {"title": "Economics", "url": "https://kdcube.tech/docs/economics.html", "purpose": "Per-tenant + per-customer cost accounting; reservation pattern; wallets."},
      {"title": "Security & Governance", "url": "https://kdcube.tech/docs/security.html", "purpose": "ISO runtime, tenant boundary, named secrets, audit trail."},
      {"title": "ReAct Agent", "url": "https://kdcube.tech/docs/react-agent.html", "purpose": "Timeline-first v2 loop: planning, channels, retries, replay."}
    ],
    "engineering_blog": "https://kdcube.tech/blog.html",
    "platform_changelog": "https://kdcube.tech/changelog.html",
    "comparison_changelog": "https://kdcube.tech/compare/changelog.html"
  },

  "key_repository_paths": {
    "platform_source": "kdcube-ai-app/app/ai-app/src/kdcube-ai-app/",
    "cli_source": "kdcube-ai-app/kdcube_cli/",
    "platform_docs": "kdcube-ai-app/app/ai-app/docs/",
    "example_bundles": "kdcube-ai-app/app/ai-app/src/kdcube-ai-app/kdcube_ai_app/apps/chat/sdk/examples/bundles/",
    "reference_bundle": "kdcube-ai-app/app/ai-app/src/kdcube-ai-app/kdcube_ai_app/apps/chat/sdk/examples/bundles/versatile@2026-03-31-13-36",
    "docker_compose_all_in_one": "kdcube-ai-app/app/ai-app/deployment/docker/all_in_one_kdcube",
    "kubernetes": "kdcube-ai-app/app/ai-app/deployment/kubernetes/",
    "terraform_ecs": "kdcube-internal-demo/ops/ecs/terraform/"
  },

  "common_tasks": {
    "build_a_bundle": {
      "summary": "Author a Python package that subclasses BaseEntrypoint and registers via @agentic_workflow. Add tools, skills, prompts, widgets, @cron jobs, optional bundle-served MCP endpoints — all in one folder.",
      "start_at": "https://kdcube.tech/docs/sdk.html",
      "reference_example": "versatile@2026-03-31-13-36 in the platform repo"
    },
    "use_react_v2": {
      "summary": "Default agent loop. Set AI_REACT_AGENT_VERSION=v2 (default) or v3 (experimental). v3 with safe_fanout enables limited multi-action rounds (still sequential).",
      "reference": "https://kdcube.tech/docs/react-agent.html"
    },
    "use_claude_code_or_byo": {
      "summary": "Bundle is framework-agnostic inside. Drop in LangGraph, CrewAI, plain Python, or a Claude Code agent. Platform guarantees the surrounding runtime; bundle owns the loop.",
      "reference": "https://kdcube.tech/claude-code.html"
    },
    "expose_an_mcp_endpoint": {
      "summary": "Decorate bundle methods with @mcp(...) to serve them as MCP tools. Bundle-served endpoints share tenancy + budgets + audit with chat surfaces.",
      "reference": "https://kdcube.tech/docs/sdk.html"
    },
    "schedule_a_cron_job": {
      "summary": "Decorate a bundle method with @cron(\"0 2 * * *\"). Processor owns scheduling. Cron timezone honors the bundle's declared TZ.",
      "reference": "https://kdcube.tech/docs/sdk.html"
    },
    "set_per_customer_budgets": {
      "summary": "Reservation-then-commit economics enforced at admission. Per-customer wallets in Stripe-integrated ledger. Configure caps in gateway descriptor.",
      "reference": "https://kdcube.tech/docs/economics.html"
    },
    "deploy": {
      "summary": "Three runways from one image set: Docker Compose (laptop / single VM), Kubernetes (any cluster), ECS Fargate via Terraform (AWS-native).",
      "reference": "https://kdcube.tech/docs/deployment.html"
    }
  },

  "anti_patterns": [
    "Don't access bundle config directly inside bundle code — go through the runtime read/write contract (see docs/sdk.html).",
    "Don't deploy a bundle update via image rebuild — bundles are hot-reloadable; use the bundle release workflow.",
    "Don't run untrusted code outside the ISO runtime — bundle.run() does not sandbox, py-code-exec does.",
    "Don't cross tenant boundaries in bundle code — the (tenant, project, user) context is resolved at admission and threaded through automatically; manual cross-tenant calls are blocked structurally.",
    "Don't issue conversation IDs from the frontend — ingress mints them and validates supplied IDs."
  ],

  "discoverability": {
    "llms_txt": "https://kdcube.tech/llms.txt",
    "agents_md": "https://kdcube.tech/AGENTS.md",
    "json_ld_pages": ["index.html (SoftwareApplication, WebSite, Organization)", "faq.html (FAQPage with all Q&A)", "glossary.html (DefinedTermSet with per-term DefinedTerm nodes)", "docs/*.html (TechArticle)", "why.html (AboutPage), what.html (WebPage), how.html (TechArticle)"],
    "robots_txt": "https://kdcube.tech/robots.txt — allows ClaudeBot, GPTBot, OAI-SearchBot, PerplexityBot, Google-Extended, CCBot, Applebot-Extended, Meta-ExternalAgent, Bytespider, cohere-ai, DiffbotPersistent",
    "sitemap": "https://kdcube.tech/sitemap.xml"
  },

  "for_agents": {
    "if_you_are_a_coding_agent": "Read AGENTS.md first. It defines the project conventions, voice rules, and 'don't do these'. Then this file (agents.json) for the structured map. Then llms.txt for the curated index of every URL that matters.",
    "if_you_are_helping_a_human_understand_kdcube": "Start with the why → what → how arc. The Q&A page covers the 'when does KDCube stop being overkill' and 'why not just build it ourselves' questions explicitly. The compare page handles 'how does it stack up against X'.",
    "if_you_are_drafting_kdcube_content": "Voice: developer journey arc — build, share, company-wide rollout, productization burden, KDCube absorbs it. The home manifest is the calmer 'KDCube makes life easier when you approach productization' register. Why-page keeps the 'fun' framing as a deliberate narrative anchor; What/How pages are calmer.",
    "if_you_are_writing_a_bundle": "The reference bundle is `versatile@2026-03-31-13-36`. Copy that, then read docs/sdk.html. Bundles run inside chat-proc; untrusted generated code runs in py-code-exec. @cron, @venv, @mcp decorators are your main extension points."
  }
}