Cortex FAQ

Cortex FAQ — frequently asked questions

Answers to the most common questions about Cortex. For anything else, visit the support page or write to us.

Hosted or self-hosted

Where does Cortex run?

Usually with us. The hosted service runs at cortex.red8.io, in the EU, one tenant per customer, so there is nothing for you to install or keep running. If you would rather run it on your own infrastructure, that is available on request: it is not offered off the shelf, and we set it up with you.

How do I try it?

Ask for a 14-day trial on cortex.red8.io. We set up your tenant and invite your administrator, and you work in it as you would after buying.

How is it priced?

The hosted service is priced per seat, in volume bands: every seat bills at the rate for your total, so the rate falls as the team grows. A seat is an active user account, and you can change the count at any time. Every tier has all seventeen tools; what differs is the business functions. Team adds calendar and issue-tracker sync, campaigns, LinkedIn publishing, competitor research, automation rules and webhooks. Business adds the money ledger, e-signature sealing, scheduled reports, API tokens and the MCP server. Self-hosting is priced on consultation. Current prices are on the product site.

What happens to my data if I leave?

You get one archive of your whole tenant whenever you ask, and a 30-day window before a deleted tenant is purged — encryption key included. The exports below work on the hosted service too.

Exports and backups

What does the nightly Git export actually contain?

Worth reading carefully, because it is narrower than it sounds. It commits a JSON export of your content to a git repository you nominate — GitHub through your own connection, or your own remote — once a day. It is per user, not per tenant — each person sets their own repository, and the export contains only what that person can read.

It deliberately leaves things out: no credentials of any kind, no attachment file contents (their details only), and synced mail as recent metadata rather than your mailbox. The point is a readable history of your work, not a disk image.

What does restoring an export do?

It merges the content into your active workspace, creating new records. It never modifies or deletes what is already there, and there is deliberately no “replace everything” mode — an import should not be able to destroy a working workspace. Use it to move a project between workspaces or recover content you lost, not to roll a whole instance back.

There is also a per-project export, and unlike the account-wide snapshot it carries attachment contents, so it is the one to use when handing a whole project to someone.

If you run it yourself

Self-hosting is arranged with us, so these answers are for an instance we have set up with you on your own infrastructure.

What actually runs?

One docker compose stack: PostgreSQL 16, Redis, the API, a background worker, an nginx container serving the interface, an isolated sandbox that renders PDF reports, and a bundled metasearch service used for competitor research. A NAS or a small VPS is the usual target; we size it with you, because the honest answer depends on how much mail you sync.

What has to be configured before the first start?

A handful of values in .env that have no safe default: a session secret, your own database name, user and password, an encryption key for stored credentials, the first administrator’s email and password, the origins allowed to call the API, and an absolute path for the data directory. Cortex refuses to start in production if any of them is missing or left at a default, and tells you which — it will not quietly run insecurely. After first boot, a good deal of configuration can also be edited in Settings → Integrations without a restart.

Is there a setup wizard?

No. On first boot Cortex creates the administrator account named in the configuration. That account is a pure instance administrator: it belongs to no workspace and sees only the admin console. The next steps are a workspace and a normal user account to work in it — the separation is deliberate, so that the person who can reset passwords is not also silently inside everyone’s data.

How do upgrades work?

Bring the stack back up on the new version. Database migrations run automatically on boot — there is no separate migrate step, and an older database is brought forward for you. Multiple containers starting at once is safe: they take a lock so only one performs the upgrade.

How do I take a real backup?

Back up the data directory — it holds PostgreSQL and Redis, and on a NAS it is an ordinary folder your existing backup tool can take — or run pg_dump. That, plus your CREDENTIALS_ENCRYPTION_KEY, is what rebuilds a server. Restore the data without that key and every stored credential is unreadable: mailboxes and tokens need reconnecting, and two-factor enrolments have to be redone from recovery codes.

What licence covers a self-hosted instance?

The Business Source License 1.1, and every version becomes Apache-2.0 four years after it is published. Evaluation, development and testing are unlimited and unrestricted.

How does the licence key work offline?

A commercial licence arrives as a signed key you paste into Settings → Integrations. It is verified locally, by checking a signature against a public key built into the image — pure arithmetic, no call home — so an air-gapped instance works for the full term. The key is bound to your instance’s own identifier, which you will find under Settings → Integrations → Plan.

What happens when a licence expires?

A two-week grace period, then the instance quietly falls back to the base tier. Nothing is deleted and nothing is locked — reads stay open, your data stays yours, and only the paid features and limits close again. Limits apply when you create a workspace, mailbox or user, so an instance that grew past them keeps everything it already has.

Does a self-hosted instance report anything back to you?

No. By default there is no licence server configured at all, so no such request is ever made. If you point an instance at one, it sends exactly three things once a day — the instance identifier, the key, and the version. Never workspace data, never mail, never names, and never a count of your users.

Mail

Which providers work?

Anything over IMAP and SMTP, plus Microsoft Graph and the Gmail API for accounts connected with OAuth. There are presets for Gmail, Microsoft and iCloud, and a generic option for everything else.

On a self-hosted instance, why do I register my own OAuth application?

Because the instance is yours, there is no red8.io application standing between it and your mail provider — so you register an app with Microsoft or Google yourself and paste in its client id and secret. Leave those blank and the OAuth buttons simply do not appear; app-password IMAP keeps working.

Two things catch people out. Microsoft has retired basic authentication, so app passwords are often refused outright for work accounts and OAuth is the only route. And your redirect base must be the address as the browser reaches it, over https — both providers reject a plain-http redirect, and Cortex refuses to start with one configured.

An account says “Reconnect needed”

The grant expired or was revoked at the provider. Reconnect the account and it resumes. Cortex backs off between retries rather than hammering a failing account.

Can colleagues see my mailbox?

Not unless you share it. A mailbox is private to the person who connected it by default; you can choose to share it into a workspace.

Calendar

How does calendar sync behave?

Connect Google or Outlook, pick which calendars to include, and their events appear as a read-only overlay in Calendar, as a drag source in the Timesheet, and on Home. It refreshes every few minutes, and faster where your instance is reachable for push notifications.

Writing back is a deliberate, narrow gesture rather than continuous two-way reconciliation: you can publish a card or meeting onto your own calendar. What Cortex creates carries no attendees, no reminders and no conferencing links, so publishing can never notify anyone on your behalf.

Reading works but “add to calendar” is refused

Your connection was granted read-only permission. Google’s consent screen lets you untick the write permission and continue, and a connection made before write support existed keeps the permissions it was given. Reconnect the calendar and accept the write scope.

Accounts, roles and security

How are accounts protected?

Passwords are hashed with Argon2. Sessions use a short-lived access token plus a rotating refresh token, and reusing an old refresh token revokes the whole family — so a stolen token is caught rather than quietly enjoyed. You can add TOTP two-factor or a passkey, review your active sessions, and sign other devices out.

I’ve lost my authenticator

Use one of the ten recovery codes shown when you enrolled: sign in with one, turn two-factor off, and enrol again. Keep them somewhere other than the phone holding the authenticator — they are the supported way back into an account whose device is gone, and they keep working even if the instance’s encryption key has been rotated.

My passkeys stopped being offered

Passkeys need a secure context, so they will not appear over plain http on a LAN address, and they are bound to the exact hostname they were registered against. On a self-hosted instance, changing that hostname setting orphans existing passkeys — though the effect is symmetric, so restoring the old value brings them back.

Is there a “forgot password” link?

Once an administrator has nominated a mailbox for the system to send from — a self-hosted instance has no mail server of its own until you give it one. Until then, an administrator resets passwords. Completing a reset signs out every existing session, and deliberately does not touch two-factor.

Who can see what?

Roles are per workspace: members can write, viewers are read-only, enforced on the server rather than by hiding buttons. Instance administrators hold no workspace membership at all and see only the admin console.

Money visibility is a separate, per-person switch set by an administrator, independent of your role — because a cost rate is salary-adjacent, and “may edit the plan” should not imply “may see what everyone earns”.

Are timesheets private?

Not by default — worth knowing before you roll it out. Out of the box, every member’s timesheet is visible within the workspace. An administrator can enable a workspace policy that lets people hide their own, at which point it becomes each person’s choice. What is always private is your synced calendar: your own events never appear in a colleague’s timesheet rail.

Integrations, API and AI

How much of the GitHub and Azure DevOps sync is two-way?

Issues and work items become cards, and that direction is the rich one — title, description, state and assignee flow in. Going back out is intentionally narrow: you can close, reopen and assign from a card, and create an issue from one. Scheduling, board column and position stay local and are never overwritten, because those are the parts your plan owns rather than the tracker.

If a linked repository never shows its webhook indicator, the token lacks permission to create hooks. Sync still works by polling — it just will not be instant.

Can I drive Cortex from n8n or Node-RED?

Yes. Cortex has its own when X happens, do Y rules, and if you already run an automation engine you can point it at Cortex instead. There are published nodes for both, whose action lists are read from your own instance’s API description, so they match your version rather than ours. Outbound webhooks are signed in the same shape GitHub uses, so an unmodified webhook node can verify them.

Deliveries are at-least-once and carry a stable event id — dedupe on it. Bulk operations such as an import or a nightly sweep publish a summary count rather than thousands of individual events.

What can an AI agent do through the MCP server?

Read your workspace and make ordinary edits — but three classes of operation are excluded structurally, not by prompt: anything that sends (no mail, no campaign, no publishing, no report delivery), anything destructive (no deletions, no member administration), and money-changing writes (no approving a quotation, issuing an invoice or recording a payment). The permitted writes are declared by name, and the server refuses to start if anything outside that list appears.

The MCP server is off until an administrator turns it on, and is a Business-tier feature.

Where does my AI API key go, and what is sent?

You supply your own key for Claude, OpenAI, Gemini or any OpenAI-compatible model, and it is personal — yours, in one workspace, like a mailbox credential. It is checked once when you save it, then encrypted, and it is never readable back through the interface or included in a backup. You can let colleagues use a provider without ever exposing the key.

What travels is the text of the task you actually asked for — the note to summarise, the text to reformat — to the provider you chose, under their terms. Identical requests are cached so you do not pay twice for the same prompt.

How the data model works

What does “nothing syncs, everything links” mean in practice?

That there is only one record. A Gantt bar is the Kanban card — dragging the bar writes the same dates on the same row the card editor writes, and there is no separate scheduling table anywhere in the database. The Projects, Calendar and Portfolio views are all derived from cards. Nothing can drift out of step, because there is nothing to reconcile.

What are the [[task]] chips in notes?

Live references, not copies. A note stores the reference, and the chip resolves when you look at it — so a task chip shows the card’s current column, and a deal chip its current stage, however long ago you typed it. Changes broadcast to open screens, so a chip re-labels itself while you are reading. Every reference is also indexed as it is written, which is what makes “where is this contact mentioned?” an instant answer.

Money and currency

Where do exchange rates come from?

The European Central Bank’s daily reference rates — free and keyless — imported each evening. Every amount converts at its own date, so last quarter never silently re-prices itself.

Two consequences worth knowing. The feed covers about thirty currencies; if your base currency is not one the ECB quotes, Cortex tells you it cannot convert rather than guessing — amounts show at face value with an explicit flag, never a silent rate of 1.0. And a rate you enter by hand is never overwritten by the automatic import, because you overrode it deliberately.

How does a quote become a budget and an invoice?

A budget only ever enters through an approved quotation, and it is derived rather than typed — a phase’s budget is the sum of the approved lines against it, so the two cannot disagree. An approved quotation is immutable; revoke it to change it. Adding scope to an approved project is a change order, by design. From there: the client’s purchase order funds the work, a finished phase drafts its own numbered invoice, and payments and credit notes settle it.

Recorded hours price at the rate in force when they were incurred, so giving someone a raise moves future months and never rewrites last quarter.

How are quotes and invoices numbered?

As a date and a client code — 20260801-APEX — derived rather than counted. There is no running sequence, so there are no gaps to explain and the number does not leak how much business you have done. Change orders and credit notes extend their parent’s number.

Cortex / Privacy Policy (hosted service) / red8.io privacy for Cortex / Terms of Service