Install¶

Install from the published wheel — never from the git repo

cortexbuild-core is not on PyPI. It is published as a wheel to the CortexBuild distribution index on every release tag. Always install from that index; installing from a git URL is not supported.

Prerequisites¶

Requirement	Notes
Python 3.11+	Declared minimum is `>=3.11`.
git	Needed for repo analysis (git-log mining) and git-URL onboarding.

Install¶

pip install --upgrade cortexbuild-core \
  --find-links https://dist.cortexbuild.dev/index.html

The index is a flat PEP-style find-links page listing every published wheel, so pip resolves the newest release automatically. Pin explicitly when you need a specific version:

pip install "cortexbuild-core==0.2.11" \
  --find-links https://dist.cortexbuild.dev/index.html

Extras are appended to the requirement as usual, e.g. "cortexbuild-core[graph,mcp]".

Offline / air-gapped install¶

CortexBuild is offline-by-default, so it also installs on a machine with no network access. This uses standard pip features — no CortexBuild-specific tooling.

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

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

The [graph] extra adds tree-sitter parsers for JavaScript, TypeScript, and Go. Python is analysed out of the box — Pass-2 graph extraction for Python uses the standard-library ast module and needs no extra. Without [graph], non-Python codebases still get the structural and debt passes.
[postgres] and [redis] are optional memory backends; drop them if you don't need persistence.

Optional extras¶

A few more extras unlock specific, opt-in capabilities:

[gemini] — native Google Gemini adapter (google-genai), in addition to the native Anthropic adapter and the built-in OpenAI-compatible adapter (any base_url). (No native AWS Bedrock or Google Vertex adapter ships today; those clouds are reachable through an OpenAI-compatible gateway — CortexBuild ships no native Bedrock/Vertex adapter.)
[server] — opt-in HTTP transport over the task/execution seam. It writes a task single-source-of-truth under .cortexbuild/tasks/; it does not run agents in-process. The seam itself needs no extra: cortexbuild task author|list|distribute|bind-check work on the default install, and only serving them over HTTP (cortexbuild server seam) needs [server].
[ide] — read-only file-reader over .cortexbuild/ for IDE surfaces.
[mcp] — read-only MCP server so an IDE/agent host (Claude, VS Code, Cursor, Codex) can consult CortexBuild over the standard protocol. Pulls no third-party dependency. See MCP & A2A integration.
[a2a] — read-only A2A Agent Card discovery surface (the agent↔agent complement to [mcp]). See the same guide.

Two analysis/insights commands are also worth knowing early — eval (offline, no-LLM, deterministic conformance scoring) and remediation (advisory, reversible, applied only under an explicit --approve gate, never auto-merged). See the CLI Reference for the full command set.

Verify the install¶

Confirm the CLI is on your path. --help needs no license, so this works before activation:

cortexbuild --help

Activate your license — before anything else¶

Every command except auth and the host-invoked hook requires a valid license, including version and info. Activate first:

cortexbuild auth activate --key <token>
cortexbuild auth status          # confirm the license verifies on THIS install

auth and hook are the only exemptions. auth is a necessity rather than a policy choice: it is how a machine becomes licensed, so gating it would make the license unobtainable. hook is invoked by your AI host, not by you, and it never refuses -- an unlicensed or offline hook call does nothing rather than erroring.

Now the install can be verified:

cortexbuild version
cortexbuild info

version prints the package/framework version; info prints environment and capability details. If both run without error, you're ready to onboard a repo.

License-gated usage¶

Every operational command is license-gated for registered usage.

Device activation (the trusted path — binds a seat, caches a signed licence):

cortexbuild auth activate --key cblk_<token> --url https://license.cortexbuild.dev

activate verifies the licence it just stored and exits non-zero if it does not verify on this install, so a broken activation is never reported as a success.

Confirm what you are actually entitled to:

cortexbuild auth status --json        # licensed, signing_available, inspected_repo_root
cortexbuild auth entitlements         # exits non-zero when the licence does not verify
cortexbuild auth logout

CI / non-interactive runners: install into the job as above, activate once (or set the token via the environment), and confirm with cortexbuild auth status --json. Put the venv's bin/Scripts directory on the job's PATH explicitly rather than relying on an interactive shell profile.

A licence belongs to a person, and is activated once in each repository checkout you work in. Licences are resolved from the checkout a command operates on — pass --repo-root <repo> (or --base for rollout) rather than relying on the working directory, so a multi-repo script reports a genuine per-repo result.

No extra is required for licensing¶

cryptography is a base dependency. It used to live in the optional [signing] extra, which meant the documented install could not verify a licence at all. cortexbuild-core[signing] still resolves as a no-op alias, so existing runbooks and pipelines that name it keep working.

Which mode am I using?¶

CortexBuild has two operating modes. Understanding which one applies to you determines whether you need an LLM API key:

Mode	When it applies	LLM key needed?
Rendered-into-host	You ran `cortexbuild render` and use the generated files inside Copilot, Claude Code, Codex CLI, or Cursor	No — the host tool supplies model access
Own orchestration engine	You invoke CortexBuild's orchestrator directly (e.g. `cortexbuild orchestrate run`, CI automation) with `CORTEXBUILD_LLM=1`	Yes — configure `.cortexbuild/llm-config.yaml` with your endpoint and set the key as an environment variable

I use GitHub Copilot in VS Code¶

No API key needed. Run cortexbuild render to write rules and agent personas into .github/copilot-instructions.md and .github/agents/. Copilot picks up the rendered instructions automatically and uses its own models.

I want CortexBuild to call an LLM directly¶

Set CORTEXBUILD_LLM=1 and create .cortexbuild/llm-config.yaml:

# Example: local Ollama (zero-egress, no consent needed)
base_url: "http://localhost:11434"
model: "llama3:8b"
locality: "local"
provider: "openai"   # Ollama speaks the OpenAI protocol

# Example: Anthropic Claude (cloud, full consent gate)
provider: "anthropic"
model: "claude-opus-4.7"
api_key_env: "ANTHROPIC_API_KEY"   # env var NAME, never the key value inline
locality: "cloud"

See How it works for the full provider and locality-gate reference.

Per-agent model tiers¶

When CORTEXBUILD_LLM=1 is active, CortexBuild's router assigns each agent to a model tier:

Tier	Agents	Why
`reasoning_heavy`	Planner, Critic, Security Compliance, PR Reviewer, Enterprise Orchestrator	Deep reasoning; these agents produce or gate high-consequence output
`balanced`	Builder, Tester Validator, Optimizer	Cost-quality balance; handle the bulk of task volume
`fast_cheap`	Explore	Read-only summarisation; latency and cost matter most

You can override per agent in .cortexbuild/llm-config.yaml by adding an agent_overrides block:

agent_overrides:
  builder:
    model: "claude-opus-4.7"   # override Builder to reasoning_heavy if needed

Edge cases: - Host-tool rendered mode — CortexBuild cannot choose the model, but it does ask. cortexbuild render writes each agent's tier into the model: field of the agent file the host reads, so on Claude Code the Planner renders as opus, the Critic as sonnet, the Builder as sonnet, and Explore as haiku. This is an instruction the host honours, not enforcement: a host that ignores the field, or a user who edits it, is not prevented. Copilot is deliberately left on default — its accepted model ids vary by plan and rollout, and a value it does not recognise is silently ignored, which would look like the feature working while doing nothing. - No eligible model available — If a requested tier has no configured model, CortexBuild fails closed: the task is paused and the user is notified. It will not silently fall back to a lower-tier model for a reasoning_heavy task (e.g., plan review or Critic gate) because a capability downgrade on a security-sensitive gate must be explicit. - Cross-model Critic — The Critic never runs on the same model as the Planner. Both need reasoning_heavy capability, so routing on tier alone would put them on the same model; the Critic therefore drops one tier deliberately. That is a capability trade for independence, and rule-critic-gate is explicit that it is the right one: "a single model reviewing its own reasoning shares its blind spots." PR Reviewer and Security Compliance review the Builder (a balanced agent) and so already differ from their author by tier. - Which reviewers get independence — the judgement-based gates: Critic, PR Reviewer, Security Compliance. Tester Validator and Optimizer share the Builder's tier by design: their checks are largely empirical (do the tests pass, what does the profiler say), and an empirical check does not inherit the author's blind spots the way a judgement does.

Cost impact. Adopting this raises spend. On a re-render, Planner, PR Reviewer, Security Compliance, and Enterprise Orchestrator request opus where they previously requested nothing. If that is wrong for you, edit recommended_model in your rule pack's registry.yaml, or pin a model: in the agent persona source — a value other than default is always preserved.

A hand-edit to a rendered agent file does not survive. .claude/agents/*.md and .github/agents/*.agent.md are fully CortexBuild-owned, so cortexbuild render overwrites them. To change an agent's model durably, set it in the persona source or in your org standards pack — not in the rendered output.

Next¶

→ Onboard Your Repo — the step-by-step walkthrough.