CortexBuild Admin Portal — Guide for Organisation Admins¶

For the person who manages one organisation's CortexBuild licences and people. If you administer the platform itself (multiple customers, seat allocations, signing keys), contact CortexBuild instead.

Portal: https://admin.cortexbuild.dev Sign in with: your email address and the password your CortexBuild contact set for you. Your role and organisation are shown in the top-right corner — org_admin · YourOrg. If it does not say your organisation's name, you are on the wrong account.

1. What you can do¶

You can	You cannot
Issue licences from your allocation	Change how many seats you have
Move a licence to a different colleague	Create or delete organisations
Revoke a licence	Manage platform operators
Issue a replacement activation token	Change signing keys or service settings
Free a device seat	See any other organisation's data
Add people and control what they can see
See your usage, fleet and audit trail

Seats are what your organisation has contracted. You decide how to spend them; changing the total is a conversation with your CortexBuild contact.

2. Licences¶

Seat headroom¶

The Licenses page shows how many seats are free before you issue anything — 24 seats free · YourOrg (1 of 25 used). At zero it says at cap and issuing will be refused; that is the contracted limit, not a fault.

Issuing a licence¶

Licenses → Add license.
Choose your organisation, enter the person's email, pick a plan, set the device cap and an expiry date.
The activation token is shown once. Copy it before closing the dialog.

Hand the token to the person. They activate with:

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

The token is shown once and cannot be retrieved. The service stores only a one-way hash of it — nobody, including CortexBuild, can look it up later. If it is lost, issue a replacement (below).

If someone loses their token¶

Licenses → New token on that row. This:

immediately stops the old token working;
shows you a replacement, once;
leaves devices that are already activated working until their lease next refreshes (up to 7 days), after which they need the new token.

So it is safe to do, but coordinate it — tell the person before you rotate.

Moving a licence to someone else¶

Reassign. This clears every device activation on that licence, so the new holder starts from a clean device cap and the previous holder's machines stop working at their next lease refresh.

Revoking¶

Revoke ends a licence permanently and frees its seat. It cannot be undone — issue a new licence if you need to restore access.

Devices¶

Devices on a licence row lists the machines bound to it, when each was first seen and when it last checked in. Release frees a seat — use it when a laptop is replaced or lost. The person re-activates on the new machine with the same token.

3. Projects and people¶

Team & Projects has two tabs.

Projects — a project is a collection of repos¶

A repo is one repository your team works in. A project is a group of them that you name — "B2B Platform" might hold five repos. Usage rolls up per project, so this is how you answer "what is this team costing and delivering" rather than looking at repos one at a time.

Repos are discovered, not typed in. Once someone runs CortexBuild in a repo, its identifier appears under Repos reported, not yet in a project. You never have to retype what the system already knows.

To set one up:

Add project — give it an id (permanent, lowercase) and a display name.
Repos on its row — tick the repos that belong to it.

Two things worth knowing before you start ticking:

A repo belongs to exactly one project. If it's already in another project, it won't be listed — remove it there first. This is deliberate: if repos could sit in two projects, the usage figures for those projects would double-count and never add up to your organisation's total.
The same repo can appear twice, under two identifiers. One is a readable name (payments-api); the other starts with local: or repo: and is an anonymised id. They come from two different parts of CortexBuild, and they cannot be matched up automatically — the anonymised id is a one-way hash of a file path that only that machine knows. If you recognise them as the same repo, put both in the same project. Nothing is double-counted by doing so; they are two labels for one thing.

The project id cannot be renamed, the display name can. Installed clients report against the id, so changing it would quietly stop their usage being attributed to the project — with no error to tell you. Rename changes only what you see.

Deleting a project doesn't delete anything else: its repos return to the unassigned list, ready to be grouped somewhere else.

People¶

Add the colleagues who should be able to sign in and see your organisation's usage. They get a read-only account: they can see licences, fleet and telemetry for the projects you give them, and change nothing.

Adding someone here is not the same as giving them a licence. A licence lets their CortexBuild CLI run; an account lets them look at the portal. Most engineers need only the licence.

Project access¶

Project access on a person's row chooses which projects they can see. Someone with no projects assigned sees no project-scoped data — that is the safe default, not a bug.

4. Understanding your usage¶

Dashboard¶

The portal opens on your organisation's Overview — governed activities and billable-equivalent tokens recorded across your projects, at a glance.

AI Adoption¶

AI Adoption goes deeper: trends over time, a per-developer ranking, and breakdowns by agent, rule, skill, tool and guard.

Reading the numbers:

Billable-equivalent tokens = input + output + cache-creation tokens. This is the figure shown everywhere usage is totalled or ranked.
Cache reads are shown separately, and excluded from the billable figure. On cache-heavy usage, cache reads can be the large majority of raw token volume, so folding them into one number would make usage look far larger than what is actually billed.
The approx marker means CortexBuild recorded an estimated token count because a model did not report exact usage. It is shown so an estimate is never presented as a precise measurement.
The "Not being counted" chip on a repo or project means exactly that — not "adopted with zero usage," but "nothing has been recorded yet." The two look identical in a naive 0 and are not the same situation.

Weekly report and client download¶

The Weekly tab on AI Adoption shows one row per ISO week, oldest first, so you can compare each week with the one before it. Use Weeks shown to choose how many weeks to list: 4, 8, 12 or 26.

Reading the deltas. Under each figure, the change from the previous week is shown as a percentage. A rise is not automatically good news: read it next to the "Not being counted" chip, so a change in how many repos are reporting is not mistaken for a change in how people work.
Partial weeks. The current week is not finished, so its row carries a partial week marker. Do not read a partial week as a drop.
Exact or sampled. When a collector could not count every event in the window, a note says "Counted from the latest N events; totals may be understated." If that note is absent, the figures are exact. Pages can lag new activity by up to 45 seconds.
Client download. Download client report (JSON) produces a file you can share outside your organisation. It contains category counts only. It never contains guard or rule names, and never contains a person's name, email or other identifier.
Repository names. Repository names are left out unless you tick Include repository names before downloading. Repository names can be account handles, so leave the box unticked for anything leaving your organisation unless you are sure the names are fine to share.

Telemetry¶

Telemetry shows what your teams are actually doing with CortexBuild: events, active users, tokens consumed, estimated cost, and breakdowns by feature, agent, skill, rule and guard.

It opens on your organisation automatically.
Filter by repo, project, user or time range. Filtering by project covers every repo in it, and the headline figures narrow with the list rather than staying organisation-wide.
Figures marked approx include estimated token counts — CortexBuild records an estimate when a model does not report exact usage, and says so rather than presenting a guess as a measurement.

Fleet¶

Fleet lists the repositories and users reporting in, with the CortexBuild version each is running and its conformance score. Use it to find installations that have fallen behind.

Audit log¶

Audit Log records every administrative change in your organisation — who did it, to what, and when. Filter by month. This is your evidence trail; it is written by the service and cannot be edited from the portal.

5. Things worth knowing¶

Sessions end when your account changes. If your role or password is changed, or your account is disabled, you are signed out on your next click rather than whenever a token would have expired. That is deliberate.

You only ever see your own organisation. This is enforced by the database, not just by hiding buttons — a request naming another organisation's licence returns "not found" rather than an error that would reveal it exists.

Nothing here is a self-service password change. Ask your CortexBuild contact to reset it.

6. Feedback¶

The Feedback screen collects what your team reports about CortexBuild itself, from the CLI or from the portal: a category (something not working, something that could be done better, or a task-completion rating), an optional feature it relates to, and a message.

Once your CortexBuild contact has linked your tracker (see below), a report's resolution status appears automatically: Not tracked (no linked issue yet — filing one is what starts the loop), or, once linked, whether it was fixed, marked as by-design, or found not reproducible. Reopening a linked issue supersedes an earlier status.

Filing a linked GitHub issue automatically is set up by your CortexBuild contact, not from this screen — CortexBuild's team manages the GitHub connection.

Sending feedback, with screenshots or logs¶

Use Submit feedback on the Feedback screen. Choose a category (Bug, Feature request, Analytics & reporting, or Suggestion), optionally name the feature it relates to, and describe what happened.

You can attach up to 5 files to one report — pick them, drag them onto the dialog, or paste a screenshot straight from the clipboard:

Type	Formats	Size limit
Images	PNG, JPEG, WebP (single frame)	10 MB each
Text	`.txt`, `.log`, `.json`, `.csv`	5 MB each
Whole report	—	25 MB

Location and other hidden metadata are removed from images before they are stored.
A text file that appears to contain a password, token or key is refused — remove the secret and attach it again.
Attachments are visible only to your organisation's admins and to CortexBuild's support team, and are kept for 180 days.
If the attachment button is missing, attachments are not available for your organisation yet; you can still send the report without them.

7. Health¶

Health shows your organisation's own ingest freshness and any active alerts — whether your fleet's telemetry is arriving on schedule, scoped to your organisation only.

8. Getting help¶

Have these ready — they make any question answerable in one round trip:

your organisation name, exactly as it appears in the portal;
the licence id (the long identifier on the Licenses row), never the token;
what you expected and what happened, with the time.

Never send an activation token by email or chat. It is a credential. If one has been shared somewhere it should not have been, issue a replacement immediately — that is what New token is for.