Configuration

Config Hierarchy

assembly.yaml

release_name: "prod-2026-03-21"
platform:
  repo: "kdcube-ai-app"
  ref: "v0.3.2"
secrets:
  provider: "secrets-service"   # secrets-service | secrets-file | aws-sm
auth:
  type: "delegated"   # simple | cognito | delegated
domain: "chat.example.com"
storage:
  workspace:
    type: "git"              # custom | git
    repo: "https://github.com/org/react-workspace.git"
  claude_code_session:
    type: "git"              # local | git
    repo: "https://github.com/org/claude-session-store.git"
paths:
  host_bundles_path: "/Users/you/dev/bundles"       # local path bundle root mounted into /bundles
  host_git_bundles_path: "/Users/you/.kdcube/git-bundles" # optional dedicated git bundle cache mounted into /git-bundles

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

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

For local prototyping, a bundle entry can point at a mounted local path instead of a git repo. In that case the path in bundles.yaml must be the container-visible path under /bundles, not the raw host path.

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

Bundle Secrets — Provider Backed

Secret resolution is provider-based. With secrets.provider: secrets-service, secrets are provisioned via the Admin UI or injected into the local kdcube-secrets sidecar and resolved in-memory at runtime. With secrets.provider: secrets-file, runtime reads and writes secrets.yaml and bundles.secrets.yaml through the configured storage backend, so those files are the source of truth. With aws-sm, deployment-scoped secrets live in grouped AWS Secrets Manager documents such as .../bundles/<bundle_id>/secrets; Redis is only cache, not authority.

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-..."  # sidecar mode: injected by CLI / file mode: stored in descriptor backend
          webhook_url: "env:MY_WEBHOOK_URL"  # or env: reference

Use bundles.secrets.yaml for bundle-scoped deployment secrets. Use secrets.yaml for platform/service secrets. In secrets-file mode, those files remain durable runtime inputs. In aws-sm mode they are the portable export/import shape, while the live authority is the grouped secret documents in AWS Secrets Manager.

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
bundle_api_key = get_secret("b:my_service.api_key")               # current bundle
platform_api_key = get_secret("services.openai.api_key")          # same as a:services.openai.api_key

from kdcube_ai_app.apps.chat.sdk.config import get_user_prop, set_user_prop
prefs = get_user_prop("preferences.theme", "light")         # per user + current bundle
set_user_prop("preferences.theme", "dark")                 # persisted in Postgres

from kdcube_ai_app.apps.chat.sdk.config import get_plain
host_bundles = get_plain("paths.host_bundles_path")            # assembly.yaml
git_bundle_cache = get_plain("paths.host_git_bundles_path")  # assembly.yaml (optional)
default_bundle = get_plain("b:bundles.default_bundle_id")     # bundles.yaml

get_plain(...) / read_plain(...) reads non-secret descriptor data by dot path. Use no prefix or a: for assembly.yaml, and use b: for bundles.yaml.

get_secret("b:...") means "the current bundle". The runtime resolves that bundle id from the bound request or bundle context. Outside a bound bundle invocation, use the fully qualified secret path instead of b:.

This is the descriptor-backed complement to get_secret(...): use get_secret(...) for provider-managed secrets, use get_plain(...) for mounted descriptor values, and use get_user_prop(...) for per-user non-secret bundle state.

Descriptor-Driven Local Bundle Development

The fastest local development path is descriptor-driven. Put assembly.yaml, gateway.yaml, secrets.yaml, and usually bundles.yaml in one descriptor folder. For the fully non-interactive install path, use secrets.provider: secrets-file.

# use the released ref from assembly.platform.ref
kdcube --descriptors-location /path/to/descriptors --build

# override assembly.platform.ref with the latest released platform
kdcube --descriptors-location /path/to/descriptors --latest --build

# build from the latest upstream repo state instead of a release
kdcube --descriptors-location /path/to/descriptors --upstream --build

# override assembly.platform.ref with a specific released ref
kdcube --descriptors-location /path/to/descriptors --release 2026.4.11.012 --build

Choose exactly one source selector:

• --upstream with --build for the latest upstream repo state
• --latest for the latest released platform ref
• --release <ref> for a specific released ref
• otherwise assembly.yaml -> platform.ref

Without --build, --latest and --release select release images instead of the source checkout version. --upstream is the source-build path for the current upstream repo state.

With that setup:

• assembly.yaml declares paths.host_bundles_path for local path bundles on the host
• assembly.yaml can also declare paths.host_git_bundles_path for a dedicated git bundle cache
• the runtime mounts those host folders into proc as /bundles and optionally /git-bundles
• bundles.yaml points local bundle entries at /bundles/<bundle-dir>
• git bundle entries are cloned under /git-bundles when a dedicated git cache root is configured

Then the edit/test loop is:

# edit the local bundle under paths.host_bundles_path
kdcube --workdir ~/.kdcube/kdcube-runtime --bundle-reload my.bundle@1.0.0

This reload command replays the active descriptor and clears the bundle cache so the next request picks up the updated code and descriptor-backed config.

Canonical descriptor references:

• assembly.yaml
• bundles.yaml
• bundles.secrets.yaml
• gateway.yaml
• secrets.yaml

When secrets.provider: aws-sm is active, you can export the current effective live bundle descriptor state into portable files with:

kdcube --export-live-bundles \
  --tenant allcisodev \
  --project cisoteria-ciso-dev \
  --aws-region eu-west-1 \
  --out-dir /tmp/kdcube-export

This reads the live grouped AWS documents for bundle descriptors and bundle secrets and writes fresh bundles.yaml and bundles.secrets.yaml snapshots.

Configuration Resolution Order

User-scoped bundle props are separate from that precedence chain. They are not part of bundles.yaml; they are stored per user and per bundle in Postgres and should be read with get_user_prop(...).

Reserved Property Paths

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