Applications
An application in cortex is by default an app service: a whole application with its own container definition and source tree, built and run as a container on the project's engine fork, published at its own hostname and framed by cortex through one optional script. What a customer receives when an application is delivered is on Independent applications.
App services
The engine stores an app service as a document: name, route, the source tree verbatim (binary entries as bytes), the container definition, the port, an optional host port, environment, a health path and the hosting fields below. The service manager writes the tree to disk, builds the image and runs the container. It generates no server and injects no libraries. Any runtime serving HTTP (or plain TCP, when the health check says so) on a port qualifies.
| Adapter | Where it runs | Build | Reachability |
|---|---|---|---|
| Container compose | A single host | The host's container engine | A network-internal name inside the engine network; a loopback port on the host when a host port is set |
| Kubernetes | The cluster | An in-cluster image build; the build fails when the build job fails | A deployment and an internal service per app service, plus one ingress per public service |
The fork's MCP tools create, update, build, inspect (status and logs), read and delete a service. Every status line of a build is appended to the service's build log.
Every new app the fleet builds is an app service. The scaffold produces a browser module, a small server that serves the built assets and proxies API calls to the cortex API (address auto-detected per environment), a page carrying the app SDK tag, a styling chain and a container definition. Data is read through fork endpoints via the API's data-call surface. An environment example file at the tree's root feeds the delivery runbook.
Hosting
| Setting | Effect |
|---|---|
| None | Public at a generated label (service name and project) under the environment's apps domain, covered by the wildcard certificate |
| Subdomain | Replaces the generated label under the apps domain |
| Custom domain | The customer's own hostname; the ingress carries no certificate reference, so the load balancer discovers the certificate issued for it; the customer points a CNAME at the environment's apps hostname. Wins over a subdomain |
| Not public | No ingress, no host URL; reachable inside the network only |
Where an environment answers on a second domain, every generated or subdomain host gets a twin under it; a custom domain gets none. Links the web application hands out follow the host the person is on. The service must allow cortex to frame it, or it shows blank in the Apps embed.
The app registry
The Apps page lists the project's registered apps, of two kinds.
| Kind | How it renders |
|---|---|
| Service | The Apps page embeds the service's URL directly, cross-origin; guides open it by its service name |
| View | The older shape: an endpoint on the fork rendered inside cortex by the engine's view runtime in an embedded frame |
Service rows are synced from the fork on every Apps listing: every service with an HTTP surface and a host URL is registered with its current URL, and rows whose service is gone are purged. A completed new-app request registers the row owned by the requester. Views are maintained until migrated and never authored new. The row menu offers Copy link, Share, Viewer options (owner), Build a change, Report a bug and Add agent.
The cortex app SDK
One script with no dependencies and no build step is included in the service's page with two attributes, the service name and the project. It loads through the service's own API proxy (the cortex API serves it with the cortex origin stamped in, so one page works in every environment) or from the cortex host directly. It consumes the session handoff in the page address fragment and watches the stored token, resolves the app with the API to get the server's companion list, chat kind and guide picks, renders the speed dial in the server's order (Chat as cortex's chat window in a floating panel, every other companion as a chromeless cortex page), answers the tutorial engine over the embed bridge when framed by cortex, and runs guides on the app's own elements.
With the automatic gate on, a visitor without a session sees the sign-in gate at once. A small global object exposes refresh, open, close, the token and a token setter. Cortex draws no dial of its own over a service app.
Viewer options and companions
A companion appears on the dial only when the owner switched it on in Viewer options. The set, in dial order, is Chat, Workflows, Guides, Models, Pipeline, Governance and Docs; the first four are on by default, the last three off because they expose the project's internals. The chat kind chooses the full orchestrator chat (default) or the read-only analyst chat; guide picks narrow the Guides companion. A companion the owner switched on is part of the app for the people it is shared with: the share gate opens that companion's whole route surface, and the project's access policies and endpoint guards govern what happens inside. Hiding a companion is chrome; every backing route enforces its own access.
Sharing
Share opens an app to named users. The standalone share page is chrome-free and redirects to the service URL for a service app. An application user has no project access: they reach only app resolution, the app and agent lists, the workflow run surface and the shared app's data calls, each filtered to what was shared. A visitor with no session on a shared link signs in through the service's own login proxy. A member reaches an app by ownership, an explicit share or the app's organisation visibility.
Sessions, identity and environments
Cortex hands a signed-in person's bearer to a service in the page address fragment when it embeds or opens it. The page stores it and the SDK watches it, so the dial appears with a session and disappears when it is cleared. The service's server forwards only the authorisation header and the project and branch headers to the API. On a data call the API places the caller's verified identity claims (id, email, name, active project and branch) beside the endpoint input; an app nests its own fields under a dedicated arguments key so they are never overwritten.
Nothing environment-specific is baked into a tree: the API address is probed or set, the SDK arrives through the proxy, and the host URL is re-synced on every listing. One tree runs on a local stand, in a development cluster and in production.
Public applications
Cortex has no anonymous runtime path: every data call requires a signed-in identity and the share surface requires an application-user login. A service for anonymous visitors holds one visitor credential server-side (a member with a project share), signs in lazily and never sends that token to a browser. Because a data call places the caller's claims beside the input, such a service routes calls through one fork gateway endpoint that takes a target and arguments, limits the target to the app's own endpoint namespace, delivers the arguments intact and carries the app's own identity as a payload the endpoint guard verifies.
Guides
A guide is a spotlight tour over an app, played by the tutorial engine while the UI stays clickable. For a cross-origin service the engine sends its selectors over the embed bridge; without the bridge a step degrades to a card over the whole frame. Guides, their PDFs and how they are requested are on Requirements and knowledge.
Apps and agents
An app may be agent-backed: a project agent whose tools are the fork endpoints the app reads, linked to the app in the registry and marked with the agent's icon on the Apps page. Add agent on an app without one files a request that derives the agent from the app's data operations. The Chat companion of an agent-backed app is the orchestrator with that agent among its delegates, or the analyst chat when the owner chose it. See Agents and MCP.
Editing a service in the studio
The embedded engine studio (platform staff) has an App Services page with a file explorer over the tree and the container definition, a code editor, Settings (route, port, host port, health path, environment, hosting fields) and Build and Deploy, Start, Stop and Logs. This is the hand-editing path; the governed path is a Board card.
Changing an app
Every change goes through the requests queue. Kinds include a new app, a change, a bug fix, a new or changed agent, a new or changed guide, a new workflow, a new model, a new report, a new data-source connector, a new project and a project change. Filing requires a build role.
- A person picks Build a change or Report a bug on the Apps menu (or Add agent), describes it, and a card appears on the Board.
- A fleet worker claims the card, reads the service tree, patches the changed files, rebuilds and re-runs the requirement's browser tests.
- The completion records the delivered app, attaches evidence (screenshots, commits, test notes, steps, links) and moves the card to done. The Board also moves a card from to-do to queued, closes a card whose work happened outside the fleet and re-queues a failed one.
Comments and links on a card keep the conversation with the worker there. Two cards are never queued against the same service at once, since the tree is one document.