Quick Start

Run the local platform first, then choose your starting point: use the ready workspace app, bring an existing agent behind KDCube's serving seam, or author a new app from the SDK. You do not need to adopt chat, ReAct, UI, or every platform service at once.

  1. 1

    Install the KDCube CLI

    # Recommended: pipx (isolated installation)
pipx install kdcube-cli

# Or with pip
pip install kdcube-cli

    Prerequisites: Python 3.11+, Docker, Git.

  2. 2

    Initialize and start the runtime

    kdcube init  --tenant acme --project staging --prompt-secrets
kdcube start --tenant acme --project staging

    init runs the setup wizard. It asks for a sign-in method: application-hosted Google login is preselected and needs a Google Web application OAuth client id — public, no client secret, with your runtime's UI origin authorized as a JavaScript origin. Have it ready before you start, or pick simple for a development/demo runtime with no external identity. SimpleIDP is not a production identity posture. Do not proceed app-hosted with a placeholder id: the result is a runtime you cannot sign into.

    Non-interactive form of the same choice:

    kdcube init --tenant acme --project staging \
  --auth-type bundle --client-id "<google-web-oauth-client-id>" \
  --bootstrap-admin-email you@example.com   # optional: first super-admin

    init creates the tenant/project workdir, stages descriptors and source, and optionally builds images. It is a first-time operation for that workdir; it ends with a first-run checklist of unfilled secret slots — features backed by an unfilled slot stay inactive, everything else runs. Fill them later in config/bundles.yaml / bundles.secrets.yaml or the AI Bundles dashboard. start launches the local Docker Compose runtime. Prompted secrets go to the staged secret descriptor, not a Compose .env file.

    Updating later — platform via kdcube refresh, apps via kdcube bundle reload — is a separate flow: see Update below. Your staged descriptors are preserved.

    KDCube CLI setup wizard
  3. 3

    Open the UI

    http://localhost:5173/platform/chat

    5173 is the CLI/default UI port; use the value selected during setup if you overrode it.

    You're now running a full KDCube stack with the built-in reference apps. Start with workspace for the ready assistant and scene, or inspect ported-langgraph-agents@2026-07-13 for the existing-agent serving pattern.

    Use the ready app

    Configure models, tools, skills, integrations, and execution policy; keep the SDK chat and workspace surfaces.

    Bring your agent

    Keep LangGraph, CrewAI, Claude Agent SDK, or custom logic. Add the thin execution and streaming seam; rebuild stateful graphs per turn.

    Build an app

    Expose only the API, MCP, jobs, named services, UI, website, chat, or agent surfaces your product actually needs.

  4. 4

    Connect your AI assistant (optional)

    Client setup — pick your client

    Three slash commands in any Claude Code session — no config-file editing:

    /plugin marketplace add https://github.com/kdcube/agent-plugins
/plugin install kdcube@kdcube
/reload-plugins

    The current plugin packages runtime bootstrap (/kdcube:runtime-init), app scaffolding (/kdcube:bundle-new), configuration, testing, release, operator workflows, and an offline Tier-1 documentation pack. Source: github.com/kdcube/agent-plugins.

    Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

    {
  "mcpServers": {
    "kdcube-docs": {
      "type": "streamable-http",
      "url": "https://kdcube.tech/mcp/docs"
    }
  }
}

    Restart Claude Desktop after editing. Tools then appear under the kdcube-docs namespace.

    Edit ~/.cursor/mcp.json:

    {
  "mcpServers": {
    "kdcube-docs": {
      "url": "https://kdcube.tech/mcp/docs"
    }
  }
}

    Reload Cursor (Cmd/Ctrl+Shift+P → "Reload Window") after editing.

    Add the streamable HTTP server with the Codex CLI:

    codex mcp add kdcube-docs --url https://kdcube.tech/mcp/docs
codex mcp list

    Gemini CLI uses the standard mcp.json shape. Refer to Gemini CLI's configuration docs for the file location for your install. Configuration body:

    {
  "mcpServers": {
    "kdcube-docs": {
      "url": "https://kdcube.tech/mcp/docs"
    }
  }
}

Install

CLI setup flow diagram
Install Install flow: six descriptors, kdcube init once per tenant and project, a namespaced workdir, kdcube start with Docker Compose, platform live. INSTALL · KDCUBE CLI DESCRIPTORS IN · PLATFORM LIVE Descriptors ×6 assembly · bundles gateway · economics secrets · bundles.secrets kdcube init --tenant --project once Workdir + Env ~/.kdcube/kdcube-runtime/ <tenant>__<project> kdcube start Docker Compose Platform Live ✓ ready for apps

Workdir Layout

~/.kdcube/kdcube-runtime/<tenant>__<project>/
├─ config/
│  ├─ .env                           # Base Docker Compose env
│  ├─ .env.ingress                   # Ingress env
│  ├─ .env.proc                      # Processor env
│  ├─ .env.metrics                   # Metrics env
│  ├─ .env.postgres.setup            # Local Postgres setup env
│  ├─ assembly.yaml                  # Platform version, auth type, domain
│  ├─ secrets.yaml                   # Deployment-wide local secrets
│  ├─ bundles.yaml                   # Staged local app authority; edit or use Admin/CLI
│  ├─ bundles.secrets.yaml           # App-level local secrets
│  ├─ gateway.yaml                   # Rate limits, circuit breaker
│  ├─ economics.yaml                 # Spend plans, budgets, user limits
│  ├─ install-meta.json              # CLI install metadata
│  ├─ frontend.config.<mode>.json    # Static /config.json fallback
│  ├─ nginx_proxy*.conf              # Nginx reverse proxy
│  └─ nginx_ui.conf                  # Nginx UI config
├─ data/
│  ├─ bundle-storage/                # Per-app filesystem storage
│  ├─ bundles/                       # Local path app root
│  ├─ managed-bundles/               # Git-resolved and example apps
│  ├─ exec-workspace/                # Code execution sandboxes
│  ├─ kdcube-storage/                # Conversations, artifacts, files
│  ├─ nginx/                         # Nginx runtime data
│  ├─ postgres/                      # Database volume
│  └─ redis/                         # Redis persistence
└─ logs/                             # Service logs

Deployment-wide secrets supplied during local init go to config/secrets.yaml. App-level secrets live in config/bundles.secrets.yaml. They are not written to Compose .env files.

Frontend browser config is public runtime config. It can be declared in assembly.yaml under frontend.config; the CLI renders the static fallback and ingress serves the same shape from /api/cp-frontend-config.

Full CLI reference: kdcube_cli/README.md

Update

Updates never regenerate your staged descriptors: everything under config/ — assembly.yaml, bundles.yaml, gateway.yaml, economics.yaml, secrets.yaml, bundles.secrets.yaml — is preserved. init is a first-time operation; updating goes through two separate paths depending on what changed.

Update flow: platform refresh and app reload, descriptors preserved
Update Update flow. The runtime workdir's staged descriptors are preserved. Platform or SDK changes go through kdcube refresh with a source selector and build, which updates repo and images and restarts the stack itself. App changes go through kdcube bundle reload or bundle config apply with reload, hot, with no restart. Both paths end with the platform live. UPDATE · KDCUBE CLI DESCRIPTORS PRESERVED · NOT REGENERATED existing runtime <tenant>__<project> config/*.yaml kept as-is PLATFORM / SDK CHANGED kdcube refresh … --build --latest · --release <ref> · --path <repo> updates repo/ + images · restarts the stack itself APP CHANGED kdcube bundle reload <app_id> or bundle config apply --reload · hot · no restart Live ✓ same descriptors · new code REFRESH STOP/STARTS ITSELF · INIT IS FIRST-TIME ONLY · AUTH CHANGES VIA CONFIG APPLY 
# platform / SDK update — pick exactly one source
kdcube refresh --tenant acme --project staging --latest --build
kdcube refresh --tenant acme --project staging --release <ref> --build
kdcube refresh --tenant acme --project staging --path /path/to/kdcube-ai-app --build

# app updates — hot, no restart
kdcube bundle reload <app_id>
kdcube bundle config apply --descriptors-location <dir> --reload

refresh performs the stop/start cycle itself — do not wrap it in a separate kdcube stop/start. To change the authentication method on an initialized runtime, use kdcube config apply rather than re-running init.

Stable MCP URLs (operator note)

The canonical app MCP route includes tenant, project, app ID, and endpoint alias. If clients need a shorter stable URL, prefer an app-owned stable public alias on the runtime host. A reverse proxy or CDN can alternatively issue a method-preserving 308 to the canonical streamable-HTTP route.

The redirect layer is routing only: it does not replace the MCP endpoint's declared app-owned or Connection Hub managed authentication. Avoid 301/302 redirects for JSON-RPC POST clients because some clients may change the method.

Two ways to give MCP clients a short stable URL
Stable MCP URLs Two ways to a short URL: A, preferred, an app-owned stable alias on the runtime host; B, an edge redirect layer answering a method-preserving 308 to the canonical MCP route. Routing only - the endpoint's own authentication still applies. STABLE MCP URLS TWO WAYS TO A SHORT URL MCP client Claude Code · any YOUR RUNTIME HOST stable alias app-owned · preferred canonical MCP route tenant · project · app · alias A · PREFERRED · CALL THE ALIAS B · REDIRECT LAYER edge redirect CDN / proxy · 308 method-kept ROUTING ONLY · THE ENDPOINT’S AUTH STILL APPLIES · NO 301/302 FOR JSON-RPC POST

KDCube's own production edge follows shape B, and you can watch it work: curl -I "https://kdcube.tech/mcp/docs" answers with a method-preserving 308 and the canonical route in Location.