Distribution & Customer Onboarding¶

In plain English

CortexBuild ships as a Python CLI (cortexbuild-core) plus the .cortexbuild/ artefacts a customer commits to their own repo. This page lists the ways to deliver the engine and the recommended onboarding flow per customer type.

Install from the published wheel — never from git

cortexbuild-core is not on PyPI. Every release tag publishes a wheel to the CortexBuild distribution index, and that index is the only supported install channel for consumers. Installing from a git URL is not recommended: it builds an unreviewed working tree, bypasses the tag/version verification the release pipeline enforces, and requires credentials for a private repository. See Install.

Two things you distribute¶

When onboarding a customer (or yourself), you are delivering two distinct artefacts — don't blur them:

1. The engine¶

The cortexbuild-core CLI / Python package. Installed on the customer's machine or CI runner. It analyses, renders, evaluates, and gates — but it does not run agents itself or open PRs autonomously.

2. The rendered harness¶

The .cortexbuild/ rules, agents, analysis, and recurrence ledger plus the tool-surface files (.github/copilot-instructions.md, CLAUDE.md, AGENTS.md, .cursor/rules/) produced by cortexbuild init run + cortexbuild render. These are committed to the customer's own repo and consumed by their existing AI coding tools (GitHub Copilot, Claude Code, Codex, Cursor).

The engine produces the harness; the harness governs the AI tools. They are versioned and distributed independently.

Channel options for delivering the engine¶

Channel	Best for	Status	How
Published wheel index (`--find-links`)	Everyone — this is the supported channel	Available now	`pip install --upgrade cortexbuild-core --find-links <index>`
Editable source install (`git clone` + `pip install -e ".[…]"`)	Contributors only — people changing CortexBuild itself	Available now	Clone the repo, `pip install -e ".[graph]" --group dev`
Direct-from-git (`pip install "git+https://…@<tag>"`)	—	Not recommended — unreviewed tree, skips release verification, needs private-repo credentials	Use the published wheel index instead
Built wheel / sdist handoff (`python -m build` → `.whl`)	Air-gapped/manual delivery; internal artifact stores	Available now (manual)	Download the wheel from the index, hand it over
Private / enterprise package index (Artifactory, Nexus, GitHub Packages, private PyPI) + offline wheelhouse	Enterprises, regulated/air-gapped networks	Pattern available now (standard pip; no special tooling shipped)	Mirror the published wheel into your private index, or vendor a wheelhouse
PyPI / `pipx install cortexbuild-core`	Broad public, easiest install	Planned — not available yet	Will become an additional channel once published
Container / devcontainer (`cortexbuild-vm`, Daytona-based)	Reproducible sandboxed execution, cloud onboarding	Planned (Phase 1) — not shipped	Future image with toolchain pre-installed
Native AI-tool marketplaces (Claude plugin / Gemini extension)	Distributing the rendered harness to teams' AI tools	Limited / gated — `export` + `publish`, dry-run by default, opt-in, operator-gated	`cortexbuild export --target …` then `cortexbuild publish --target … --bundle-dir …` (real upload requires explicit opt-in + operator credentials)

Published wheel index (supported channel)¶

pip install --upgrade cortexbuild-core \
  --find-links https://cortexbuilddist40b9jc.blob.core.windows.net/dist/index.html
cortexbuild version   # verify

The index is a flat PEP-style find-links page listing every published wheel, so pip resolves the newest release automatically. Pin for reproducibility:

pip install "cortexbuild-core==0.2.4" \
  --find-links https://cortexbuilddist40b9jc.blob.core.windows.net/dist/index.html

Editable source install (contributors only)¶

Only for people changing CortexBuild itself — not a consumer channel.

git clone https://github.com/chiragmakvana/cortexbuild.git
cd cortexbuild
pip install -e ".[graph]" --group dev
cortexbuild version   # verify

Built wheel (available now — manual)¶

# Download the published wheel rather than rebuilding it, so the artefact the
# customer runs is byte-identical to the released one.
pip download --no-deps -d . cortexbuild-core \
  --find-links https://cortexbuilddist40b9jc.blob.core.windows.net/dist/index.html

# Hand the .whl to the customer
pip install ./cortexbuild_core-0.2.4-py3-none-any.whl

Air-gapped / offline wheelhouse (pattern available now)¶

This pattern uses standard pip features — no CortexBuild-specific tooling. It aligns with CortexBuild's offline-by-default posture.

# On a network-connected machine: download everything into a wheelhouse
pip download -d ./wheelhouse "cortexbuild-core[graph]" \
  --find-links https://cortexbuilddist40b9jc.blob.core.windows.net/dist/index.html

# Transfer the wheelhouse directory to the air-gapped machine, then:
pip install --no-index --find-links=./wheelhouse cortexbuild-core[graph]

Customer onboarding — end to end¶

A numbered runbook for onboarding a single new customer:

Choose a delivery channel from the table above.
Install the engine → see Install.
Configure a model if you want LLM features (optional) → see Configure Your Model.
Onboard the repo — analyse the codebase and generate the rule pack:
```
cortexbuild init run .
```
→ see Onboard Your Repo.
Review & curate the generated rules in .cortexbuild/rules/.
Render into the customer's AI tools:
```
cortexbuild render
```

Wire the drift gate into CI:

cortexbuild render --check   # exits 1 if rendered files are stale

Start the recurrence ledger and iterate:
```
cortexbuild ledger init
```
(Optional, gated) Publish the rendered harness artefacts to AI-tool marketplaces — requires explicit opt-in and operator credentials; dry-run by default.

Which path should I pick?¶

Customer type	Recommended channel
Individual developer / evaluator	Editable source install now; PyPI when available (v0.1.0).
Single team	Editable or direct-from-git install; pin a tag; commit `.cortexbuild/` to the team repo.
Enterprise / regulated / air-gapped	Private package index or offline wheelhouse; offline-by-default; review rules before render.
Teams who want it inside their AI tools	Render + (gated) marketplace publish for the harness artefacts.

Licensing & support¶

The cortexbuild-core engine is Apache-2.0 (open source). A hosted control plane / managed offering is future and planned — not available today. Onboarding is currently self-serve via this documentation.