Quick Start

  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 --prompt-secrets
kdcube start

    kdcube init stages descriptors and env files under a namespaced workdir, then kdcube start launches Docker Compose. The example prompts for common local secrets such as OpenAI, Anthropic, and a Git HTTPS token; those values are written to the staged config/secrets.yaml, not to .env files. For a full guided configuration flow, use kdcube init -i. For prepared descriptors, kdcube init --descriptors-location /path/to/descriptors --latest uses the latest released platform, kdcube init --descriptors-location /path/to/descriptors --release 2026.4.11.012 pins a specific release, and kdcube init --descriptors-location /path/to/descriptors --build --upstream builds from the latest upstream repo state.

    KDCube CLI setup wizard
  3. 3

    Open the UI

    http://localhost:${KDCUBE_UI_PORT}/platform/chat

    You're now running a full KDCube stack with the built-in example bundle set.

  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/claude-plugins
/plugin install kdcube-docs@kdcube
/reload-plugins

    The plugin auto-registers the kdcube-docs MCP server and ships two slash commands: /kdcube-docs:search for citation-backed doc lookups, /kdcube-docs:scaffold for bundle skeletons. When the underlying canonical URL changes, the marketplace version bumps and Claude Code picks it up on the next /reload-plugins. Source: github.com/kdcube/claude-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.

    Codex CLI consumes the same mcp.json shape as Cursor. The exact file location varies by version — check codex config show or the Codex CLI docs. Configuration body:

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

    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"
    }
  }
}

Setup Flow

CLI setup flow diagram
Setup Flow Sequential steps of KDCube CLI setup from descriptor staging through Docker Compose startup Descriptors ×5 assembly · secrets gateway · bundles kdcube init stage runtime Workdir + Env ~/.kdcube/kdcube-runtime kdcube start Docker Compose Platform Live ✓ ready for bundles

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                   # Bundle definitions        ← edit this
│  ├─ bundles.secrets.yaml           # Bundle-level local secrets
│  ├─ gateway.yaml                   # Rate limits, circuit breaker
│  ├─ 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-bundle persistent storage
│  ├─ bundles/                       # Local path bundle root
│  ├─ managed-bundles/               # Git-resolved and example bundles
│  ├─ 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. Bundle-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

Vanity MCP URL — how it's wired (for operators)

The canonical KDCube MCP URL encodes the full bundle path, which makes it long and version-bound. The vanity URL https://kdcube.tech/mcp/docs 308-redirects to the canonical URL via a CloudFront Function on the apex distribution, so the endpoint stays stable as the underlying bundle is re-versioned. Source + deploy scripts: scripts/prod-infra/ on the website repo. If you're running KDCube on your own domain, three setup paths in order of increasing operational complexity:

  1. Bundle-side public route (cleanest). Add an @api(route='public', alias='mcp-docs') handler on the docs bundle that re-exposes the MCP server under a stable alias. The route lives at the runtime host (https://<runtime-host>/api/integrations/bundles/<tenant>/<project>/<bundle>/public/mcp-docs), so MCP traffic stays on one origin. Survives bundle version bumps because the alias is decoupled from the bundle ID.

  2. CloudFront Function on the marketing host (what kdcube.tech uses). A viewer-request function issues a 308 for /mcp/* paths:

    function handler(event) {
  var uri = event.request.uri;
  if (uri === '/mcp' || uri === '/mcp/' || uri === '/mcp/doc' || uri === '/mcp/docs') {
    return {
      statusCode: 308,
      statusDescription: 'Permanent Redirect',
      headers: { location: { value: 'https://<runtime-host>/api/integrations/bundles/<tenant>/<project>/<bundle>/public/mcp/<server>' } }
    };
  }
  return event.request;
}

    308 is method-preserving — MCP clients POST JSON-RPC over streamable-http and need the method preserved across the redirect (301/302 may downgrade to GET in some clients). Verify with curl -ILX POST https://<your-domain>/mcp/docs. Cross-origin handshake to a different runtime host works for HTTP clients but browser-based MCP debuggers may need CORS configured on the runtime side.

  3. S3 redirect object (simplest if you're already on S3+CloudFront). Upload a zero-byte object at mcp/docs/index.html with the header x-amz-website-redirect-location set to the canonical URL. Requires the bucket to be in static-website-hosting mode and the CloudFront origin pointing at the website endpoint (not the REST API endpoint). Returns HTTP 301 — works for clients that follow 301 across POST, but 308 (Option 2) is safer for MCP.

Option 1 is closest to how production traffic should flow: MCP stays on a single host, no cross-origin redirect, and the alias survives bundle version bumps. Option 2 (what kdcube.tech itself uses) is fine for marketing-host vanity but introduces a cross-origin redirect to the runtime. Option 3 is the cheapest if you don't want to manage a CloudFront Function, but the 301 doesn't preserve POST method on all clients.