KDCube
← Engineering blog
2026-07-07 · Deep

Set Up And Operate KDCube

kdcube-cli bootstrap descriptors operations two doors, one loop

Two ways into a running KDCube — a one-command clean bootstrap that stages a configured ecosystem, and a descriptor set that reproduces an environment as a reviewed artifact — and the one operating loop you live in afterwards.

Standing a platform up is a one-time event; operating it is every day after. KDCube keeps both honest with one rule: the staged descriptors under the runtime's config/ are the authority — installs produce them, every later change flows through them, and nothing you edit there is ever silently overwritten.

TWO DOORS IN, ONE LOOP AFTER DOOR ONE — CLEAN BOOTSTRAP kdcube init base complectation, configured first-run checklist DOOR TWO — DESCRIPTOR SET (CI/CD) config export align init --descriptors-location environment as a reviewed artifact THE OPERATING LOOP platform code → refresh staged edits → refresh app descriptors → apply --reload one app → reload The staged descriptors are the runtime authority; every loop preserves them.
Two doors in, one loop after.

Door one: the clean bootstrap

On a fresh machine, one init produces a working ecosystem:

kdcube init --tenant acme --project main --build
kdcube start
  • The base complectation arrives configured: Connection Hub (identity, consent, delegated credentials), KDCube Services (managed MCP + named services), User Memories, and the workspace showcase — a pure config overlay on apps shipped in the image.
  • Identity works out of the box: the bundle-session flavor — Google sign-in validated by the workspace app, KDCube session issued by Connection Hub. The first admin is bootstrapped by email (KDCUBE_ADMIN_EMAIL).
  • Environment specifics are explicit placeholders, and init ends with a first-run checklist of what is still unfilled. A feature backed by an unfilled slot waits; everything else runs. Loud and locatable beats mysterious.
  • Nothing is locked in: every staged value remains editable in the runtime descriptors or the AI Bundles dashboard.

See: clean install recipe

Door two: descriptors as the environment artifact

Six YAML files describe an environment completely — topology, gateway policy, platform secrets, app registry and config, app secrets, economics. That makes an environment an artifact you can export, review, version, align, and reproduce:

kdcube config export --out-dir "$OUT_DIR" --include-platform-descriptors
# review + align to the target machine
kdcube init --descriptors-location "$OUT_DIR" --tenant acme --project staging --build
  • Export resolves reality back to portable form: runtime bundle paths become host paths; git-backed apps keep repo/ref/subdir.
  • Aligning is a real step, with a checklist: host paths, infra topology (bundled vs host-managed), and the local-bundle symlink audit — the classic from-scratch breaker.
  • This is the CI/CD story: dev exports, review edits, staging inits — the same shape a pipeline runs. Reseeding an existing runtime is config import, never a re-init.

See: install from descriptors recipe

One loop after

Everything post-install is four change loops on one runtime:

  • Platform code changed → kdcube refresh --path "$REPO" --build (or --upstream/--release to move to a git source). Descriptors and data volumes are preserved.
  • Staged config edited by hand → kdcube refresh; the edits survive.
  • App descriptors are the source of truth → kdcube bundle config apply --descriptors-location … --reload — no Docker restart.
  • One app changed → kdcube reload <app-id>, the fast path.

And verification that tells the truth: kdcube info reports process state; the done-signal is a real HTTP 200 on the chat UI plus a proc-log scan for widget:... build done — a bundle build can fail quietly behind a green info.

See: operate a runtime recipe · CLI reference

Read more