Chatons Cloud Architecture

Current architecture reference for Chatons Cloud. Verified against the repository as of March 21, 2026.

Related: Developer Guide, Pi Integration, Cloud Kubernetes Deployment

---

1. Summary

Chatons Cloud is a remote control-plane and runtime path for cloud projects.

Cloud mode changes the ownership model:

• cloud project, conversation, and transcript state are cloud-owned
• provider credentials and model access are cloud-owned
• remote runtime execution is cloud-owned
• the desktop app is a hybrid client that renders local and cloud workspaces in one UI

For a cloud conversation, the desktop does not create a local Pi runtime. It authenticates against Chatons Cloud, bootstraps remote state over HTTP, subscribes to live updates over WebSocket, and sends runtime commands to the remote runtime service.

---

2. Core Rules

2.1 Local and cloud are distinct runtime modes

Chatons supports:

• local projects and conversations backed by the desktop runtime
• cloud projects and conversations backed by cloud services

These are first-class domain concepts, not UI-only labels.

2.2 Cloud projects do not use local Pi

For a cloud project:

• no local Pi session is authoritative
• local settings.json, models.json, and auth.json are not the source of truth
• the desktop does not resolve cloud provider credentials locally
• runtime execution belongs to the remote headless Chatons runtime

2.3 Cloud providers are organization-owned

In cloud mode, provider connections and runtime model availability belong to the cloud organization.

That includes:

• API keys and OAuth-derived credentials
• model metadata and allowlists
• provider base URLs
• subscription and runtime quota enforcement
• default cloud runtime model selection

The desktop may display that metadata, but it must not become the canonical storage location for it.

2.4 Quotas and access are server-derived

Cloud subscription state, runtime admission, project access, conversation ownership, and realtime authorization are resolved server-side from cloud state.

The desktop can display quota and access state, but it does not decide them.

---

3. Service Split

Chatons Cloud is split into three services plus the desktop client.

Desktop app

Responsibilities:

• launch browser auth
• store the desktop cloud session locally
• hydrate cloud state from bootstrap
• maintain a local UI cache for cloud entities
• subscribe to cloud realtime events
• route runtime commands to either local Pi or the cloud runtime service

cloud-api

Responsibilities:

• OIDC-style desktop auth
• browser-side signup/login/onboarding APIs
• cloud account and subscription payloads
• project, conversation, and transcript APIs
• admin plan and user management
• internal authorization checks for runtime and realtime services

cloud-realtime

Responsibilities:

• websocket token minting
• websocket fan-out for connected desktop clients
• replay buffering for reconnect
• Redis-backed multi-pod fan-out when configured
• internal-only event publish endpoint

runtime-headless

Responsibilities:

• create and reuse remote runtime sessions for cloud conversations
• apply cloud-side runtime admission and lease ownership
• execute remote conversation commands
• persist transcript state back to cloud-api
• publish runtime events through cloud-realtime

---

4. Desktop Flow

4.1 Cloud sign-in

The desktop cloud flow is:

1. user starts cloud auth from the desktop
2. desktop opens the system browser
3. browser authenticates against Chatons Cloud
4. Chatons Cloud redirects to chatons://cloud/auth/callback
5. desktop exchanges the auth code for a cloud session
6. desktop bootstraps cloud state and opens realtime

4.2 Bootstrap and local cache

After authentication, the desktop calls the cloud bootstrap API and mirrors the returned organizations, active organization id, cloud projects, and conversations into local SQLite for rendering and startup hydration.

That cache is a view cache, not the cloud source of truth.

Bootstrap now returns all organizations visible through organization memberships. The server also returns one active organization id that clients use as the default org context for new cloud actions unless the user explicitly chooses another organization.

4.3 Realtime

The desktop requests a websocket token from cloud-realtime, opens a websocket, and applies replay plus live deltas. Runtime events are bridged into the same pi:event renderer path used by local conversations so the renderer does not need a separate cloud-only event protocol.

Live delivery and replay are filtered by the server-authorized cloud audience context instead of being broadcast blindly to every socket on a cloud instance. Runtime event envelopes carry organization and conversation audience metadata so reconnect and live fan-out stay scoped to the caller's authorized cloud organization.

4.4 Remote runtime routing

When a conversation belongs to a cloud project, desktop runtime commands are routed to runtime-headless instead of to the local PiSessionRuntimeManager.

---

5. Cloud Data Ownership

Cloud control-plane state currently owns:

• authenticated cloud users and desktop sessions
• active organization selection for authenticated cloud sessions
• cloud subscription plans and usage counters
• cloud organizations, memberships, and organization invites
• cloud projects
• cloud conversations
• cloud conversation messages
• browser-side verification and password-reset tokens

The cloud onboarding surface in landing/ is a presentation client over cloud-api. It is not a second source of truth.

---

6. Runtime Model

6.1 Local mode

Local conversations use the desktop Pi runtime managed in electron/pi-sdk-runtime.ts.

6.2 Cloud mode

Cloud conversations use runtime-headless.

The desktop:

• creates or reuses a remote runtime session
• requests snapshots from the remote runtime
• sends commands to the remote runtime
• stops the remote runtime session when the cloud thread is stopped

The cloud runtime session store supports:

• active-session reuse per conversation
• lease ownership and expiry
• PostgreSQL-backed session persistence when configured

6.3 Current limitation

The cloud runtime service now creates a managed Pi agent directory and serves real Pi-backed remote sessions from runtime-headless.

That means cloud runtime control flow, session reuse, quota admission, transcript persistence, model/auth materialization, and event publication are implemented through a real Pi session rather than through a synthetic echo path.

It is still not equivalent to the full local desktop runtime:

• repo-backed cloud projects now use a managed per-project source checkout plus per-conversation Git worktrees, but they still do not have full parity with the richer local worktree management UI and cleanup paths
• remote extension parity is not complete
• cloud sharing and organization membership are still evolving

---

7. Cloud Project Behavior

When the user opens a cloud project:

• project metadata comes from the cloud
• conversation list comes from the cloud
• message history comes from the cloud
• runtime events come from the cloud
• runtime access and quotas are enforced by the cloud

Cloud projects are intentionally distinct from local repository imports. If filesystem-backed capabilities are unavailable for a given cloud thread, the UI should surface that limitation directly.

---

8. Security and Authorization

Important authorization rules:

• desktop bearer tokens are validated by cloud-api
• websocket token issuance is checked server-side before cloud-realtime accepts a client
• websocket replay and live delivery are filtered by authorized audience metadata, not only by cloud instance id
• runtime admission is checked server-side before runtime-headless creates or serves a session
• internal service-to-service routes require the shared internal service token
• provider secrets entered through the browser cloud portal remain cloud-owned

---

9. Current Limitations

Current cloud limitations in the repository:

• repo-backed cloud runtime uses server-managed Git worktrees, but it still lacks the fuller local worktree tooling and lifecycle surface exposed by the desktop app
• the Postgres control plane now persists organizations, memberships, active organization selection, and invite records, but several cloud tables still retain compatibility user_id columns during the migration to fully organization-native ownership
• the cloud portal and desktop both consume the active organization model, but invite management and org switching UI are still partial compared with the underlying API support
• the cloud portal supports browser auth and provider onboarding, but provider execution support is narrower than desktop-local provider support
• full offline editing and client-side/cloud-side repository sync are not part of the current architecture

These are implementation limitations, not ownership ambiguities. Even where functionality is incomplete, cloud state and cloud execution still remain cloud-owned by design.