[P2][Phase 2][Platform] Multi-Tenant Architecture — phased SaaS isolation

[krishsutariya1742]

Overview

Enable multiple organizations to use a single hosted EngineX deployment with complete isolation of data, agents, credentials, and users.

Example: Acme Corp and Beta Inc both use app.enginex.com. Acme cannot access Beta's sessions, credentials, or reports.

Assignee: @vidorc
Timeline: Phase 2 — after #2 Hourly Tracking v1 pilot (PR #9 shipped).
Not required for: early pilots with dedicated EngineX install per client in their VPC (recommended OSS model today).

---

Ticket metadata

Field	Value
Phase	Phase 2 — Platform scale (post-pilot)
Priority	P2 — Medium
Type	Platform / infrastructure
Depends on	#2 pilot, #10 docs
Related	#5 Desktop — local clients register to this backend

---

Why this matters

• Enables SaaS deployment (recurring revenue, faster onboarding)
• Single infrastructure stack serves multiple customers
• Required for enterprise self-service signup
• Tenant isolation failures are security incidents — must be tested rigorously

---

Current state

EngineX is single-tenant today:

Area	Today	Required change
HTTP API	./engine serve — no authentication	Auth + tenant context on every request
Sessions	In-memory SessionManager	Scoped by tenant_id, persisted
Storage	Files on disk (~/.engine/ JSON — no database)	Tenant-prefixed paths or database
Credentials	Global ~/.engine/credentials/	Per-tenant encrypted vault
Agents	Shared repo templates	Per-tenant agent catalog
Users	None	Organization, user, roles
Frontend	Single workspace	Login + tenant-scoped API

Key files: core/engine/server/, core/engine/storage/, core/engine/credentials/, core/frontend/

---

Personas

Persona	Access
Tenant admin	Manage users, credentials, agents for their organization
Operator / approver	Run workflows, approve in browser
Platform admin	Create tenants, monitor health
Builder	Deploy agent packages into tenant workspace

Primary user interface: web dashboard (not desktop — see #5).

---

Phased delivery

MVP — Tenant isolation core

Goal: Two test tenants; Tenant A cannot read Tenant B data.

• Data model: Organization, User, Membership, Role
• Login (email/password or OIDC for MVP)
• Tenant middleware on all API routes
• Scope sessions, credentials, storage by tenant_id
• Frontend login + tenant-scoped API calls
• Cross-tenant security tests (required)

Phase 2 — Tenant workspaces

• Per-tenant agent catalog
• Per-tenant LLM/model settings
• Per-tenant MCP / skills config
• Audit log (runs, credential access, approvals)

Phase 3 — Enterprise

• SSO/SAML, SCIM provisioning
• Billing / usage quotas
• GDPR export/delete, data residency

---

Non-goals (MVP)

• Billing, multi-region, custom domains per tenant
• Replacing per-customer dedicated deployment (valid GTM before this ships)

---

System architecture

Request flow (auth + tenant context)

Every API call carries tenant identity from login through to storage:

sequenceDiagram
 participant U as User browser
 participant A as Auth
 participant M as Tenant middleware
 participant API as EngineX API
 participant S as Tenant-scoped storage

 U->>A: Login
 A->>U: Session / JWT with tenant_id
 U->>M: HTTP request + credentials
 M->>M: Resolve and validate tenant_id
 M->>API: Request with tenant context
 API->>S: Read / write scoped data only
 S-->>U: Response — never cross-tenant

Loading

Data isolation (tenant boundaries)

flowchart TB
 subgraph deploy [Single EngineX deployment]
 API[API + SessionManager + CredentialStore]
 end

 subgraph acme [Tenant A — Acme Corp]
 direction TB
 UA[Users]
 SA[Sessions / checkpoints]
 CA[Encrypted credentials]
 AA[Agent catalog]
 end

 subgraph beta [Tenant B — Beta Inc]
 direction TB
 UB[Users]
 SB[Sessions / checkpoints]
 CB[Encrypted credentials]
 AB[Agent catalog]
 end

 API --> acme
 API --> beta

Loading

Rule: tenant_id on every session, credential, and storage path. Cross-tenant access attempts must fail and be covered by automated tests.

Reference diagram

---

Definition of done (MVP)

• Two or more tenants operate independently on one deployment
• Users access only their tenant's data
• All APIs enforce tenant isolation — verified by automated tests
• Frontend requires authentication
• docs/MULTI_TENANT.md — data model, auth flow, operations runbook
• Security review completed before merge

---

Open questions

1. Postgres vs filesystem for tenant/user storage in MVP?
2. Auth provider: built-in vs Auth0 / Clerk / Keycloak?
3. Agent delivery: git import, zip upload, or registry?
4. One supervisor per tenant or shared platform supervisor?

[pravinmishra672]

Description

Add multi-tenant support to EngineX so that multiple organizations or customers can use the same hosted EngineX deployment while maintaining complete separation of data, configurations, agents, workflows, and permissions.

This enables the SaaS deployment model (one cloud, many customers). It is not required for early pilots where each customer gets a dedicated instance/VPC.

---

Current state (audit baseline — do not rebuild blindly)

EngineX today is a single-tenant runtime:

Area	Today	Gap
HTTP API	./engine serve — no login, no tenant context	Need auth middleware + tenant scoping on every route
Sessions	In-memory SessionManager (core/engine/server/session.py)	Partition by tenant_id; persist across restarts
Storage	Filesystem SessionStore, checkpoints under data root	Tenant-prefixed paths or DB-backed store
Credentials	Global ~/.engine/credentials/ via CredentialStore	Per-tenant encrypted vault
Agents	Shared discovery from repo examples/templates/	Per-tenant agent registry / upload
Users/Roles	None	Org, user, role model (admin, operator, approver)
Frontend	Web dashboard assumes single workspace	Login, org switcher, tenant-scoped API calls

Related but different: #5 Desktop Agents — local install on employee machines; optional complement to hosted SaaS, not a substitute for tenant isolation.

---

Who uses this (personas)

Persona	How they access EngineX
Tenant admin	Web dashboard — manage users, credentials, agents for their org
Operator / approver	Web dashboard — run workflows, HITL approve/reject
Platform admin (us)	Admin console — provision tenants, monitor usage
Builder (our team / SI)	CLI + deploy pipeline — ship agent packages into tenant workspace

Default end-user experience remains the browser, not desktop (#5).

---

Phased delivery (recommended)

Phase 1 — MVP (tenant isolation core) — P2, post-pilot

Goal: Two test tenants on one deployment; Tenant A cannot read Tenant B data.

• Design tenant data model: Organization, User, Membership, Role
• Auth: login (email/password or SSO/OIDC — pick one for MVP)
• Tenant context middleware on all API routes (core/engine/server/routes.py, routes_credentials.py, routes_skills.py)
• Scope SessionManager sessions by tenant_id
• Partition credential storage by tenant (core/engine/credentials/)
• Partition session/checkpoint storage (core/engine/storage/)
• Frontend: login page + tenant context in API client (core/frontend/src/context/DashboardContext.tsx)
• Cross-tenant security tests (mandatory — one bug = data leak)

Phase 2 — Tenant workspaces

• Per-tenant agent catalog (not shared repo tree)
• Per-tenant LLM/model settings (~/.engine/configuration.json equivalent per org)
• Per-tenant skills and MCP server configs
• Audit log: who ran what, credential access, approvals

Phase 3 — Enterprise SaaS (later)

• SSO/SAML, SCIM provisioning
• Usage quotas / billing hooks
• Data residency / export / delete (GDPR)
• Multi-region deployment notes

---

Code touchpoints (starting map)

core/engine/server/
  app.py              # inject auth + tenant into app context
  session.py          # SessionManager → tenant-scoped
  routes*.py          # reject cross-tenant session_id access

core/engine/storage/
  session_store.py    # tenant prefix or DB backend
  checkpoint_store.py

core/engine/credentials/
  store.py, storage.py  # tenant-scoped EncryptedFileStorage paths

core/frontend/
  pages/, context/    # login, org context, scoped API

---

Non-goals (explicit)

• Not in Phase 1: billing, multi-region, per-tenant custom domains
• Not replacing: per-customer dedicated deploy — that remains valid GTM before [P2][Phase 2][Platform] Multi-Tenant Architecture — phased SaaS isolation #4 ships
• Not the same as [P3][Phase 3][Platform] Desktop Agents — Windows, macOS, Linux #5: desktop agents run on user machines; [P2][Phase 2][Platform] Multi-Tenant Architecture — phased SaaS isolation #4 isolates cloud tenants

---

Why it is important

• Enables SaaS deployment model (recurring revenue, faster onboarding)
• Supports multiple customers on single infrastructure
• Required for enterprise adoption at scale
• Prerequisite for selling "sign up and go" vs "we deploy for you"

Priority: platform · Milestone: Post-pilot / Phase 2 (after #2 Hourly Tracking + #10 docs)

---

System Architecture

---

Definition of done (Phase 1)

• Two+ tenants operate independently on one deployment
• Users can only access data belonging to their tenant (sessions, credentials, history)
• All APIs enforce tenant isolation — verified by automated cross-tenant tests
• Frontend requires login; unauthenticated requests rejected
• docs/MULTI_TENANT.md — model, auth flow, ops runbook
• Security review completed before merge

---

Open questions (resolve in design doc)

1. DB choice: Postgres for users/tenants/sessions vs filesystem-only Phase 1?
2. Auth provider: Built-in vs Auth0/Clerk/Keycloak?
3. Agent packaging: Git import, zip upload, or internal registry?
4. Supervisor/Queen mode: one supervisor per tenant or shared platform supervisor?

[pravinmishra672]

Ticket metadata

Field	Value
Phase	Phase 2 — Platform scale (post-pilot)
Priority	P2 — Medium (after first client)
Type	Platform
Target	Hosted SaaS — many customers, one cloud
Depends on	#2 pilot success, #10 docs
Blocks	Self-serve signup, multi-customer hosted product

Suggested labels (admin): phase-2, priority-p2, type-platform

Why P2: Not needed for per-customer VPC deploy (valid GTM before this ships). Required when selling one shared cloud to many orgs.

See scoped comment above for phased MVP breakdown.

[mishrapravin114]

Assigned to: @vidorc

Scope: P2 Phase 2 — multi-tenant SaaS isolation (auth, tenant context, partitioned storage/credentials). See detailed scoped comment on this issue.

Note: Accept the EngineXV/engineX triage collaborator invite first so GitHub can show you as assignee.

[mishrapravin114]

Comment correction (2026-06-14)

Supersedes the scoped comment’s open question #4 wording:

• Supervisor/Queen mode → Supervisor mode: one supervisor per tenant or shared platform supervisor?

Queen naming was removed in PR #11 (supervisor_runtime.py, examples/templates/supervisors/).

Multi-tenant body and diagrams remain accurate for Phase 2 target architecture.