openship 0.1.0 → 0.1.1

package/docker-compose.yml

@@ -50,9 +50,12 @@ services:
       NODE_ENV: production
       PORT: 4000
       CLOUD_MODE: "false"
+      DEPLOY_MODE: docker
       DATABASE_URL: postgresql://openship:openship@postgres:5432/openship
       REDIS_URL: redis://redis:6379
       JWT_SECRET: change-me-in-production
+      BETTER_AUTH_SECRET: change-me-in-production   # used for session signing
+      TRUSTED_ORIGINS: http://localhost:3001,http://localhost:3000
     depends_on:
       - postgres
       - redis

package/openship.code-workspace

@@ -0,0 +1,7 @@
+{
+    "folders": [
+        {
+            "path": "."
+        }
+    ]
+}

package/package.json

@@ -1,31 +1,45 @@
 {
   "name": "openship",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Open-source, self-hostable deployment platform",
   "license": "MIT",
   "repository": {
     "type": "git",
     "url": "https://github.com/oblien/openship.git"
   },
+  "workspaces": [
+    "apps/*",
+    "packages/*"
+  ],
   "scripts": {
     "build": "turbo run build",
     "dev": "turbo run dev",
+    "dev:api": "turbo run dev --filter=@repo/api...",
+    "dev:saas": "turbo run dev:saas --filter=@repo/api --filter=@repo/dashboard --concurrency=10",
+    "dev:dashboard": "turbo run dev --filter=@repo/dashboard",
+    "dev:desktop": "turbo run dev --filter=@repo/desktop",
+    "dev:web": "turbo run dev --filter=@repo/web",
+    "dev:all": "turbo run dev",
     "lint": "turbo run lint",
     "test": "turbo run test",
     "format": "prettier --write \"**/*.{ts,tsx,js,jsx,json,md}\"",
-    "db:generate": "turbo run db:generate --filter=openship-db",
-    "db:push": "turbo run db:push --filter=openship-db",
-    "db:migrate": "turbo run db:migrate --filter=openship-db",
+    "db:generate": "turbo run db:generate --filter=@repo/db",
+    "db:push": "turbo run db:push --filter=@repo/db",
+    "db:migrate": "turbo run db:migrate --filter=@repo/db",
     "clean": "turbo run clean && rm -rf node_modules"
   },
   "devDependencies": {
-    "openship-tsconfig": "workspace:*",
-    "prettier": "^3.2.0",
-    "turbo": "^2.0.0",
-    "typescript": "^5.4.0"
+    "prettier": "^3.8.1",
+    "turbo": "^2.8.14",
+    "typescript": "^5.9.3"
   },
-  "packageManager": "pnpm@9.0.0",
+  "packageManager": "bun@1.3.10",
   "engines": {
     "node": ">=20.0.0"
+  },
+  "dependencies": {
+    "@octokit/auth-oauth-device": "^8.0.3",
+    "api": "^6.1.3",
+    "oblien": "^2.1.7"
   }
 }

package/packages/adapters/docs/ARCHITECTURE.md

@@ -0,0 +1,160 @@
+# Platform Architecture
+
+> `@repo/adapters` — the abstraction layer between Openship's API and the underlying infrastructure.
+
+## Three Deployment Targets
+
+The same codebase runs in three completely different environments. The `createPlatform()` factory resolves the correct combination at startup based on config.
+
+```
+┌────────────────┬──────────────────────┬──────────────────────────┬─────────────────────┐
+│                │  cloud (Oblien)      │  selfhosted              │  desktop            │
+├────────────────┼──────────────────────┼──────────────────────────┼─────────────────────┤
+│  Runtime       │  CloudRuntime        │  DockerRuntime or        │  BareRuntime        │
+│                │  (pure API calls)    │  BareRuntime             │  (local executor)   │
+├────────────────┼──────────────────────┼──────────────────────────┼─────────────────────┤
+│  Routing       │  CloudInfraProvider  │  TraefikProvider         │  NoopInfraProvider  │
+│                │  (pure API calls)    │  (writes YAML via exec)  │  (silent no-op)     │
+├────────────────┼──────────────────────┼──────────────────────────┼─────────────────────┤
+│  SSL           │  CloudInfraProvider  │  TraefikProvider (ACME)  │  NoopInfraProvider  │
+│                │  (pure API calls)    │  (file ops via exec)     │  (no-op)            │
+├────────────────┼──────────────────────┼──────────────────────────┼─────────────────────┤
+│  System        │  null                │  SystemManager           │  null               │
+│                │  (no RCE at all)     │  (checks + installers)   │  (no setup needed)  │
+├────────────────┼──────────────────────┼──────────────────────────┼─────────────────────┤
+│  Executor      │  null                │  LocalExecutor or        │  null               │
+│                │  (nothing executes)  │  SshExecutor (shared)    │  (BareRuntime owns) │
+├────────────────┼──────────────────────┼──────────────────────────┼─────────────────────┤
+│  ssh2 loaded?  │  NO                  │  Only if SSH config set  │  NO                 │
+└────────────────┴──────────────────────┴──────────────────────────┴─────────────────────┘
+```
+
+## Three Layers
+
+Each layer has a single responsibility. They are composed by the Platform, never used directly.
+
+### 1. Runtime — build/deploy/stop lifecycle
+
+| Class | Transport | Use Case |
+|---|---|---|
+| `DockerRuntime` | dockerode (socket / SSH / TLS) | Self-hosted with Docker |
+| `BareRuntime` | `CommandExecutor` (local or SSH) | Self-hosted bare metal, desktop |
+| `CloudRuntime` | HTTP API calls (Oblien SDK) | Oblien cloud |
+
+- Docker has its **own** SSH transport via dockerode — separate from the shared executor
+- Bare uses the **shared** executor for everything (git, npm, nohup, kill, PID files)
+- Cloud makes **zero** local calls — pure API stubs
+
+### 2. Infra — routing + SSL
+
+| Class | Transport | Use Case |
+|---|---|---|
+| `TraefikProvider` | `CommandExecutor` (dual-path) | Self-hosted |
+| `CloudInfraProvider` | HTTP API calls (Oblien SDK) | Oblien cloud |
+| `NoopInfraProvider` | Nothing | Desktop / dev |
+
+- Traefik writes YAML config files to a watched directory via the executor
+- SSL is Traefik's built-in ACME resolver — cert info read via the executor
+- The executor enables Traefik config to be written on the local machine OR a remote server via SSH
+
+### 3. System — prerequisite checks + server setup
+
+| Class | Transport | Use Case |
+|---|---|---|
+| `SystemManager` | `CommandExecutor` | Self-hosted only |
+| _null_ | — | Cloud and Desktop (no setup needed) |
+
+- Checks: docker, traefik, git, node, bun — all via executor
+- Installers: automated install scripts with real-time log streaming
+- State: cached in `SetupStateStore` (file or DB), 24h auto-reverification
+- Feature gating: `requireFeature("deploy")` reads cached state (free on hot paths)
+
+## File Map
+
+```
+src/
+├── types.ts              # Shared types: configs, CommandExecutor, SshConfig
+├── platform.ts           # Factory + singleton (createPlatform, getPlatform)
+├── index.ts              # Barrel exports
+│
+├── runtime/
+│   ├── types.ts          # RuntimeAdapter interface, RuntimeCapability
+│   ├── docker.ts         # DockerRuntime (dockerode)
+│   ├── bare.ts           # BareRuntime (executor-based)
+│   ├── cloud.ts          # CloudRuntime (API stubs)
+│   └── index.ts          # Factory + re-exports
+│
+├── infra/
+│   ├── types.ts          # RoutingProvider, SslProvider interfaces
+│   ├── traefik.ts        # Traefik file provider (dual-path via executor)
+│   ├── cloud.ts          # Cloud infra (API stubs)
+│   └── noop.ts           # No-op (desktop/dev)
+│
+└── system/
+    ├── types.ts          # SystemLog, ComponentStatus, InstallerConfig, etc.
+    ├── executor.ts       # LocalExecutor, SshExecutor, createExecutor()
+    ├── state.ts          # SetupStateStore interface, FileStateStore
+    ├── checks.ts         # Component health checks (all via executor)
+    ├── installer.ts      # Component installers (all via executor)
+    ├── setup.ts          # SystemManager orchestrator
+    └── index.ts          # Barrel exports
+```
+
+## How It's Wired
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│  API (apps/api)                                                 │
+│                                                                 │
+│  app.ts:  bootstrapPlatform()                                   │
+│           │                                                     │
+│           ▼                                                     │
+│  controller-helpers.ts:  resolveConfig() → initPlatform()       │
+│                          platform() → getPlatform()             │
+│                                                                 │
+│  service code:  const { runtime, routing, ssl } = platform()    │
+│                 await runtime.build(config, onLog)               │
+│                 await routing.registerRoute({ domain, ... })    │
+│                 await ssl.provisionCert(domain)                 │
+└─────────────────────────────────────────────────────────────────┘
+          │
+          ▼
+┌─────────────────────────────────────────────────────────────────┐
+│  @repo/adapters                                                 │
+│                                                                 │
+│  createPlatform(config) ─┬─ "cloud"      → CloudRuntime        │
+│                          │                + CloudInfraProvider   │
+│                          │                + system: null         │
+│                          │                + executor: null       │
+│                          │                                      │
+│                          ├─ "selfhosted" → Docker/BareRuntime   │
+│                          │                + TraefikProvider      │
+│                          │                + SystemManager        │
+│                          │                + executor ─┐         │
+│                          │                            │         │
+│                          │    ┌───────────────────────┘         │
+│                          │    │ shared across:                  │
+│                          │    │  • BareRuntime (if bare mode)   │
+│                          │    │  • TraefikProvider              │
+│                          │    │  • SystemManager                │
+│                          │    │  • checks.ts + installer.ts     │
+│                          │                                      │
+│                          └─ "desktop"    → BareRuntime (own)    │
+│                                           + NoopInfraProvider   │
+│                                           + system: null        │
+│                                           + executor: null      │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+## Environment Variables
+
+| Variable | Values | Effect |
+|---|---|---|
+| `CLOUD_MODE` | `true` / `false` | Force cloud target (overrides DEPLOY_MODE) |
+| `DEPLOY_MODE` | `docker` / `bare` / `cloud` / `desktop` | Select runtime + target |
+
+Resolution priority in `resolveConfig()`:
+1. `CLOUD_MODE=true` or `DEPLOY_MODE=cloud` → `target: "cloud"`
+2. `DEPLOY_MODE=desktop` → `target: "desktop"`
+3. Everything else → `target: "selfhosted"` + `runtime: DEPLOY_MODE`
+4. Default (nothing set) → `target: "selfhosted"`, `runtime: "docker"`

package/packages/adapters/docs/BUILD-PIPELINE.md

@@ -0,0 +1,171 @@
+# Build Pipeline & Process Management
+
+> How builds run, how processes are tracked, and how cleanup works across all runtimes.
+
+## Build Flow
+
+All three runtimes implement `build()` but with completely different transports:
+
+```
+build.service.ts
+    │
+    │  Creates BuildLogger (single source of truth for all log emission)
+    │  Creates logCallback → pushes to logs[] + SSE broadcast
+    │
+    ▼
+runtime.build(config, logger)
+    │
+    ├─ CloudRuntime   → Oblien API: workspace.build() + execAndStream()
+    ├─ BareRuntime    → executor.streamExec() through runBuildPipeline()
+    └─ DockerRuntime  → (stub — Docker builds via Dockerfile)
+```
+
+## BuildLogger — Single Source of Truth
+
+Every log emission goes through `BuildLogger`. No adapter creates `LogEntry` objects with step metadata directly.
+
+```typescript
+class BuildLogger {
+  log(message: string, level?)       // Plain log line
+  step(step, status, message)        // Step lifecycle event (stepper UI)
+  runStep(step, label, fn)           // Run a step: emit running → execute → completed/failed
+  get callback(): LogCallback        // Pass to exec functions for raw output streaming
+}
+```
+
+### Who calls what
+
+| Caller | Method | Purpose |
+|---|---|---|
+| `runBuildPipeline()` | `logger.runStep("clone", ...)` | Step events for clone/install/build |
+| `runBuildPipeline()` | `logger.log(...)` | Pipeline status messages |
+| `build.service.ts` | `logger.step("deploy", ...)` | Deploy phase step events |
+| `build.service.ts` | `logger.log(...)` | Deploy status messages |
+| `executor.streamExec()` | `logger.callback` (raw `LogCallback`) | stdout/stderr lines from shell commands |
+| `cloud.ts execAndStream()` | raw `LogCallback` | Oblien exec output chunks |
+
+## Shared Build Pipeline
+
+`runBuildPipeline()` is used by `BareRuntime` and would be used by `DockerRuntime` when it supports builds. `CloudRuntime` has its own build flow via the Oblien API.
+
+```
+runBuildPipeline(env, config, logger)
+    │
+    ├─ Step: clone
+    │    env.exec(`git clone --branch ${branch} --depth 1 ${repo} .`, logger.callback)
+    │
+    ├─ Step: install
+    │    env.exec(`npm install` / `yarn` / `pnpm install`, logger.callback)
+    │
+    ├─ Step: build (if buildCommand configured)
+    │    env.exec(buildCommand, logger.callback)
+    │
+    └─ Returns { status: "deploying" | "failed", durationMs }
+```
+
+The `BuildEnvironment` abstraction decouples the pipeline from the executor:
+
+```typescript
+interface BuildEnvironment {
+  projectDir: string;
+  exec(command: string, onLog: LogCallback): Promise<void>;
+}
+```
+
+BareRuntime wires it to `this.executor.streamExec()`. A future Docker build could wire it to `docker exec`.
+
+## Process Management (Bare Runtime)
+
+### Deploy — setsid for proper process groups
+
+```
+deploy(config)
+    │
+    │  setsid nohup npm start >> logfile 2>&1 &
+    │  echo $!
+    │         │
+    │         └─ PID captured → written to .pids/{deploymentId}.pid
+    │
+    └─ setsid makes npm the process group leader
+       so all child processes belong to the same PGID
+```
+
+### Stop — kill the entire tree
+
+```
+stop(containerId)
+    │
+    │  1. Read PID from .pids/{containerId}.pid
+    │  2. kill -- -${pid}        ← SIGTERM the entire process group
+    │     (fallback: kill ${pid}   if group kill not supported)
+    │  3. Wait up to 10s for graceful shutdown
+    │  4. kill -9 -- -${pid}     ← SIGKILL the group if still alive
+    │
+    └─ This ensures child processes (e.g., node spawned by npm)
+       are cleaned up too — no orphans
+```
+
+### PID Tracking
+
+```
+${workDir}/
+  .pids/
+    {deploymentId}.pid    ← contains the PID as plain text
+  .logs/
+    {deploymentId}.log    ← stdout + stderr from the process
+```
+
+All PID operations go through the executor:
+- `readPid()` → `executor.readFile(pidFile)`
+- `writePid()` → `executor.writeFile(pidFile, pid)`
+- `isAlive()` → `executor.exec("kill -0 ${pid}")`
+
+This means PID management works identically on local and remote (SSH) servers.
+
+### Build Cancellation
+
+```
+cancelBuild(sessionId)
+    │
+    │  Read PID from .pids/build-{sessionId}.pid
+    │  kill -- -${pid}   ← kill entire build process group
+    │
+    └─ Kills git clone, npm install, or whatever is running
+```
+
+## Resource Configuration
+
+```typescript
+interface ResourceConfig {
+  cpuCores: number;   // Fractional cores (e.g., 0.5, 1, 2)
+  memoryMb: number;   // Memory in megabytes
+}
+
+// Defaults
+DEFAULT_RESOURCE_CONFIG  = { cpuCores: 0.5, memoryMb: 512 }   // runtime
+DEFAULT_BUILD_RESOURCE_CONFIG = { cpuCores: 2, memoryMb: 4096 } // build
+```
+
+- Cloud: `cpuCores` passed directly to Oblien SDK (fractional, e.g., 0.5)
+- Docker: used for container resource limits
+- Bare: informational only (OS manages resources)
+
+## Error Handling
+
+Build failures cascade cleanly:
+
+```
+Pipeline step fails (e.g., npm install exits non-zero)
+    │
+    ├─ executor.streamExec returns { code: non-zero }
+    ├─ BuildEnvironment.exec throws Error
+    ├─ runBuildPipeline catches → logger.step(step, "failed", message)
+    ├─ Returns { status: "failed" }
+    │
+    ▼
+build.service.ts
+    ├─ Updates deployment status to "failed"
+    ├─ Persists logs to DB via finishBuildSession()
+    ├─ Broadcasts failure via SSE
+    └─ Sends failure notification email
+```

package/packages/adapters/docs/CLOUD.md

@@ -0,0 +1,239 @@
+# Cloud Architecture
+
+> How Openship connects to Oblien cloud infrastructure — same pipeline, two auth paths.
+
+## Overview
+
+Openship runs in two modes. Both use the **exact same** `CloudRuntime` and build/deploy pipeline. The only difference is how the Oblien SDK client gets authenticated:
+
+```
+┌─────────────────────────────────────────────────────────────────────────┐
+│                         CloudRuntime(client)                           │
+│                                                                        │
+│   build() → provisionBuildWorkspace → runBuildPipeline → deploy()     │
+│   stop() / start() / restart() / destroy()                            │
+│   logs / metrics / domain management                                   │
+│                                                                        │
+│   Doesn't know or care HOW the Oblien client was authenticated.       │
+└────────────────────────────┬────────────────────────────────────────────┘
+                             │
+              ┌──────────────┴──────────────┐
+              │                             │
+   ┌──────────▼──────────┐      ┌───────────▼───────────┐
+   │  SaaS (CLOUD_MODE)  │      │  Local (!CLOUD_MODE)  │
+   │                     │      │                        │
+   │  Master credentials │      │  Namespace token       │
+   │  clientId + secret  │      │  from stored session   │
+   │                     │      │                        │
+   │  new Oblien({       │      │  new Oblien({          │
+   │    clientId,        │      │    token               │
+   │    clientSecret     │      │  })                    │
+   │  })                 │      │                        │
+   │                     │      │  Scoped to user's      │
+   │  Full platform      │      │  namespace (os-{uid})  │
+   │  access             │      │  30min TTL             │
+   └─────────────────────┘      └────────────────────────┘
+```
+
+## Mode 1: SaaS (`CLOUD_MODE=true`)
+
+When Openship runs as the hosted SaaS platform (api.openship.io):
+
+```
+Server startup
+  → initPlatform({ target: "cloud", cloudClientId, cloudClientSecret })
+  → new Oblien({ clientId, clientSecret })       ← master creds from env
+  → CloudRuntime(client)                          ← singleton, stays for process lifetime
+  → build.service.ts uses platform().runtime directly
+```
+
+The SaaS also exposes a token endpoint for local instances:
+
+```
+POST /api/cloud/token  (requires auth)
+  → ensureNamespace(userId)    ← creates os-{userId} namespace if needed
+  → client.tokens.create({ scope: "namespace", namespace, ttl: 1800 })
+  → { token, namespace, expiresAt }
+```
+
+### Key files
+
+| File | Purpose |
+|---|---|
+| `apps/api/src/lib/openship-cloud.ts` | `ensureNamespace()` + `issueNamespaceToken()` |
+| `apps/api/src/modules/cloud/cloud.controller.ts` | `getToken()` handler |
+| `apps/api/src/modules/cloud/cloud.routes.ts` | `cloudSaasRoutes` → `POST /token` |
+
+## Mode 2: Local (`CLOUD_MODE=false`)
+
+When Openship runs locally (desktop app, self-hosted, CLI):
+
+### Step 1: User connects their Openship Cloud account
+
+```
+Dashboard Settings page
+  → user enters email + password
+  → POST /api/cloud/connect
+  → Local API proxies login to api.openship.io/api/auth/sign-in/email
+  → Receives session token
+  → Encrypts + stores in user_settings.cloud_session_token
+```
+
+### Step 2: Deploy to cloud
+
+```
+build.service.ts → executeBuildAndDeploy()
+  → detects !CLOUD_MODE && target === "cloud"
+  → getCloudToken(userId)
+      → reads encrypted session from DB
+      → POST api.openship.io/api/cloud/token (with Bearer session)
+      → receives namespace-scoped Oblien token (cached in memory, 30min TTL)
+  → createPlatform({ target: "cloud", cloudToken: result.token })
+      → new Oblien({ token })                  ← namespace-scoped
+      → CloudRuntime(client)                    ← per-deploy instance
+  → same build() → same deploy() → same everything
+```
+
+### Key files
+
+| File | Purpose |
+|---|---|
+| `apps/api/src/lib/cloud-client.ts` | `connectCloud()`, `disconnectCloud()`, `isCloudConnected()`, `getCloudToken()` |
+| `apps/api/src/modules/cloud/cloud.controller.ts` | `connect()`, `disconnect()`, `status()` handlers |
+| `apps/api/src/modules/cloud/cloud.routes.ts` | `cloudLocalRoutes` → `POST /connect`, `POST /disconnect`, `GET /status` |
+| `apps/dashboard/src/app/(dashboard)/settings/page.tsx` | Cloud connection UI |
+| `apps/dashboard/src/lib/api/cloud.ts` | `cloudApi` client-side helpers |
+
+## Auth Flow Diagram
+
+```
+LOCAL MODE — full round trip:
+
+┌──────────────┐     POST /api/cloud/connect
+│  Dashboard   │ ──────────────────────────────▶ ┌──────────────┐
+│  Settings    │     { email, password }          │  Local API   │
+│              │                                  │              │
+│              │     { connected: true }           │  cloud       │
+│              │ ◀────────────────────────────────│  controller  │
+└──────────────┘                                  └──────┬───────┘
+                                                         │
+                               POST /api/auth/sign-in    │
+                               { email, password }       │
+                                                         ▼
+                                                  ┌──────────────┐
+                                                  │ Openship     │
+                                                  │ Cloud SaaS   │
+                                                  │              │
+                                                  │ Returns      │
+                                                  │ session token│
+                                                  └──────────────┘
+                                                         │
+                                          encrypt(token) │
+                                          store in DB    │
+                                                         ▼
+                                                  ┌──────────────┐
+                                                  │ user_settings│
+                                                  │ cloud_session│
+                                                  │ _token (enc) │
+                                                  └──────────────┘
+
+
+DEPLOY TIME:
+
+┌──────────────┐                                  ┌──────────────┐
+│ build.service│ ── getCloudToken(userId) ──────▶ │ cloud-client │
+│              │                                  │              │
+│              │                                  │ 1. read DB   │
+│              │                                  │ 2. decrypt   │
+│              │     { token, namespace }          │ 3. POST /api │
+│              │ ◀────────────────────────────────│    /cloud    │
+└──────┬───────┘                                  │    /token    │
+       │                                          └──────┬───────┘
+       │  createPlatform({                               │
+       │    target: "cloud",                              ▼
+       │    cloudToken: token             ┌──────────────────────────┐
+       │  })                              │ Openship Cloud SaaS      │
+       │                                  │                          │
+       ▼                                  │ ensureNamespace(userId)  │
+┌──────────────┐                          │ issueNamespaceToken()    │
+│ CloudRuntime │                          │                          │
+│              │                          │ Returns Oblien namespace │
+│ new Oblien({ │                          │ token (30min TTL)        │
+│   token      │                          └──────────────────────────┘
+│ })           │
+│              │
+│ build()      │──────▶ Oblien API (workspaces, runtime, deploy...)
+│ deploy()     │
+└──────────────┘
+```
+
+## Namespace Model
+
+Each user gets an isolated Oblien namespace:
+
+- **Slug**: `os-{userId}`
+- **Creation**: Idempotent — 409 on duplicate is caught, existing namespace fetched
+- **Cached**: In-memory `Map<userId, slug>` on SaaS server
+
+The namespace token gives full access to everything in that namespace:
+- Create/manage workspaces
+- Build & deploy
+- Domain management
+- Logs & metrics
+
+## Security
+
+| Concern | Approach |
+|---|---|
+| Cloud session at rest | AES-256 encrypted via `encrypt()`/`decrypt()` in `encryption.ts` |
+| Session in transit | HTTPS only (api.openship.io) |
+| Expired sessions | Auto-cleared on 401 from SaaS API |
+| Namespace tokens | 30min TTL, 5min refresh buffer, in-memory cache only |
+| Token scope | Namespace-scoped — user can only access their own resources |
+| No browser cookies | Session lives server-side in DB, never exposed to dashboard |
+
+## API Endpoints
+
+### SaaS routes (`CLOUD_MODE=true`, mounted at `/api/cloud`)
+
+| Method | Path | Handler | Purpose |
+|---|---|---|---|
+| POST | `/token` | `getToken` | Mint namespace-scoped Oblien token |
+
+### Local routes (`CLOUD_MODE=false`, mounted at `/api/cloud`)
+
+| Method | Path | Handler | Purpose |
+|---|---|---|---|
+| POST | `/connect` | `connect` | Proxy login → store encrypted session |
+| POST | `/disconnect` | `disconnect` | Clear stored session |
+| GET | `/status` | `status` | Check connection state |
+
+### Dashboard API (`apps/dashboard/src/lib/api/cloud.ts`)
+
+```typescript
+cloudApi.connect(email, password)  // POST /api/cloud/connect
+cloudApi.disconnect()              // POST /api/cloud/disconnect
+cloudApi.status()                  // GET  /api/cloud/status
+```
+
+## Route Mounting (`app.ts`)
+
+```typescript
+if (env.CLOUD_MODE) {
+  // SaaS: mint tokens for local instances
+  app.route("/api/cloud", cloudSaasRoutes);
+} else {
+  // Local: manage connection to Openship Cloud
+  app.route("/api/cloud", cloudLocalRoutes);
+}
+```
+
+Dynamic imports ensure zero code bleed between modes.
+
+## Database
+
+| Table | Column | Type | Purpose |
+|---|---|---|---|
+| `user_settings` | `cloud_session_token` | `text` (nullable) | Encrypted Openship Cloud session |
+
+Migration: `packages/db/drizzle/0004_add_cloud_session_token.sql`