[INFO][P3][Phase 2][Platform] Engine Cloud — future private hosted control plane (design spec)

[mishrapravin114]

Summary

Engine Cloud is the optional hosted control plane that sits above one or more Engine OSS runtimes. It is not required to run agents or deliver client pilots today.

This ticket captures the future product definition, deployment models, OSS integration hooks, and build scope. Implementation is Phase 2+ and will live in a separate private repo (e.g. EngineXV/engineX-cloud — name TBD), not in the public OSS repo.

Related: #4 (multi-tenant isolation in OSS/API) — Engine Cloud is the SaaS delivery vehicle for multi-tenant; OSS remains the runtime workers install in VPC.

Default for pilots (Phase 1): Model A or B — Engine OSS only in client VPC. No Engine Cloud build required.

---

Two-layer product model

Layer	What it is	Where it runs	In public repo?
Engine OSS	Agent runtime, CLI, dashboard, local credential vault, templates	Client VPC (or managed VM)	Yes — EngineXV/engineX
Engine Cloud	Hosted control plane — central credential vault, OAuth connector hub, org/tenant admin, SSO	EngineX vendor cloud (our SaaS)	No — private product; OSS ships integration hooks only

flowchart TB
 subgraph PublicOSS["Public repo — Engine OSS"]
 CLI["./engine run / ./engine serve"]
 Dash["Web dashboard :8787"]
 Local["~/.engine/ — sessions, credentials, checkpoints"]
 Hooks["ENGINE_OAUTH_API_KEY + with_engine_sync() hooks"]
 CLI --> Local
 Dash --> Local
 Hooks --> Local
 end

 subgraph PrivateCloud["Private repo — Engine Cloud (future)"]
 API["Cloud API api.*"]
 Vault["Per-tenant credential vault"]
 OAuth["Central OAuth connector hub"]
 IdP["SSO / org admin / RBAC"]
 DB["Multi-tenant org/user DB"]
 API --> Vault
 OAuth --> Vault
 IdP --> DB
 end

 Hooks <-->|"credential sync"| API
 CLI -.->|"executes agents locally"| Agent["Agent graphs"]
 Agent --> Local

Loading

---

Capability split: OSS vs Cloud

Capability	Engine OSS (runtime)	Engine Cloud (control plane)
Run agents	Yes — ./engine run, ./engine serve	No — does not execute graphs
Store sessions/checkpoints	Yes — ~/.engine/ on runtime disk	Optional central audit/history (product decision)
Credential vault	Local encrypted files per install	Per-org / per-tenant vault + sync to runtimes
OAuth "Connect HubSpot/Google"	Per-install dashboard + env CLIENT_ID/SECRET	Central OAuth app + token refresh for all tenants
Users / SSO / RBAC	None built-in (proxy in front of :8787)	Org admin, operators, approvers
Multi-tenant isolation	No — one install = one client	Yes — tenant-scoped data (see #4)
Agent catalog	Shared repo templates	Per-tenant agent registry (future)
Billing / self-serve signup	No	Phase 2+

---

Three deployment models

flowchart TB
 subgraph M1["Model A — Client VPC (most common / Phase 1 default)"]
 C1["Client installs Engine OSS"]
 C2["~/.engine credentials + sessions"]
 C1 --- C2
 end

 subgraph M2["Model B — Managed single-tenant"]
 V1["Our cloud VM / K8s — still single-tenant OSS"]
 V2["Dedicated ~/.engine volume per customer"]
 V1 --- V2
 end

 subgraph M3["Model C — OSS runtime + Engine Cloud (Phase 2+)"]
 Cloud["Engine Cloud<br/>credentials · OAuth · SSO · tenants"]
 R1["Runtime A — client VPC"]
 R2["Runtime B — another client"]
 Cloud -->|"sync credentials"| R1
 Cloud -->|"sync credentials"| R2
 R1 --> D1["~/.engine local cache"]
 R2 --> D2["~/.engine local cache"]
 end

 M1 -.- M2
 M2 -.- M3

Loading

Model	Who operates runtime	Who holds credentials	Engine Cloud?
A — Client self-host	Client DevOps	Client (~/.engine or their secret manager)	No
B — Managed single-tenant	Us (one VM per client)	Per-client volume / secrets	No
C — SaaS / multi-tenant	Us or client runtimes	Engine Cloud vault + local cache on runtime	Yes

---

Hybrid enterprise pattern (Model C + client VPC)

Common when data must stay in client cloud but IT wants central connector management:

1. Agents run in client VPC — data never leaves; ./engine run / ./engine serve
2. Engine Cloud holds integration tokens and user directory — synced down to runtime
3. LLM keys stay in client VPC (env or client secret manager), not in Cloud

flowchart LR
 subgraph ClientVPC["Client VPC"]
 RT["Engine OSS runtime"]
 LLM["LLM API keys"]
 Data["Business data / ERP"]
 RT --> LLM
 RT --> Data
 end

 subgraph EngineCloud["Engine Cloud (vendor SaaS)"]
 Vault["Tenant credential vault"]
 OAuth["OAuth connector hub"]
 IdP["SSO / user admin"]
 end

 RT <-->|"ENGINE_OAUTH_API_KEY sync"| Vault
 OAuth --> Vault
 IdP -.->|"dashboard users"| RT

Loading

---

OSS → Cloud credential sync (runtime behavior)

The public repo includes hooks only — not the Cloud service itself.

Hook (OSS today)	Purpose
ENGINE_OAUTH_API_KEY	API key for runtime → Cloud credential sync
CredentialStore.with_engine_sync(base_url=...)	Pull org credentials into local encrypted cache
EngineCredentialClient / EngineSyncProvider	Client library (engine.credentials.engine — not in public repo)
Dashboard Connect OAuth (OSS)	Works without Cloud using per-install HUBSPOT_CLIENT_ID, GOOGLE_CLIENT_ID, etc.

Code reference (OSS): core/engine/credentials/store.py → CredentialStore.with_engine_sync()

If ENGINE_OAUTH_API_KEY is unset, OSS uses local-only storage — same as Model A/B.

sequenceDiagram
 participant Admin as Tenant admin
 participant Cloud as Engine Cloud API
 participant RT as Engine OSS runtime
 participant Local as ~/.engine/credentials
 participant Agent as Agent execution

 Admin->>Cloud: Connect HubSpot / Google (OAuth)
 Cloud->>Cloud: Store tokens per tenant_id
 RT->>Cloud: Sync credentials (ENGINE_OAUTH_API_KEY)
 Cloud-->>RT: Encrypted credential bundle
 RT->>Local: Cache locally (offline resilience)
 Agent->>Local: Load token for tool call

Loading

---

When clients need Engine Cloud vs OSS only

Need	OSS only	Engine Cloud
Single company, one VPC	Yes	Overkill
Client owns all keys in their secret manager	Yes	Optional
Headless workers, no shared login	Yes	No
Many customers on one hosted product (app.you.com)	No	Yes
Central IT connects Salesforce once for all departments/tenants	No	Yes
Enterprise SSO (Okta/SAML) for dashboard users	Proxy in front of OSS, or	Yes
Self-serve signup + billing	No	Yes (Phase 2+)

---

What is NOT in the public repo today

Engine Cloud implementation scope (future private repo):

• Engine Cloud API service (api.* host)
• engine.credentials.engine sync client package (full implementation)
• Multi-tenant user/org database
• Hosted connector marketplace UI
• Tenant admin dashboard (org users, roles, connector management)
• Billing / usage metering (Phase 3)
• SAML/SCIM (Phase 3 — see [P2][Phase 2][Platform] Multi-Tenant Architecture — phased SaaS isolation #4 phased delivery)

OSS ships stubs and env vars so runtimes can sync when Cloud is available; pilots do not depend on it.

---

Phased delivery (proposed)

Phase 2 — Engine Cloud MVP

• Private repo bootstrap (engineX-cloud or monorepo service dir)
• Cloud API: tenant registration, runtime API keys (ENGINE_OAUTH_API_KEY issuance)
• Per-tenant credential vault + OAuth connector hub
• Runtime sync: OSS with_engine_sync() talks to real Cloud API
• Basic org admin UI
• Cross-tenant security tests (coordinate with [P2][Phase 2][Platform] Multi-Tenant Architecture — phased SaaS isolation #4)

Phase 2b — Tenant workspaces

• Per-tenant agent catalog registry
• Per-tenant MCP / skills config
• Central audit log (credential access, approvals)

Phase 3 — Enterprise

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

---

Non-goals (until Phase 2 is funded)

• Replacing Model A/B VPC deployments (valid GTM indefinitely)
• Putting Cloud source in the public OSS repo
• Requiring Cloud for any OSS feature (OAuth Connect works locally today)
• Multi-tenant logic inside a single OSS install without Cloud ([P2][Phase 2][Platform] Multi-Tenant Architecture — phased SaaS isolation #4 tracks OSS-side isolation if ever needed)

---

GTM / sales guidance

Sell today: workflow automation via Engine OSS in client VPC — not a catalog of agents, not Engine Cloud.

Introduce Cloud when: prospect needs multi-customer SaaS, central connector portal, or enterprise SSO across many runtimes.

Investor framing: OSS = adoption + trust + runtime; Cloud = recurring SaaS control plane (private, not open-sourced).

---

Acceptance criteria (for closing this design ticket)

• Engineering agrees on Model A/B/C definitions and repo split (OSS public / Cloud private)
• [P2][Phase 2][Platform] Multi-Tenant Architecture — phased SaaS isolation #4 updated with explicit Engine Cloud dependency notes
• Private engineX-cloud repo created (or decision to defer documented)
• MVP scope signed off before any Cloud implementation begins

---

References

• OSS credential sync hook: core/engine/credentials/store.py
• OSS OAuth routes: core/engine/server/routes_oauth.py, routes_credentials.py
• Multi-tenant design: [P2][Phase 2][Platform] Multi-Tenant Architecture — phased SaaS isolation #4
• Local deployment guide (gitignored from public repo): docs/CLIENT_DEPLOYMENT_GUIDE.md Section 2A