{
  "$schema": "https://kdcube.tech/agents.schema.json",
  "name": "KDCube",
  "tagline": "Self-hosted runtime for the AI mini-apps your team builds.",
  "description": "KDCube is an open-source, self-hosted runtime and SDK for focused AI applications. One running deployment binds one effective tenant/project and can serve many users and operator-approved apps. Apps can expose chat, UI, REST, MCP, event, and job surfaces under declared guards. Integrated calls can use accounting and budgets; generated-code isolation depends on the selected execution profile.",
  "homepage": "https://kdcube.tech/",
  "repository": "https://github.com/kdcube/kdcube",
  "discussions": "https://github.com/kdcube/kdcube/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-07-18",

  "elevator_pitch": [
    "You build a useful agent. Share it with a colleague — they love it.",
    "Try to roll it out company-wide and the hard runtime work appears: identity, access control, cost policy, evidence, configuration, deployment, and operations.",
    "KDCube supplies shared building blocks for that work in one self-hosted, MIT-licensed runtime."
  ],

  "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 running environment binds one effective tenant/project and can host many users and operator-approved apps. A control plane can operate many separately scoped deployments.",
      "boundary_enforcement": "Platform services carry bound context and use service-owned schemas, keys, prefixes, and lookup contracts. Custom stores must define and enforce their own owner and minimum scope. Stronger hostile-environment isolation requires separate deployments or infrastructure."
    },
    "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": "Profile-dependent execution for generated code. The reference split-Docker profile uses a separate networkless executor, narrow mounts, dropped privileges, and supervisor-mediated tools. Local subprocess, legacy combined Docker, and Fargate remote-task profiles have different, documented boundaries.",
      "url": "https://kdcube.tech/docs/security.html"
    }
  },

  "architecture": {
    "ingress": {
      "name": "chat-ingress",
      "port": 8010,
      "responsibility": "API gateway for authentication, admission, routing, and queueing. Rate limits, upload scanning, feature gates, and economics checks apply where the deployment and participating surface configure them."
    },
    "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 generated Python under the selected execution profile. Split Docker is the reference separate-executor profile; local subprocess, legacy combined Docker, and Fargate remote tasks must be assessed by their own documented boundaries. @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": "Category-first, sourced comparisons across agent frameworks, self-hosted runtimes, managed runtimes, AI application builders, observability, and deployment infrastructure. Methodology at /compare.html#methodology."},
      {"title": "KDCube capability ledger", "url": "https://kdcube.tech/compare/capabilities.html", "purpose": "The complete 46-capability KDCube product contract, grouped by responsibility with a source, audit date, and limiting boundary for every claim."},
      {"title": "MCP 2026-07-28 support", "url": "https://kdcube.tech/compare/mcp-2026-07-28.html", "purpose": "Dated, source-backed support record for KDCube's stateless July 28 wire path, legacy interoperability, governed OAuth client registration, regression evidence, and explicit limits on the current conformance claim."},
      {"title": "KDCube with agent frameworks", "url": "https://kdcube.tech/compare/kdcube-with-agent-frameworks.html", "purpose": "How LangGraph, CrewAI, Claude Agent SDK, and custom loops keep their orchestration and framework-owned state while KDCube supplies the application host boundary."}
    ],
    "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": "Accounting and reservation semantics for integrated model, embedding, web-search, and participating custom-call paths."},
      {"title": "Security & Governance", "url": "https://kdcube.tech/docs/security.html", "purpose": "Tenant/project deployment scope, trusted apps, profile-dependent generated-code isolation, server-side credentials, and guarded surfaces."},
      {"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": "app/ai-app/src/kdcube-ai-app/",
    "cli_source": "app/ai-app/src/kdcube-ai-app/kdcube_cli/",
    "platform_docs": "app/ai-app/docs/",
    "example_bundles": "app/ai-app/src/kdcube-ai-app/kdcube_ai_app/apps/chat/sdk/examples/bundles/",
    "reference_bundle": "app/ai-app/src/kdcube-ai-app/kdcube_ai_app/apps/chat/sdk/examples/bundles/workspace@2026-03-31-13-36",
    "docker_compose_all_in_one": "app/ai-app/deployment/docker/all_in_one_kdcube",
    "kubernetes": "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": "workspace@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": "An app can host LangGraph, CrewAI, plain Python, or a Claude Code agent. The platform provides shared runtime services, while the app owns its loop, protected surfaces, data ownership, and instrumentation.",
      "reference": "https://kdcube.tech/claude-code.html"
    },
    "expose_an_mcp_endpoint": {
      "summary": "Decorate app methods with @mcp(...) to serve them as MCP tools. Each endpoint declares its visibility and guard; economics and operational records apply only where the participating paths are configured.",
      "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": "Integrated model, embedding, web-search, and participating custom-call paths can use reservation-then-commit economics with scoped plans and wallets. Direct uninstrumented spending remains outside automatic enforcement.",
      "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 through a trusted app path. Select the generated-code execution profile explicitly; split Docker is the reference separate-executor profile, while local subprocess is not a security sandbox.",
    "Don't invent tenant, project, or user IDs in app code — use the bound request context and scoped SDK services. A custom direct store or external call must enforce its own ownership contract.",
    "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 and compare/mcp-2026-07-28.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"
  },

  "mcp_endpoints": [
    {
      "name": "kdcube-docs",
      "purpose": "Public, read-only MCP server over the KDCube platform documentation. Search and return sourced excerpts from inside any MCP-capable client (Claude Code, Claude Desktop, Cursor, OpenAI Codex CLI, Gemini CLI, custom scripts).",
      "transport": "streamable-http",
      "url": "https://kdcube.tech/mcp/docs",
      "url_kind": "vanity",
      "url_canonical": "https://dev.kdcube.tech/api/integrations/bundles/demo/demo-march/knowledge@1-0/public/mcp/knowledge",
      "url_canonical_note": "308 method-preserving redirect from the vanity URL. Bundle-pinned — changes when the bundle is re-versioned. Use the vanity URL in client configs.",
      "auth": "none",
      "setup_docs": "https://kdcube.tech/docs/quickstart.html#connect-mcp",
      "claude_code_plugin": {
        "marketplace": "https://github.com/kdcube/claude-plugins",
        "install_commands": [
          "/plugin marketplace add https://github.com/kdcube/claude-plugins",
          "/plugin install kdcube-docs@kdcube",
          "/reload-plugins"
        ],
        "mcp_server_namespace": "kdcube-docs",
        "slash_commands": [
          "/kdcube-docs:search — citation-backed lookup against the KDCube docs",
          "/kdcube-docs:scaffold — generate a starter bundle skeleton"
        ]
      }
    }
  ],

  "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 `workspace@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."
  }
}