Skip to main content

​
Projects

Projects are the boundary around one target app in Qodex. A project owns its chats, scenarios, scripts, findings, environments, memory, API keys, members, and BYOK credentials. Keeping these objects project-scoped prevents data and access from crossing between apps or teams.

​
What belongs to a project

Every meaningful object in Qodex is project-scoped: chats, scenarios, scripts, findings, test runs, environments, collections, memory, API keys, and BYOK credentials. Cross-project access is not possible from the agent or the API. The data model lives in Postgres. The projects table is the root. project_members joins users to projects with a role. project_api_keys mints scoped keys for webhooks and CI. environments holds target URLs, auth profiles, and constraints for staging, production, preview, or any other environment.

​
Workspaces

Today, workspaces are an in-memory OrgContext singleton that brackets a set of projects. The full org-as-persisted-tenant model is partial: organization persistence is a runtime bridge, not a database table. Per-project isolation is fully shipped; org-level rollups are evolving.

​
Members and roles

Users sign up with email and password and get verified by email. A user joins a project through project_members with a role. Membership scopes what the user can read and do in the project. The project switcher in the UI lists every project the user belongs to.

​
Project-scoped routes

The web app uses /p/{slug}/... for everything project-scoped: 
/p/acme/chat
/p/acme/scenarios
/p/acme/test-runs
/p/acme/findings
/p/acme/playground
/p/acme/settings
The API mirrors this. The CLI flips between projects with qodex projects use <slug>.

​
Environments

A project can have many environments. Each environment carries:
  • A name and a base URL (and apiBaseUrl if different).
  • Auth: static auth_token, or api_login_config (HTTP login + JSONPath token), or ui_login_steps (Playwright drives login, captures storageState).
  • Constraints: read-only, max requests per second, allow destructive tests, allow security testing.
The same scenario runs against any of them by passing ${baseUrl}, ${apiBaseUrl}, ${authEmail}, ${authPassword} and the SCREAMING_SNAKE variants. Switching environments is one click.

​
BYOK

Bring-your-own-key credentials are stored at the project level. Each project can pick its provider (OpenAI today, Anthropic and Google on the roadmap) and supply its own key. Every LLM call uses the project’s key directly. Qodex takes zero margin on AI spend. Platform-funded mode runs on Qodex’s keys, enforced by per-project 5-hour and weekly caps. BYOK and codex_pool traffic is exempt from those caps.

​
Cost tracking

Every LLM call writes one row to llm_usage_log with the project id, provider, model, input and output tokens, latency, outcome, and cost. The admin console at /admin#llm shows per-project and per-source breakdowns. You see exactly where spend is going.

​
When to use it

  • Use one project per target app. A monolith with one frontend and one API is one project.
  • Create a separate project per environment only when the apps differ enough, such as different auth or domains. Otherwise use one project with multiple environments.
  • Create a separate project per customer if you run a multi-tenant agency setup.

​
When not to use it

  • Splitting a single app into projects per team. Use chats and tags inside one project instead.
  • Sharing scenarios across projects. Today scenarios are project-bound. To share, export and re-import.

​
On the roadmap

Planned: organization persistence. Today OrgContext is an in-memory bridge. The plan is a persisted org-as-tenant layer with org-level rollups, SSO, and billing. See TESTING-PLATFORM-ARCHITECTURE.md.
Planned: per-project provider selection in the UI. Anthropic Claude and Google Gemini join OpenAI as supported providers. Per-project BYOK for the non-OpenAI providers is the remaining column.

Memory

Project-scoped knowledge.

Environments

Project-scoped targets and auth.

Members and roles

Who can do what in a project.

BYOK

Per-project key management.