Configuration

Config Hierarchy

assembly.yaml

release_name: "prod-2026-03-21"
platform:
  repo: "kdcube-ai-app"
  ref: "v0.3.2"
auth:
  type: "delegated"   # simple | cognito | delegated
domain: "chat.example.com"

bundles.yaml

bundles:
  version: "1"
  default_bundle_id: "versatile@2026-03-31-13-36"
  items:
    - id: "versatile@2026-03-31-13-36"
      repo: "git@github.com:org/repo.git"
      ref: "bundle-v2026.03.21"
      module: "versatile@2026-03-31-13-36.entrypoint"
      config:
        model_id: "gpt-4o-mini"
        role_models:
          solver.react.v2.decision.v2.strong:
            provider: "anthropic"
            model: "claude-sonnet-4-6"

Platform-Reserved Config Keys

Key	Description
`role_models`	Override LLM per role. Maps logical agent roles to concrete provider + model combinations.
`embedding`	Embedding provider + model for RAG and vector search in knowledge spaces.
`economics.reservation_amount_dollars`	Cost reserved before execution begins. Default 2.0 USD. Committed on completion, released on failure.
`execution.runtime`	Code exec backend: `docker` (default, fast) or `fargate` (batch/async workloads only).
`mcp.services`	MCP connector config per bundle. Matched by `server_id` in `MCP_TOOL_SPECS`.

Configuration & Secrets

bundles.yaml — Your Bundle Definition

bundles:
  version: "1"
  default_bundle_id: "my-bundle@1-0"
  items:
    - id: "my-bundle@1-0"
      name: "My Bundle"
      repo: "git@github.com:org/my-bundle-repo.git"   # optional git source
      ref: "v1.0.0"
      subdir: "src/my_bundle"
      module: "my-bundle@1-0.entrypoint"
      config:
        embedding:
          provider: "openai"
          model: "text-embedding-3-small"
        role_models:
          solver.react.v2.decision.v2.strong:
            provider: "anthropic"
            model: "claude-sonnet-4-6"
        economics:
          reservation_amount_dollars: 2.0
        execution:
          runtime:
            mode: "docker"   # docker is default — see Exec Runtime section
            enabled: true

Bundle Secrets — Managed by kdcube-secrets (Never on Disk)

Bundle secrets are provisioned via the Admin UI or injected into kdcube-secrets at setup time. They are resolved in-memory at runtime and are never written to disk. The bundles.secrets.yaml format below is only used as a transient CLI input during initial provisioning — it is not stored in the workdir.

bundles:
  version: "1"
  items:
    - id: "my-bundle@1-0"
      secrets:
        openai:
          api_key: null          # null = resolve from env OPENAI_API_KEY
        my_service:
          api_key: "sk-live-..."  # inline value — consumed by CLI, not stored
          webhook_url: "env:MY_WEBHOOK_URL"  # or env: reference

Reading Config & Secrets in Code

value = self.bundle_prop("some.nested.key")   # dot-path navigation
all_props = self.bundle_props                    # full merged dict

from kdcube_ai_app.apps.chat.sdk.config import get_secret
api_key = get_secret("bundles.my-bundle@1-0.secrets.my_service.api_key")

Configuration Resolution Order

Priority	Source	How
1 (highest)	Admin UI / runtime overrides	Stored in Redis, applied per tenant/project
2	`bundles.yaml` config section	Loaded at startup, seeded into Redis
3 (lowest)	`entrypoint.configuration`	Bundle code defaults

Reserved Property Paths

Path	Purpose
`role_models`	Maps logical agent roles → concrete LLM (provider + model)
`embedding`	Embedding provider/model for RAG and vector search
`economics.reservation_amount_dollars`	Pre-run cost reservation floor (default 2.0)
`execution.runtime`	Code exec configuration (Docker, Fargate)
`knowledge`	Knowledge space repo/paths configuration
`ui.main_view`	Reserved UI build/serve block for bundle main-view override assets
`subsystems`	Bundle-declared UI/helper subsystems and dashboard resources

ui.main_view is the current reserved UI config surface. It is used by bundles such as versatile to describe how a standalone main-view frontend should be built or served. Decorator-discovered surfaces such as widgets, APIs, ui_main, and on_message are scanned from the bundle class rather than stored in props.

config:
  ui:
    main_view:
      src_folder: "ui-src"
      build_command: "npm install && OUTDIR=<VI_BUILD_DEST_ABSOLUTE_PATH> npm run build"

See full config docs: bundle-configuration-README.md