Getting started
A team meets cortex as organisations with roles, projects with an address and a branch, and a navigation of pages. One shared access policy, loaded by every component, enforces every rule on this page server-side.
Organisations, users and roles
A user belongs to one or more organisations, each membership with one role.
| Role | May open a project | May author platform objects (apps, agents, models, projects) | Typical holder |
|---|---|---|---|
| Platform administrator | Every project | Yes | Platform operator |
| Organisation administrator | Every project of the organisations it administers | Yes | Team lead of a customer organisation |
| Member | The projects it owns, organisation-visible projects of its organisation, and projects explicitly shared with it | No | Analyst, data steward |
| Application user | None; reaches only the apps and agents shared with it | No | External reviewer, customer user |
A project whose ownership cannot be resolved is denied to everyone. An application user is denied project access even where projects are organisation-visible. The API, the assistant's MCP gate and the account service load the same policy.
Roles are assigned on the Organizations page (Admin group). A platform administrator assigns any role; an organisation administrator assigns organisation administrator, member and application user. The Members card shows a capability matrix for the roles the viewer may assign. A new project is private to its owner and the organisation's administrators until it is shared or switched to organisation visibility.
Signing in
The account service issues sessions and signs tokens with a private key only it holds. The API, the assistant and deployed portals verify with the public key. Login, sign-up, refresh, logout and organisation switching pass through the API to it.
| Method | How | Notes |
|---|---|---|
| Password | The Login page | Kept for break-glass and local development |
| Single sign-on | The Login page starts an OpenID Connect code flow with the configured identity provider. The callback verifies the identity token (issuer discovery, signing keys, nonce), requires a verified email, optionally pins the allowed workspace domain and exchanges the identity for a session | Enabled by the environment's identity-provider settings. Unknown users are denied unless automatic provisioning is on; provisioned accounts have no usable password |
| Second factor | A verification page completes a login that requires a code and preserves the deep link the person opened |
The acting organisation
A platform administrator sees every organisation and picks an acting one on the Projects page. The choice is stored in the browser and sent with every API call. The API resolves it as that choice, else the organisation in the session, else the first membership. It scopes lists and defaults only; project access follows the roles above.
Creating a project
A role that may build creates projects on the Projects page. New Project creates an empty project. Project assistant files a card the agent fleet turns into a complete project from a description or a document (see Requirements and knowledge). Change this project files a change card against an existing one.
Creation runs these steps and compensates on failure, since no single transaction spans the stores:
- The project's own database is created in the versioned configuration store with the recipe schema.
- A fork of the prototype is created in the execution engine, inheriting every shared endpoint and service.
- The project's environment settings are seeded on the fork: its configuration database and an object-storage prefix (or the organisation's own bucket and credentials when provisioned).
- The per-fork wrapper endpoint is authored; it injects the project's context into any inherited engine endpoint by name.
- With a git hosting integration configured, a private repository is provisioned as the fork's export remote. Without one the fork keeps a local repository.
- The registry row is written as a commit authored by the creator, who becomes the owner.
The Workflow, Models, Docs and Reports Assistants are stamped when the project's agents or reports are first listed, so a fresh project has agents before anyone authors one.
The project address
Every in-app page lives under an address naming the project and the branch. A page opened without one redirects into the first available project; only the login, second-factor and embedded-studio pages sit outside the prefix. The API reads the same choice from request headers the web application sets. Branches are branches of the recipe; the Branches page lists, creates, switches, diffs and merges them.
Navigation
Simple view lands on Apps and shows Apps, Agents, Guides, Board, Workflows, Docs, Status and Feed. Advanced view shows everything, grouped.
| Item | What lives there |
|---|---|
| Dashboard | Data-steward overview: element lifecycle and mapping counts |
| Alerts | Platform alerts for the project, such as a test-health transition |
| Board | Kanban over the caller's requests to the fleet (builds, changes, bug fixes, agents, guides); cross-project |
| Feed | Slack knowledge surface: digests grouped into topics, and the opt-in channel registry; cross-project |
| Apps | The project's applications: app services and views, with Share, Viewer options, Build a change, Report a bug, Add agent |
| Agents | The project's agents: identity, persona, model, tools, safeguards |
| Docs | Requirement sources, Requirements, Tasks, Summary; the Docs Assistant |
| Build: Guides | Saved spotlight tours over apps, with PDF download |
| Build: Models | Trained models, versions, metrics, lineage, promotion |
| Build: Reports | Documents with a mandated form rendered over governed data |
| Build: Workflows | Business processes, triggers, live runs, My Work |
| Data Governance | Overview, Elements, Sources, Source Mappings, Reference Lists, Processing Rules, Data Review, Quality |
| Operations: Pipeline | The node canvas and the Runs table |
| Operations: Deployments | Exports, the customer archive, the Delivery card |
| Operations: Status | Every requirement-linked test with its latest verdict |
| Operations: Branches | Branches of the recipe |
| Operations: Audit | Per-project compliance runs, findings and issues |
| Admin: Projects, Organizations | Registry and access; Templates, Agent fleet, Benchmark, Cortex Audit and the embedded studio appear only for platform staff |
| Settings | MCP endpoints and access tokens |
The chat
The chat button opens the project's Cortex chat: an orchestrator holding the project's tools and one delegate tool per agent the person may see. It hands governance, engine and analyst work to persona sub-agents inside the assistant. "Chat with agent" on the Agents page reduces the roster to that agent. The window is served from the assistant, streams answers live and also opens inside an app service through the app SDK. An app owner may choose the read-only analyst chat for an app instead. See Agents and MCP.
Settings
Settings lists the MCP endpoints an external client can connect to for the active project and branch: the governance surface (read and write), the read-only surface, the paired engine fork's own MCP address, and a note that the analyst surface is reachable only inside the platform. The Access tokens card mints a labelled bearer for a headless client: the person's identity and exactly their access, valid on every listed endpoint until revoked, shown once. See Integrations and API.
A first week
- Day 1: an organisation administrator creates the project and adds members. In Docs, upload the requirement documents or type the request; they become the first requirement sources version.
- Days 1 to 2: review the build preview (variants with screen mockups, an effort estimate, a technical inventory), edit texts, comment, regenerate with a steer, approve one variant. Approval files the single build card on the Board.
- Days 2 to 3: the card moves from queued to running to done while the fleet builds the app service, pipeline, workflows and agents the sources ask for, attaches evidence and writes tests.
- Day 3: open Apps, share the app with reviewers, set Viewer options, try the Guides.
- Days 4 to 5: read Status, where every requirement-linked test shows its verdict. In Docs, Requirements, "Analyse this project" reworks requirements against what was built and "+ task" files the gaps. Connect an MCP client from Settings if agents outside cortex need the project's tools.