KDCube is built around bundles

That single decision shapes most of the SDK's ergonomics:

• One authoring surface for the whole application. A bundle carries Python backend code, optional TypeScript UI widgets and views, tools, skills, outbound MCP tool integrations, optional bundle-served MCP endpoints, prompts, configuration, hosted file outputs, and storage layout — all in one package, versioned together.
• Hot-loadable without restarting the runtime. Bundles can be replaced or upgraded in place; the ingress and processor services stay up. This is what makes "deploy" a small operation, not a downtime event.
• Tenant-scoped by construction. A bundle runs against a (tenant, project, user) context the platform resolves at admission. Storage paths, budgets, decision logs, and streaming channels inherit that scope — the bundle doesn't have to enforce it manually.
• Metered and billed as a unit. Every model call, tool invocation, and storage write routed through the bundle is tagged for economics accounting, so per-tenant spend, audit, and rate limits apply without extra plumbing.
• Framework-agnostic inside. A bundle can use the built-in ReAct v3 loop, LangGraph, CrewAI-authored flows, the separate ISO runtime for controlled execution, plain Python, or no LLM at all. The platform guarantees the surrounding runtime; what happens inside the bundle is your choice.

Environment rule: one tenant/project is one isolated deployment environment. Use a different tenant/project when you need customer isolation or separate lifecycle stages such as dev, staging, and prod. Keep multiple bundles inside one tenant/project when they belong to the same environment.

The rest of this page is a tour of how you actually build one: what a bundle contains, how it plugs into the platform, what the built-in primitives (storage, tools, hosted files, SDK integrations, widgets, APIs, @mcp, @cron, @on_job, @venv) look like, and how you deploy it.

What Is a Bundle?

A Bundle is your application package. It combines Python backend code with optional TypeScript UI widgets and views into a single deployable unit. The package becomes a bundle by subclassing the platform's base class (BaseEntrypoint or a derived variant) and registering with @agentic_workflow.

A bundle is the end-to-end application unit inside one tenant/project environment. It can include backend execution logic, authenticated or public APIs, widget UI, main UI, scheduled jobs, background job handlers, deployment-scoped bundle config, deployment-scoped bundle secrets, and optional per-user state. One environment can host many such bundles at the same time.

Bundle UI is a platform-served surface, not a special iframe concept. A bundle may expose widget UI with @ui_widget(...) and main UI with @ui_main / ui.main_view. KDCube builds and serves those assets through the integrations/static routes; a consuming frontend can render them directly or embed them, and the KDCube control plane often uses iframes for isolation. That iframe is a client display choice, not a bundle object.

Bundle code can be delivered either from git or from a mounted local bundle path. In deployed environments the registry usually points at a git repo, ref, and subdirectory. In local descriptor-driven development, use kdcube init --descriptors-location ... to stage a concrete runtime under --workdir, then iterate with kdcube reload <bundle_id> --workdir <runtime-workdir>.

Most example bundles use the ReAct agent. The current runtime features ReAct v3, selected through AI_REACT_AGENT_VERSION=v3. The ReAct subsystem gives bundles tools, skills, continuous conversations, a sources pool, ANNOUNCE, a signals board, and an event timeline that is not limited to tool calls. AI_REACT_AGENT_MULTI_ACTION=safe_fanout enables limited multi-action rounds in v3, but those actions still execute sequentially, not in parallel. The ReAct round cap can be set globally with ai.react.max_iterations / AI_REACT_MAX_ITERATIONS and overridden per bundle with config.react.max_iterations or react.max_iterations in bundle props. A bundle does not have to use ReAct at all: you can use any LangGraph graph, the ISO runtime as a separate subsystem, a simple request→response pipeline, or no LLM.

Example Bundles

Start from the examples folder in sdk/examples/bundles/. The concrete reference bundle used on this page is versatile@2026-03-31-13-36 — a production-style sample that combines ReAct orchestration, bundle-local tools, widget decorators, REST operations, public endpoint examples, Telegram webhook and Mini App patterns, attachment handling, ReAct-stream-to-Telegram delivery, and custom UI. It is the current reference bundle for bundle authoring docs, but not the reference for @cron or @venv.

Platform Architecture for Bundle Developers

See also: Platform Overview

KDCube is a multi-tenant AI application platform. It provides the infrastructure for deploying conversational AI agents at scale — with streaming, storage, economics, tooling, and extensibility all built in.

A Bundle is your unit of deployment. It's a Python package that plugs into the platform and defines how your AI agent thinks, what tools it uses, how it stores data, what UI widgets it exposes, and how it bills users.

Big Picture: How It All Fits Together

Two Services, One Platform

Bundle Anatomy

A bundle is a Python package with a required entrypoint.py and optional supporting files:

Minimal Entrypoint

from kdcube_ai_app.infra.plugin.agentic_loader import agentic_workflow
from kdcube_ai_app.apps.chat.sdk.solutions.chatbot.entrypoint import BaseEntrypoint
from langgraph.graph import StateGraph, START, END
from typing import Dict, Any

BUNDLE_ID = "my-bundle"

@agentic_workflow(bundle_id=BUNDLE_ID)
class MyBundle(BaseEntrypoint):

    @property
    def configuration(self) -> Dict[str, Any]:
        return {
            "role_models": {
                "solver.react.v2.decision.v2.strong": {
                    "provider": "anthropic",
                    "model": "claude-sonnet-4-6"
                }
            }
        }

    def on_bundle_load(self, **kwargs):
        # Called ONCE per process when bundle first loads.
        self.logger.info("Bundle loaded!")

    async def execute_core(self, state, thread_id, params):
        graph = StateGraph(dict)
        graph.add_node("run", self._run_node)
        graph.add_edge(START, "run"); graph.add_edge("run", END)
        return await graph.compile().ainvoke(state)

    async def _run_node(self, state):
        await self._comm.delta(text="Hello from my bundle!", index=0, marker="answer")
        return {"final_answer": "Done", "followups": []}

BaseEntrypoint Lifecycle

Bundle Lifecycle

A bundle goes through a well-defined lifecycle from discovery to shutdown. Understanding these phases helps you place initialization logic, manage state, and handle configuration changes correctly.

Discovery and Loading

Bundle source can come from git or from a mounted local bundle path. The platform resolves the configured bundle source, imports the module, and finds the class decorated with @agentic_workflow. The loader extracts interface metadata (decorators for widgets, APIs, message handler, and background job handler) and builds a BundleInterfaceManifest that the REST layer and processor use for routing.

Singleton Instance Model

By default each incoming turn or operation creates a fresh entrypoint instance. When the registry sets singleton=true, the platform caches and reuses one instance per loaded bundle spec in the current process worker.

Initialization Hooks

on_bundle_load() must be deterministic and idempotent. It runs before any request depends on the bundle and is the right place for heavy preparation work. Do not store request-local state there.

on_props_changed(...) is different: it runs after effective bundle props changed for the active instance. Use it for long-lived side effects such as prop-derived caches, sidecar wrapper state, or other runtime helpers that must track bundle props. Do not use it for request-local validation or heavy one-time install/build work.

Hot-Reload on Config Change

When you update a bundle's ref in bundles.yaml and re-apply, the platform detects the configuration change via a content hash of the bundle directory. The updated bundle is loaded in the current process without a service restart. on_bundle_load() runs again for the new version, and subsequent requests are served by the refreshed instance.

For props-only live updates, the active bundle instance refreshes effective props on the next invocation, and on_props_changed(...) fires only if the effective props actually changed. Already-loaded singleton bundles in the current worker also receive that hook on live bundles.props.update events.

Shutdown and Cleanup

The platform does not expose a dedicated shutdown hook. Because bundle state should live in external storage (Redis, S3, local shared storage), process termination is safe by design. Transient per-invocation state in OUT_DIR / workdir is scoped to the request and cleaned up automatically.

Storage Surfaces Across Phases

Only deployment-scoped bundle state belongs to bundle descriptors and bundle export. Platform/global deployment state and all user-scoped state stay outside kdcube --export-live-bundles.

For isolated execution, Docker/Fargate supervisors receive descriptor payloads and materialize them before tool bootstrap. Bundle tools therefore read the same platform props, platform secrets, bundle props, and bundle secrets through the normal SDK helpers, while generated code does not receive descriptor files or provider secret env. Set execution.runtime.descriptor_payload_scope: active_bundle when a bundle runtime should receive only its own bundles.yaml and bundles.secrets.yaml sections.

Reference docs: bundle-runtime-configuration-and-secrets-README.md, runtime-read-write-contract-README.md, how-to-configure-and-run-bundle-README.md.

await get_secret_async("b:...") resolves the current bundle from the bound runtime context. During normal bundle execution that context is already present; outside a bound request or bundle runtime, use a fully qualified secret path instead of b:. Use the async helpers in new bundle APIs, tools, cron handlers, and @on_job handlers; sync secret helpers are compatibility APIs for old sync-only code.

Node / TypeScript Backend Inside a Bundle

If your application backend already exists in Node or TypeScript, the supported pattern is to keep the public KDCube app surface in Python and run the Node backend as a bundle-local sidecar.

That split is intentional:

• Python bundle owns decorators, auth, role gating, bundle props, bundle secrets, and the public API / widget / MCP / cron contract.
• Node backend owns internal domain logic behind a narrow route boundary.

my.bundle@1-0/
  entrypoint.py
  backend_src/
    package.json
    src/
      bridge_app.ts

The Python side starts the sidecar through ensure_local_sidecar(...). Current runtime behavior:

• one sidecar instance per worker for the active loaded bundle spec and tenant/project scope
• bundle code reload stops the sidecar and the next call starts it fresh
• props-only updates do not proactively restart the sidecar at publish time
• startup-config changes restart lazily on next use; live config can be pushed lazily through POST /__kdcube/reconfigure

This lets you wrap an existing Node backend without replacing the Python bundle shell. The bundle remains the KDCube application unit; Node is one internal implementation part of that bundle.

Reference docs: bundle-node-backend-bridge-README.md and node-backend-sidecar-README.md.

Interface: In & Out

Using the Communicator

# Stream answer text
await self._comm.delta(text="chunk...", index=0, marker="answer")

# Announce a step
await self._comm.step(step="web_search", status="started", title="Searching the web...")
await self._comm.step(step="web_search", status="completed")

# Emit follow-up suggestions
await self._comm.followups(["Tell me more", "Show examples"])

# Final complete signal
await self._comm.complete(data={"answer": "..."})

REST Operations (for UI Widgets)

Your bundle exposes additional REST operations via the Operations API hosted by the Processor:

POST /bundles/{tenant}/{project}/{bundle_id}/operations/{operation}
GET  /bundles/{tenant}/{project}/{bundle_id}/operations/{operation}

The explicit bundle_id form is now the preferred route. The processor resolves the target method from the bundle’s decorator-discovered interface surface rather than assuming every operation is just workflow.run(). A default-bundle compatibility shortcut still exists at POST /bundles/{tenant}/{project}/operations/{operation}.

Runtime Availability And Visibility

Bundle availability and resource visibility are deployment-scoped bundle props. The whole bundle is gated through the canonical enabled.bundle prop resolved by the platform. APIs and widgets declare code defaults for user types and roles, and can declare prop paths that the Bundle Admin UI can override. Resource enabled flags are stored in bundle props/admin state; do not pass the removed enabled_config argument to @api or @mcp.

@agentic_workflow(
    name="Ops",
    version="1.0.0",
    allowed_roles=("kdcube:role:viewer",),
    allowed_roles_config="visibility.bundle.allowed_roles",
)
class OpsBundle(BaseEntrypoint):

    @api(
        alias="report",
        user_types=("registered",),
        user_types_config="visibility.api.report.user_types",
        roles_config="visibility.api.report.roles",
    )
    async def report(self, **kwargs):
        ...

    @ui_widget(
        alias="admin",
        icon={"type": "emoji", "value": "⚙️"},
        user_types=("privileged",),
        roles_config="visibility.widget.admin.roles",
    )
    async def admin_widget(self, **kwargs):
        ...

    @mcp(alias="automation", transport_config="mcp.automation.transport")
    def automation_mcp(self, **kwargs):
        ...

    @cron(alias="news-sync", expr_config="jobs.news_sync.cron")
    async def news_sync(self) -> None:
        ...

The visibility dot paths are resolved against effective bundle props. Missing or invalid values fall back to the decorator defaults. Empty user-type or role selections are intentional overrides that mean no restriction for that selector. Cron jobs use expr_config; blank or disable values disable the job. MCP endpoint request authorization belongs to the bundle-served MCP app, not to user_types / roles on the @mcp decorator.

Because these values live in bundle props, they work with hot bundle reload and live props updates. This is the mechanism that lets Bundle Admin change bundle visibility, API/widget visibility selectors, resource enabled flags, and scheduled-job expressions without a redeploy.

Continuation Types

Classic vs. Interactive Turn Execution

Long ReAct turns may also emit chat_compaction transport events with semantic type chat.compaction. These mark context compaction start/completion while the turn continues; clients should render them as progress/activity items, not as final answers.

Storage

KDCube is a distributed, multi-tenant system. Three storage tiers are available to your bundle:

Cloud Storage (AIBundleStorage)

from kdcube_ai_app.apps.chat.sdk.storage.ai_bundle_storage import AIBundleStorage

storage = AIBundleStorage(
    tenant="my-tenant", project="my-project",
    ai_bundle_id="my-bundle@1-0",
    storage_uri="s3://my-bucket"  # or file:///data/bundle-storage
)

storage.write("reports/latest.json", data='{"count": 42}')
content = storage.read("reports/latest.json", as_text=True)
keys = storage.list("reports/")

Local FS (Shared Bundle Storage)

# In entrypoint or workflow
root = self.bundle_storage_root()  # pathlib.Path
index_path = root / "knowledge_index"
index_path.mkdir(exist_ok=True)

Path namespaced: {BUNDLE_STORAGE_ROOT}/{tenant}/{project}/{bundle_id}/. Use this helper-resolved storage for local bundle state that should survive across requests on the same instance. Typical examples are knowledge indexes, cloned repos, cron workspaces, prepared local caches, or mutable subsystem roots such as _task_tracker or _knowledge_base_admin. Do not keep operational state next to the bundle source tree. In production, mount the shared instance-visible storage layer here; today that is commonly EFS.

Redis Cache

# Low-level Redis client (aioredis)
await self.redis.set("my:key", "value", ex=3600)
val = await self.redis.get("my:key")

# KVCache wrapper
await self.kv_cache.set("user_prefs", {"theme": "dark"}, ttl=86400)

Workflow Orchestration

The platform uses LangGraph for workflow orchestration. Your execute_core builds and invokes a StateGraph. For common patterns, use BaseWorkflow:

from kdcube_ai_app.apps.chat.sdk.solutions.chatbot.base_workflow import BaseWorkflow

class MyWorkflow(BaseWorkflow):
    def __init__(self, *args, bundle_props=None, **kwargs):
        super().__init__(*args, bundle_props=bundle_props, **kwargs)

    async def process(self, payload):
        scratchpad = self.start_turn(payload)
        try:
            react = await self.build_react(
                scratchpad=scratchpad,
                tools_module="my_bundle.tools_descriptor",
                skills_module="my_bundle.skills_descriptor",
                additional_instructions=self.bundle_prop("react.additional_instructions"),
            )
            result = await react.run(payload)
            self.finish_turn(scratchpad, ok=True)
            return result
        except Exception as e:
            self.finish_turn(scratchpad, ok=False); raise

react.additional_instructions is now a first-class bundle prop. If present, pass it through build_react(...) so the bundle can append deploy-scoped prompt guidance to the React decision system prompt without copying or forking the base runtime prompt.

build_react() respects runtime selection through AI_REACT_AGENT_VERSION. The featured runtime is v3. If AI_REACT_AGENT_MULTI_ACTION=safe_fanout is enabled, accepted multi-action rounds are still executed sequentially. The base round cap resolves from bundle props config.react.max_iterations / react.max_iterations, then assembly/env ai.react.max_iterations / AI_REACT_MAX_ITERATIONS, then fallback 15.

BaseWorkflow Key Parameters

Simplest Agentic Workflow Pattern

A bundle can use any orchestration pattern — it is not required to use the ReAct agent. This is one common pattern that combines a Gate agent with the ReAct agent:

Tools System

# tools/my_tools.py
from typing import Annotated
import semantic_kernel as sk
from semantic_kernel.functions import kernel_function

class MyTools:
    @kernel_function(name="search", description="Search product catalog")
    async def search(self,
        query: Annotated[str, "Search query"],
        limit: Annotated[int, "Max results"] = 5
    ) -> str:
        # your logic here
        return "results..."

# tools_descriptor.py
TOOLS_SPECS = [
    # SDK built-in tool modules (installed package)
    {"module": "kdcube_ai_app.apps.chat.sdk.tools.web_tools", "alias": "web_tools", "use_sk": True},
    {"module": "kdcube_ai_app.apps.chat.sdk.tools.exec_tools", "alias": "exec_tools", "use_sk": True},
    # Bundle-local tools ("ref" = path relative to bundle root, works in Docker too)
    {"ref": "tools/my_tools.py", "alias": "my_tools", "use_sk": True},
]
# Tool IDs: web_tools.web_search, exec_tools.execute_code_python, my_tools.search

# Optional: per-tool runtime overrides
TOOL_RUNTIME = {
    "web_tools.web_search": "local",       # subprocess sandbox
    "exec_tools.execute_code_python": "docker",  # Docker container
}

{
  "ok": true,
  "error": null,
  "ret": {
    "artifact_type": "files",
    "files": [
      {
        "path": "outputs/report.pdf",
        "filename": "report.pdf",
        "mime": "application/pdf",
        "description": "Generated report"
      }
    ]
  }
}

# tools_descriptor.py
MCP_TOOL_SPECS = [
    {"server_id": "web_search", "alias": "web_search", "tools": ["web_search"]},
    {"server_id": "docs", "alias": "docs", "tools": ["*"]},  # all tools
    {"server_id": "stack", "alias": "stack", "tools": ["*"]},
]
# Tool IDs: mcp.docs.some_tool, mcp.stack.some_tool

# bundles.yaml config section — how to connect
config:
  mcp:
    services:
      mcpServers:
        docs:
          transport: http
          url: https://mcp.example.com
          auth:
            type: bearer
            secret: bundles.my-bundle.secrets.docs.token
        stack:
          transport: stdio
          command: npx
          args: ["mcp-remote", "mcp.stackoverflow.com"]

Artifact Path Families

Reusable SDK Integrations

SDK integrations are product-neutral building blocks that bundles import when they need external protocol support. They keep provider mechanics and transport details in the SDK while the bundle keeps user policy, routing, and workflow decisions.

See the dedicated SDK Integrations page for the current reusable integration package surface.

Skills System

Skills are reusable instruction sets that give agents specialized capabilities. A skill bundles a natural-language instruction (SKILL.md), tool references, and source references.

Built-in Platform Skills

Custom Bundle Skill

# skills/my_skill/SKILL.md
You are an expert in our product catalog.
When asked about products, use the `product_search` tool to find relevant items.
Always include pricing and availability.

# skills/my_skill/tools.yaml
tools:
  - id: product_search
    role: search
    why: Search the product catalog

# skills_descriptor.py
AGENTS_CONFIG = {
    "solver": {
        "enabled_skills": ["my_skill", "pdf-press", "url-gen"],
        "disabled_skills": []
    }
}

Creating a SKILL.md File

Each skill lives in its own folder under the bundle's skills/ directory. The required file is SKILL.md (or skill.yml), which contains YAML front-matter and a natural-language instruction body.

# skills/product/SKILL.md
---
name: "Product Catalog Expert"
id: "kdcube"
namespace: "product"
description: "Search and present product information"
version: "1.0"
tags: ["catalog", "products"]
when_to_use: "When the user asks about products, pricing, or availability"
imports: []
---

You are an expert in the product catalog.
When asked about products, use the `product_search` tool.
Always include pricing and availability in your response.

Optional companion files in the same folder:

• compact.md — a shorter instruction variant for context-constrained agents
• sources.yaml — sources injected into sources_pool when the skill loads (referenceable as so:sources_pool[...])
• tools.yaml — recommended tools for the skill, used by planners and UX

Skill Visibility Configuration

The skills_descriptor.py file controls which skills are visible to which agent consumers. It exposes two key variables:

# skills_descriptor.py
import pathlib

BUNDLE_ROOT = pathlib.Path(__file__).resolve().parent

# Points to the skills folder layout: <root>/<namespace>/<skill_id>/SKILL.md
CUSTOM_SKILLS_ROOT = BUNDLE_ROOT / "skills"

AGENTS_CONFIG = {
    # Allow-list for the ReAct decision agent
    "solver.react.decision.v2": {
        "enabled": ["product.kdcube"]
    },
    # Deny-list for a generator agent
    "answer.generator.strong": {
        "disabled": ["public.*"]
    },
}

Skill Loading and Resolution

The runtime auto-detects <bundle_root>/skills as the custom skills root when CUSTOM_SKILLS_ROOT is not set. Skills are loaded into the skill registry and resolved by fully qualified id (namespace.skill_id). Consumer agents reference skills via short-id tokens (SKx) or explicit sk:<id> references. When a skill is loaded with react.read("sk:<skill>"), its sources are merged into sources_pool and citation tokens are rewritten to match.

Best Practices for Skill Authoring

• Keep SKILL.md instructions focused — one skill per capability domain
• Use when_to_use front-matter to help the agent decide when to activate the skill
• Include tools.yaml to pair skills with the tools they need
• Use AGENTS_CONFIG to restrict skill visibility rather than deleting skill files — this keeps skills available for future consumers
• Test visibility filtering per consumer: a skill hidden from solver.react.decision.v2 is still visible to unfiltered consumers

Widgets, APIs, MCP & Custom UI

Bundles now expose a decorator-discovered interface. Widgets, REST APIs, bundle-served MCP endpoints, chat message handlers, and background job handlers are separate surfaces: widgets are UI entrypoints intended for the platform shell, APIs are programmatic operations reachable under the integrations routes, @mcp(...) exposes an MCP-native surface for external MCP clients, and @on_job receives ready work claimed by proc. A bundle may also define a custom main view and a dedicated message entrypoint.

Buildable React/Vite Widgets

New widget apps should be source folders declared per alias under ui.web_app_widgets. The descriptor should pass the loader output destination through the standard placeholder, and the widget build config must consume it as an environment value:

ui:
  web_app_widgets:
    task_memo_webapp:
      enabled: true
      src_folder: widgets/task_memo_webapp
      build_command: npm install --no-package-lock && OUTDIR=<VI_BUILD_DEST_ABSOLUTE_PATH> npm run build
    task_webapp:
      enabled: true
      src_folder: widgets/task_webapp
      build_command: npm install --no-package-lock && OUTDIR=<VI_BUILD_DEST_ABSOLUTE_PATH> npm run build

For Vite widgets, configure output from process.env.OUTDIR and use relative assets. Do not pass the destination path as vite build <path>.

export default defineConfig({
  base: './',
  build: {
    outDir: process.env.OUTDIR || 'dist',
    emptyOutDir: true,
  },
})

If runtime logs show vite build /.../.ui.build.tmp... or Vite reports UNRESOLVED_ENTRY for .ui.build.tmp.../index.html, the output directory leaked into Vite as a positional project/root argument. Fix the widget build contract or update to a platform runner that treats <VI_BUILD_DEST_ABSOLUTE_PATH> as an environment value. Do not manually copy built files into bundle storage.

Bundle Interface Decorators

Bundle identity can come from the registry entry or be declared explicitly with @bundle_id("my.bundle@version"). The loader uses the discovered bundle interface decorators as the HTTP, UI, message, and job contract. Use user_types=(...) for inferred platform user types such as anonymous, registered, paid, or privileged, and use roles=(...) for raw external auth roles such as kdcube:role:super-admin. user_types are threshold-based, not exact-match: the order is anonymous < registered < paid < privileged, so user_types=("registered",) means registered-or-higher, and user_types=("paid",) means paid-or-higher. If both user_types and roles are provided, both checks must pass. Add user_types_config and roles_config to APIs/widgets when Bundle Admin should override those defaults from bundle props. Add allowed_roles_config to @agentic_workflow when bundle-level listing visibility should be configurable. Resource enabled state is no longer a decorator argument for APIs or MCP; use bundle props/Admin resource overrides. That threshold rule applies to @api and @ui_widget when proc owns the route auth contract. @api(route="public") now has three explicit auth shapes: public_auth="none", built-in proc-side header_secret, and bundle-owned public_auth="bundle". @mcp is different again: proc does not enforce user_types, roles, or public_auth there; the bundle MCP app owns request authentication and authorization. @on_job is also different: it is not URL-addressable, must be async, and receives jobs already admitted to the background job stream.

Example: Declare widget, API, MCP, and UI entrypoints

from fastapi import HTTPException, Request
from kdcube_ai_app.apps.chat.sdk.config import get_secret_async
from kdcube_ai_app.infra.plugin.agentic_loader import agentic_workflow, bundle_id, api, mcp, ui_widget, ui_main, on_message

@agentic_workflow(name="my-bundle", version="1.0.0", priority=100)
@bundle_id("my.bundle@1.0.0")
class MyBundle(BaseEntrypointWithEconomics):

    @ui_widget(icon={"tailwind": "heroicons-outline:swatch"}, alias="dashboard", user_types=("registered", "privileged"))
    def dashboard_widget(self, **kwargs):
        return ["<div id='root'></div>"]

    @api(alias="refresh_dashboard", method="POST", user_types=("registered", "privileged"))
    def refresh_dashboard(self, **kwargs):
        return {"ok": True}

    @api(alias="telegram_webhook", method="POST", route="public", public_auth="bundle")
    async def telegram_webhook(self, request: Request, **kwargs):
        header_name = self.bundle_prop("telegram.webhook.auth.header_name", "X-Telegram-Bot-Api-Secret-Token")
        expected_token = await get_secret_async("b:telegram.webhook.auth.shared_token")
        if request.headers.get(header_name) != expected_token:
            raise HTTPException(status_code=401, detail=f"Missing or invalid {header_name}")
        return {"ok": True}

    @mcp(alias="tools", route="operations", transport="streamable-http")
    async def tools_mcp(self, request: Request):
        from mcp.server.fastmcp import FastMCP

        header_name = self.bundle_prop("mcp.inbound.auth.header_name", "X-Bundle-MCP-Token")
        expected_token = await get_secret_async("b:mcp.inbound.auth.shared_token")
        if request.headers.get(header_name) != expected_token:
            raise HTTPException(status_code=401, detail=f"Missing or invalid {header_name}")

        server = FastMCP("my-bundle")

        @server.tool()
        def ping() -> str:
            return "pong"

        return server

    @ui_main
    def main_view(self, **kwargs):
        return ["<div id='app'></div>"]

    @on_message
    async def run_message(self, **kwargs):
        return await self.run(**kwargs)

Integrations HTTP Surface

How to configure and call a bundle-authenticated public API hook

Use the same explicit split as MCP: the bundle defines the non-secret client contract in bundle props, stores verification material in bundle secrets, and checks the incoming request itself.

Server-side configuration

# bundles.yaml
bundles:
  version: "1"
  items:
    - id: "partner.tools@1-0"
      config:
        telegram:
          webhook:
            auth:
              header_name: "X-Telegram-Bot-Api-Secret-Token"

# bundles.secrets.yaml
bundles:
  version: "1"
  items:
    - id: "partner.tools@1-0"
      secrets:
        telegram:
          webhook:
            auth:
              shared_token: "replace-in-real-deployment"

What to share with the hook caller

• the public route: /api/integrations/bundles/{tenant}/{project}/{bundle_id}/public/telegram_webhook
• the header name from bundle props, for example X-Telegram-Bot-Api-Secret-Token
• the shared token provisioned in bundle secrets

Bundle-authenticated public API client call

curl -X POST \
  "http://localhost:5173/api/integrations/bundles/<tenant>/<project>/<bundle_id>/public/telegram_webhook" \
  -H "X-Telegram-Bot-Api-Secret-Token: <shared-token>" \
  -H "Content-Type: application/json" \
  -d '{"update_id":1}'

How to configure and call a bundle MCP endpoint

Use one explicit contract. The bundle defines the non-secret client contract in bundle props, stores verification material in bundle secrets, and checks the incoming headers itself before returning the FastMCP app.

Server-side configuration

# bundles.yaml
bundles:
  version: "1"
  items:
    - id: "versatile@2026-03-31-13-36"
      config:
        mcp:
          preferences:
            auth:
              header_name: "X-Versatile-Preferences-MCP-Token"

# bundles.secrets.yaml
bundles:
  version: "1"
  items:
    - id: "versatile@2026-03-31-13-36"
      secrets:
        mcp:
          preferences:
            auth:
              shared_token: "<rotate-me>"

Bundle code

@mcp(alias="preferences_tools", route="operations", transport="streamable-http")
async def preferences_tools_mcp(self, request: Request, **kwargs):
    header_name = self.bundle_prop(
        "mcp.preferences.auth.header_name",
        "X-Versatile-Preferences-MCP-Token",
    )
    expected_token = await get_secret_async("b:mcp.preferences.auth.shared_token")
    if request.headers.get(header_name) != expected_token:
        raise HTTPException(status_code=401, detail=f"Missing or invalid {header_name}")
    return build_preferences_mcp_app(...)

What to share with the MCP client

• the MCP route: /api/integrations/bundles/{tenant}/{project}/{bundle_id}/mcp/{alias}
• the header name from bundle props, for example X-Versatile-Preferences-MCP-Token
• the token provisioned in bundle secrets

Authenticated MCP client call

curl -X POST \
  "http://localhost:5173/api/integrations/bundles/demo-tenant/demo-project/versatile@2026-03-31-13-36/mcp/preferences_tools" \
  -H "X-Versatile-Preferences-MCP-Token: <shared-token>" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":"1","method":"tools/list"}'

Public MCP client call

curl -X POST \
  "http://localhost:5173/api/integrations/bundles/demo-tenant/demo-project/my.bundle/public/mcp/public_tools" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":"1","method":"tools/list"}'

Interface Manifest Discovery

Decorators on the bundle class are the source of truth for the bundle's HTTP, UI, message, and job contract. At load time the loader scans the entrypoint class for @api, @mcp, @ui_widget, @ui_main, @on_message, and @on_job decorators and builds a typed BundleInterfaceManifest:

# Internal manifest shape (built automatically by the loader)
BundleInterfaceManifest(
    bundle_id="versatile@2026-03-31-13-36",
    ui_widgets=(UIWidgetSpec(alias="preferences", icon={...}, user_types=(...), roles=(...)),),
    api_endpoints=(APIEndpointSpec(alias="preferences_exec_report", http_method="POST", route="operations", user_types=(...), roles=(...)),),
    mcp_endpoints=(MCPEndpointSpec(alias="tools", route="operations", transport="streamable-http"),),
    ui_main=UIMainSpec(method_name="main_ui"),
    on_message=OnMessageSpec(method_name="run"),
)

The manifest is returned by GET /api/integrations/bundles/{tenant}/{project}/{bundle_id} and drives all route resolution. Only decorated methods are remotely callable — there is no same-name fallback for undecorated methods.

MCP Tools vs Bundle-Served MCP

These are different surfaces and they solve opposite directions of integration.

Widget UI Model

Widget methods (@ui_widget) declare bundle widget UI surfaces. Source-folder widgets are built and served by KDCube; legacy widgets may return small HTML fragments directly. The widget fetch endpoint resolves the alias, checks user_types and raw roles visibility, and invokes the method. user_types use the same threshold rule here: anonymous < registered < paid < privileged. If the same widget must also be callable through the operations route (for legacy clients), decorate it with both @ui_widget and @api:

@api(alias="task-board", route="operations", user_types=("registered",))
@ui_widget(alias="task-board", icon={"tailwind": "heroicons-outline:check-badge"}, user_types=("registered",))
def task_board(self, **kwargs):
    return ["<div id='root'></div>"]

Widget and main UI browser code should follow the same runtime config bridge as the working platform widgets. It should send CONFIG_REQUEST to the parent frame when embedded by the standard KDCube shell, accept both CONN_RESPONSE and CONFIG_RESPONSE, and build bundle operation URLs from baseUrl, defaultTenant, defaultProject, and defaultAppBundleId. Do not hardcode tenant, project, or bundle id from the source folder. Widget load should stay read-only by default; use an explicit in-widget action when the widget needs a syncing operation. For platform widgets, the preferred POST /operations/{alias} body shape is { "data": { ... } }; proc also accepts a raw JSON object body and treats it as data for webhook-style integrations. Clients should unwrap the returned {alias} field from the integrations response envelope.

Use the SDK reference page for the exact widget/runtime config pattern and example: bundle-widget-integration-README.md.

Static File Serving for Custom UIs

Bundles that ship a custom frontend (typically a Vite/React SPA in ui/main/ for the main view or ui/widgets/<alias>/ for widgets) have their built assets served from a dedicated static route:

GET /api/integrations/static/{tenant}/{project}/{bundle_id}/{path}

The endpoint serves files from the bundle's stable bundle_storage_root()/ui/ subtree. Missing paths fall back to index.html for client-side routing. A <base> tag is injected into index.html so relative assets resolve correctly.

Main View Configuration

To define a custom main view, declare ui.main_view in your bundle's configuration property and mark a method with @ui_main:

@property
def configuration(self):
    return {
        "ui": {
            "main_view": {
                "src_folder": "ui/main",
                "build_command": "npm install && OUTDIR=<VI_BUILD_DEST_ABSOLUTE_PATH> npm run build",
            }
        }
    }

The built SPA communicates with the backend through the bundle operations endpoint and receives runtime config (base URL, auth tokens, tenant/project) via postMessage from the host frame. The UI is a normal platform client — if it needs bundle-originated events targeting one exact connected peer, it must propagate the connected peer id on REST requests per the client communication contract.

Registry vs. Interface Discovery

GET /api/admin/integrations/bundles returns the configured bundle registry entries — id, repo, ref, module, path, version, and related deployment metadata. The richer interface discovery surface lives on the per-bundle integrations endpoint above, where the runtime scans decorators and returns the current manifest.

Common Bundle Operations

Deploying Your Bundle

Option A: With the KDCube Platform

1. 1

   Push your bundle to Git

   git push origin v1.0.0

2. 2

   Add to bundles.yaml

   - id: "my-bundle@1-0"
     repo: "git@github.com:org/my-bundle.git"
     ref: "v1.0.0"
     module: "my_bundle.entrypoint"

3. 3

   Initialize secrets and apply

   kdcube init \
     --workdir ~/.kdcube/kdcube-runtime \
     --descriptors-location /path/to/descriptors \
     --set-secret services.openai.api_key "sk-..." \
     --set-secret services.anthropic.api_key "sk-ant-..." \
     --set-secret services.brave.api_key "..." \
     --set-secret services.git.http_token "github_pat_..." \
     --set-secret git.http_token "github_pat_..."
   
   kdcube info --workdir ~/.kdcube/kdcube-runtime/<tenant>__<project>

   The CLI writes these values into the staged active config/secrets.yaml, resolves descriptor placeholders such as tenant/project/domain where the descriptor set supports it, and then the runtime reads that staged copy.

4. 4

   Set as default bundle via the Admin Dashboard

   Open the AI Bundle Dashboard (/api/integrations/bundles/{tenant}/{project}/{bundle_id}/operations/ai_bundle). Your registered bundle appears in the list. Set it as the default_bundle_id for the tenant/project. The change is applied immediately via Redis — no restart needed.

Option B: Standalone (Without Platform)

Bundles can run outside the platform. The SDK is a plain Python package — build your own FastAPI app that imports and invokes it directly. Or build a custom Docker image that runs just your bundle with its own server. The platform's value is in hosting, auth, SSE, storage, economics, and UI — none of that is required for the core agent logic.

Bundle Git Auth

Fast Local Bundle Prototyping

KDCube supports a descriptor-driven local bundle workflow optimized for fast iteration. The intended loop is: initialize once from descriptors, edit the bundle locally under the mounted bundles root, then reload just that bundle without reinstalling the platform.

# one-time initialization
kdcube init \
  --workdir ~/.kdcube/kdcube-runtime \
  --descriptors-location /path/to/descriptors \
  --set-secret services.openai.api_key "sk-..." \
  --set-secret services.anthropic.api_key "sk-ant-..."

kdcube start --workdir ~/.kdcube/kdcube-runtime/<tenant>__<project>

# then during development
# edit files under assembly.paths.host_bundles_path
kdcube reload my.bundle@1.0.0 --workdir ~/.kdcube/kdcube-runtime/<tenant>__<project>

The important path rule is that the host bundle lives under the host bundles root declared in assembly.yaml, while bundles.yaml points to the container-visible path:

# assembly.yaml
paths:
  host_bundles_path: "/Users/you/dev/bundles"

# bundles.yaml
bundles:
  items:
    - id: "my.bundle@1.0.0"
      path: "/bundles/my.bundle"
      module: "entrypoint"

Use this flow for local code changes, descriptor-backed bundle config edits, and quick widget/API iteration. init stages the active descriptor set under the concrete runtime workdir. reload replays that active staged descriptor, clears bundle caches, and makes the next request load the updated bundle code.

Expose a CLI-Started Local Runtime with Ngrok

For Telegram webhooks, Telegram Mini Apps, Cognito callbacks, or any other external callback into a local KDCube runtime, run KDCube with the CLI first and expose the CLI web proxy port with ngrok. Do not expose proc separately.

kdcube start --workdir ~/.kdcube/kdcube-runtime/<tenant>__<project>

# use the port printed by kdcube start, commonly 5173 for local descriptors
ngrok http --host-header=rewrite 5173

The CLI-started Docker Compose stack already includes the KDCube web proxy, which routes /api/integrations/* to proc, /api/* and /sse/* to ingress, and browser routes to the frontend. After ngrok gives you https://<ngrok-domain>, use that single origin in CORS/Cognito callback settings and in bundle public integration URLs such as Telegram webhooks. If assembly.yaml changes, restart with kdcube stop and kdcube start; if bundle config/secrets change, use kdcube reload <bundle_id>.

Reference recipe: ngrok-README.md.

Bundle-Scoped @venv(...) Helpers

Bundles can mark dependency-heavy helper functions with @venv(...). The platform creates a cached per-bundle subprocess venv, overlays the runtime packages already present in proc, then installs the bundle's requirements.txt on top. The venv is rebuilt only when the requirements file changes.

from kdcube_ai_app.infra.plugin.agentic_loader import api, venv

@venv(requirements="requirements.txt", timeout_seconds=120)
def parse_external_document(payload: dict) -> dict:
    ...

class MyBundle(BaseEntrypoint):
    @api(alias="ingest_document", route="operations")
    async def ingest_document(self, **kwargs):
        result = parse_external_document(kwargs)
        await self.comm.event(
            type="bundle.ingest.completed",
            step="ingest_document",
            status="completed",
            title="Document processed",
            data={"pages": result.get("pages", 0)},
        )
        return result

Boundary rule: @venv(...) is for plain serialized inputs and outputs only. Keep communicator use, request context, DB pools, Redis clients, and other live proc-bound runtime objects outside the venv helper. If only requirements.txt changes, the next helper call rebuilds the cached venv lazily. If Python source changes, use the normal bundle reload path.

Bundle-Scheduled @cron(...) Jobs

Bundles can now declare proc-owned scheduled jobs directly in bundle code with @cron(...). This is the new native way to bind periodic custom bundle logic to the platform lifecycle instead of wiring an external scheduler for every bundle-specific routine.

from kdcube_ai_app.infra.plugin.agentic_loader import cron

class MyBundle(BaseEntrypoint):
    @cron(
        alias="rebuild_index",
        expr_config="routines.rebuild.cron",
        cron_expression="0 */6 * * *",
        span="instance",
    )
    async def rebuild_index(self):
        ...

The shipped contract is: @cron(alias=..., cron_expression=..., expr_config=..., span=...). Use cron_expression for an inline schedule or expr_config for a dot-separated config path such as apps.app1.routines.cron. If both are provided, expr_config wins. If the resolved config value is missing, blank, or disable, the job is inert and nothing is scheduled. span controls exclusivity across process, instance, or system.

A practical example is a scheduled task-tracker routine that materializes the next due queue and publishes an operational event for the UI:

class TaskTrackerBundle(BaseEntrypoint):
    @cron(alias="refresh-task-queue", cron_expression="0 6 * * *", span="system")
    async def refresh_task_queue(self):
        tasks = await self.rebuild_due_task_queue()
        await self.comm.event(
            type="bundle.tasks.queue_refreshed",
            step="refresh_task_queue",
            status="completed",
            title="Task queue refreshed",
            data={"items": len(tasks)},
        )

Background Job Stream and @on_job

For work that should not run inside a scheduler tick or widget request, enqueue a background job and handle it with @on_job. The producer creates the durable bundle-owned record first, then writes a ready-work envelope to Redis Streams. Proc claims jobs fairly across workers, builds a bundle runtime context, and invokes the bundle's async @on_job handler.

from kdcube_ai_app.infra.plugin.agentic_loader import cron, on_job

class TaskBundle(BaseEntrypoint):
    @cron(alias="due-scan", cron_expression="*/5 * * * *", span="system")
    async def due_scan(self):
        await self.tasks.enqueue_due_jobs()

    @on_job
    async def on_job(self, job: dict, **kwargs):
        del kwargs
        if job.get("work_kind") == "task.execution.due":
            return await self.tasks.run_execution(job["payload"]["execution_id"])
        return {"ok": False, "error": {"code": "unsupported_job"}}

@on_job is not a public route and not a widget operation. It should validate work_kind, load durable ids from payload, and update bundle-owned execution/result state. Until proc acknowledges the stream message, retry is possible.

Example Bundles

Documentation Reference

Coming Soon & Current Status

Here's the current state of platform capabilities and what's next on the roadmap: