Skip to content

Set up CortexBuild in your repository (licensed client)

This is the complete, copy-pasteable setup for a customer who has a license token. Five minutes end to end.

Your CortexBuild contact will give you three values:

Value Placeholder used below Example
License token <LICENSE_TOKEN> cblk_…
License service URL <LICENSE_URL> https://license.<your-domain>
Package index URL <INDEX_URL> https://<dist-host>/dist/index.html

CortexBuild-hosted service (managed plan)

If you're on the CortexBuild-managed plan, you don't need to wait for these values — use the current hosted endpoints directly:

Value Current endpoint
License service URL (<LICENSE_URL>) https://cortexbuild-license.kindfield-41e3ed8e.centralus.azurecontainerapps.io
Package index URL (<INDEX_URL>) https://cortexbuilddist40b9jc.blob.core.windows.net/dist/index.html

You still supply your own license token (<LICENSE_TOKEN>, cblk_…) — that is the one secret only your CortexBuild administrator can issue.

Note: these are the current managed infrastructure endpoints. A canonical domain (e.g. https://license.cortexbuild.dev) is planned to supersede the raw Azure hostnames above — prefer the canonical domain once it is published, as the infrastructure URLs may change on a region/provider move.

1. Prerequisites

  • Python 3.12+ and pip.
  • Network access to <LICENSE_URL> (the CLI activates and renews online).
  • A local checkout of the repository you want to govern.

Use a virtual environment so CortexBuild is isolated from your project deps:

python -m venv .cortexbuild-venv
# Windows:  .cortexbuild-venv\Scripts\activate
# macOS/Linux:  source .cortexbuild-venv/bin/activate

2. Install the engine

Install with the signing extra — it is required to verify your signed license offline. The --find-links index always resolves the latest published version:

pip install "cortexbuild-core[signing]" --find-links <INDEX_URL>
cortexbuild version

Want repo analysis (code-graph) too? install cortexbuild-core[signing,graph]. To pin a specific version, add ==<version> (e.g. cortexbuild-core[signing]==0.0.1).

3. Activate your license

Bind this machine to your license and cache a signed lease:

cortexbuild auth activate --key <LICENSE_TOKEN> --url <LICENSE_URL>
cortexbuild auth status --json

auth status should show "ok": true, "trusted": true, "signed": true, and your plan. Activation consumes one device seat (your license has a device cap); repeat on each machine up to that cap.

4. Onboard your repository

From the root of the repo you want to govern:

cortexbuild init run .

This analyses the repo and writes a .cortexbuild/ folder (rules, agents, recurrence ledger, onboarding summary). Open .cortexbuild/ONBOARDING.md for a guided next-steps summary.

5. Render the governance surfaces

cortexbuild render

This generates the always-on instruction files your existing AI tools read:

  • .github/copilot-instructions.md + .github/agents/* (GitHub Copilot)
  • CLAUDE.md + agents (Claude Code)
  • AGENTS.md (Codex)
  • .cursor/rules/* (Cursor)

Commit these to your repo. From now on, the AI coding tools you already use operate under CortexBuild governance.

6. Verify

cortexbuild doctor        # checks the instruction surfaces are wired
cortexbuild verify        # OWASP Agentic Top-10 self-assessment
cortexbuild auth status   # confirms your license

Keeping the license current

The signed lease is short-lived (renewed automatically online). To renew explicitly (e.g. in CI, or before a long offline stretch):

cortexbuild auth refresh

Free this machine's seat (e.g. decommissioning a laptop):

cortexbuild auth deactivate

CI / non-interactive runners

Activate once and commit the flow into your pipeline, or set the license via the environment. Confirm licensing in CI with cortexbuild auth status --json.

Troubleshooting

Symptom Fix
license required on a command Run cortexbuild auth activate … (step 3), or auth status to see why.
device seat limit exceeded You've hit your device cap. Run cortexbuild auth deactivate on an old machine, or ask your admin to reassign.
signing extra error Reinstall with pip install "cortexbuild-core[signing]" --find-links <INDEX_URL>.
Activation network error Confirm access to <LICENSE_URL>; corporate proxies may need allow-listing.

Questions? Contact your CortexBuild administrator — they manage licenses, device seats, and plan entitlements from the admin portal.