feat: run Pathway on Cyndrbase (replace Convex and cloudflared)

.env.example

@@ -23,13 +23,17 @@
 # automatically.
 PATHWAY_RELAY_URL=https://relay.spiritdevs.com
 
-# Desktop artifact builds deploy `packages/backend` to PATHWAY_CONVEX_URL before
+# Desktop artifact builds deploy `packages/backend` to PATHWAY_CYNDRBASE_URL before
 # packaging, so an app never ships against a backend from an older commit. That
-# needs the deployment's deploy key (Convex dashboard, Settings > Deploy keys).
-# The key is a secret: keep it in the gitignored `.env.prod` you build with, not
-# here. Pass --skip-backend-deploy to package without deploying.
-# PATHWAY_CONVEX_URL=https://<deployment>.convex.cloud
-# CONVEX_DEPLOY_KEY=prod:<deployment>|...
+# needs the deployment's id, deploy API URL and deploy key. The key is a secret:
+# keep it in the gitignored `.env.prod` you build with, not here. Pass
+# --skip-backend-deploy to package without deploying. Leave PATHWAY_CYNDRBASE_URL
+# unset in development: once the Clerk key above is set, `vp run dev` starts a
+# local Cyndrbase for this worktree.
+# PATHWAY_CYNDRBASE_URL=https://<deployment>.<region>.cyndrbase.cloud
+# CYNDRBASE_URL=https://<deploy-api-host>
+# CYNDRBASE_DEPLOYMENT=<deployment>
+# CYNDRBASE_DEPLOY_KEY=...
 
 # Optional: hosted app origin used by the CLI's out-of-band OAuth flow.
 # Defaults to https://app.pathwayos.dev; override for another hosted deployment.

.github/workflows/deploy-relay.yml

@@ -26,19 +26,44 @@ concurrency:
   cancel-in-progress: false
 
 jobs:
+  cyndrbase:
+    name: Require Cyndrbase deployment
+    runs-on: ${{ fromJSON(vars.FLEET_MACOS_RUNNER || '["self-hosted","fleet-macos-arm64"]') }}
+    timeout-minutes: 5
+    environment:
+      name: production
+    outputs:
+      configured: ${{ steps.check.outputs.configured }}
+    steps:
+      - name: Check for a Cyndrbase deployment
+        id: check
+        env:
+          RELAY_CYNDRBASE_DEPLOYMENT_URL: ${{ vars.RELAY_CYNDRBASE_DEPLOYMENT_URL }}
+        run: |
+          if [[ -n "$RELAY_CYNDRBASE_DEPLOYMENT_URL" ]]; then
+            echo "configured=true" >> "$GITHUB_OUTPUT"
+          else
+            echo "::notice title=Relay deploy skipped::The production environment has no RELAY_CYNDRBASE_DEPLOYMENT_URL, so the relay deploy is skipped (see the relay README's Convex cutover). It never falls back to Convex."
+            echo "configured=false" >> "$GITHUB_OUTPUT"
+          fi
+
   deploy_relay:
     name: Deploy production relay
+    needs: cyndrbase
+    if: needs.cyndrbase.outputs.configured == 'true'
     runs-on: ${{ fromJSON(vars.FLEET_MACOS_RUNNER || '["self-hosted","fleet-macos-arm64"]') }}
     timeout-minutes: 15
     environment:
       name: production
     env:
       CLOUDFLARE_ACCOUNT_ID: ${{ vars.CLOUDFLARE_ACCOUNT_ID }}
       AXIOM_ORG_ID: ${{ vars.AXIOM_ORG_ID }}
-      CONVEX_URL: ${{ vars.CONVEX_URL }}
+      CYNDRBASE_DEPLOYMENT_URL: ${{ vars.RELAY_CYNDRBASE_DEPLOYMENT_URL }}
       RELAY_DOMAIN: ${{ vars.RELAY_DOMAIN }}
       RELAY_API_ZONE_NAME: ${{ vars.RELAY_API_ZONE_NAME }}
       RELAY_TUNNEL_ZONE_NAME: ${{ vars.RELAY_TUNNEL_ZONE_NAME }}
+      CYNDRBASE_CONNECT_API_URL: ${{ vars.CYNDRBASE_CONNECT_API_URL }}
+      CYNDRBASE_CONNECT_EDGE_URL: ${{ vars.CYNDRBASE_CONNECT_EDGE_URL }}
       CLERK_PUBLISHABLE_KEY: ${{ vars.CLERK_PUBLISHABLE_KEY }}
       CLERK_JWT_AUDIENCE: ${{ vars.CLERK_JWT_AUDIENCE }}
       APNS_ENABLED: ${{ vars.APNS_ENABLED || 'true' }}
@@ -52,6 +77,20 @@ jobs:
       MAIL_GOOGLE_CLIENT_ID: ${{ vars.MAIL_GOOGLE_CLIENT_ID }}
       ALCHEMY_TELEMETRY_DISABLED: "1"
     steps:
+      - name: Require Pathway Connect settings
+        env:
+          CYNDRBASE_CONNECT_ADMIN_KEY: ${{ secrets.CYNDRBASE_CONNECT_ADMIN_KEY }}
+          CYNDRBASE_CONNECT_TOKEN_KEY: ${{ secrets.CYNDRBASE_CONNECT_TOKEN_KEY }}
+        run: |
+          missing=()
+          for name in CYNDRBASE_CONNECT_API_URL CYNDRBASE_CONNECT_EDGE_URL CYNDRBASE_CONNECT_ADMIN_KEY CYNDRBASE_CONNECT_TOKEN_KEY; do
+            [[ -n "${!name}" ]] || missing+=("$name")
+          done
+          if (( ${#missing[@]} > 0 )); then
+            echo "::error title=Pathway Connect not configured::The production environment is missing ${missing[*]}, so managed tunnels would fail."
+            exit 1
+          fi
+
       - name: Checkout
         uses: actions/checkout@v6
         with:
@@ -76,6 +115,8 @@ jobs:
           CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
           AXIOM_TOKEN: ${{ secrets.AXIOM_TOKEN }}
           CLERK_SECRET_KEY: ${{ secrets.CLERK_SECRET_KEY }}
+          CYNDRBASE_CONNECT_ADMIN_KEY: ${{ secrets.CYNDRBASE_CONNECT_ADMIN_KEY }}
+          CYNDRBASE_CONNECT_TOKEN_KEY: ${{ secrets.CYNDRBASE_CONNECT_TOKEN_KEY }}
           APNS_PRIVATE_KEY: ${{ secrets.APNS_PRIVATE_KEY }}
           MAIL_ENCRYPTION_KEY: ${{ secrets.MAIL_ENCRYPTION_KEY }}
           MAIL_UPLOADTHING_API_KEY: ${{ secrets.MAIL_UPLOADTHING_API_KEY }}

.github/workflows/release-ios.yml

@@ -54,10 +54,33 @@ jobs:
             echo "should_release=true" >> "$GITHUB_OUTPUT"
           fi
 
-  release:
-    name: Build and upload to TestFlight
+  cyndrbase:
+    name: Require Cyndrbase deployment
+    runs-on: ${{ fromJSON(vars.FLEET_MACOS_RUNNER || '["self-hosted","fleet-macos-arm64"]') }}
     needs: check_changes
     if: needs.check_changes.outputs.should_release == 'true'
+    timeout-minutes: 5
+    environment:
+      name: production
+    outputs:
+      configured: ${{ steps.check.outputs.configured }}
+    steps:
+      - name: Check for a Cyndrbase deployment
+        id: check
+        env:
+          CYNDRBASE_DEPLOYMENT_URL: ${{ vars.CYNDRBASE_DEPLOYMENT_URL }}
+        run: |
+          if [[ -n "$CYNDRBASE_DEPLOYMENT_URL" ]]; then
+            echo "configured=true" >> "$GITHUB_OUTPUT"
+          else
+            echo "::notice title=TestFlight release skipped::The production environment has no CYNDRBASE_DEPLOYMENT_URL, so the TestFlight release is skipped. It never falls back to Convex."
+            echo "configured=false" >> "$GITHUB_OUTPUT"
+          fi
+
+  release:
+    name: Build and upload to TestFlight
+    needs: [check_changes, cyndrbase]
+    if: needs.check_changes.outputs.should_release == 'true' && needs.cyndrbase.outputs.configured == 'true'
     runs-on: ${{ fromJSON(vars.FLEET_APPLE_RUNNER || '["self-hosted","fleet-macos-arm64","xcode"]') }}
     timeout-minutes: 60
     permissions:
@@ -94,7 +117,7 @@ jobs:
           IOS_DEVELOPMENT_CERTIFICATE_PASSWORD: ${{ secrets.IOS_DEVELOPMENT_CERTIFICATE_PASSWORD }}
           PATHWAY_CLERK_PUBLISHABLE_KEY: ${{ vars.CLERK_PUBLISHABLE_KEY }}
           PATHWAY_CLERK_JWT_TEMPLATE: ${{ vars.CLERK_JWT_TEMPLATE }}
-          PATHWAY_CONVEX_URL: ${{ vars.CONVEX_URL }}
+          PATHWAY_CYNDRBASE_URL: ${{ vars.CYNDRBASE_DEPLOYMENT_URL }}
           PATHWAY_RELAY_URL: https://${{ vars.RELAY_DOMAIN || 'relay.spiritdevs.com' }}
           PATHWAY_HOSTED_APP_URL: https://${{ vars.PATHWAY_WEB_LATEST_DOMAIN || 'app.pathwayos.dev' }}
         run: bash scripts/ios/release-testflight.sh

.github/workflows/release.yml

@@ -231,15 +231,16 @@ jobs:
       clerk_jwt_template: ${{ steps.public_config.outputs.clerk_jwt_template }}
       clerk_cli_oauth_client_id: ${{ steps.public_config.outputs.clerk_cli_oauth_client_id }}
       relay_url: ${{ steps.public_config.outputs.relay_url }}
-      convex_url: ${{ steps.public_config.outputs.convex_url }}
+      cyndrbase_url: ${{ steps.public_config.outputs.cyndrbase_url }}
+      cyndrbase_configured: ${{ steps.public_config.outputs.cyndrbase_configured }}
       hosted_app_url: ${{ steps.public_config.outputs.hosted_app_url }}
       hosted_app_domain: ${{ steps.public_config.outputs.hosted_app_domain }}
     env:
       RELAY_DOMAIN: ${{ vars.RELAY_DOMAIN }}
       CLERK_PUBLISHABLE_KEY: ${{ vars.CLERK_PUBLISHABLE_KEY }}
       CLERK_JWT_TEMPLATE: ${{ vars.CLERK_JWT_TEMPLATE }}
       CLERK_CLI_OAUTH_CLIENT_ID: ${{ vars.CLERK_CLI_OAUTH_CLIENT_ID }}
-      PATHWAY_CONVEX_URL: ${{ vars.CONVEX_URL }}
+      PATHWAY_CYNDRBASE_URL: ${{ vars.CYNDRBASE_DEPLOYMENT_URL }}
       RELEASE_CHANNEL: ${{ (github.event_name == 'schedule' || inputs.channel == 'nightly') && 'nightly' || 'stable' }}
       PATHWAY_WEB_NIGHTLY_DOMAIN: ${{ vars.PATHWAY_WEB_NIGHTLY_DOMAIN }}
       PATHWAY_WEB_LATEST_DOMAIN: ${{ vars.PATHWAY_WEB_LATEST_DOMAIN }}
@@ -250,13 +251,21 @@ jobs:
         run: |
           set -euo pipefail
 
+          # Builds bake in and deploy to Cyndrbase; without it, skip rather than fall back to Convex.
+          if [[ -z "${PATHWAY_CYNDRBASE_URL:-}" ]]; then
+            echo "::notice title=Release skipped::The production environment has no CYNDRBASE_DEPLOYMENT_URL, so no release is built. It never falls back to Convex."
+            echo "cyndrbase_configured=false" >> "$GITHUB_OUTPUT"
+            exit 0
+          fi
+          echo "cyndrbase_configured=true" >> "$GITHUB_OUTPUT"
+
           relay_domain="${RELAY_DOMAIN:-relay.spiritdevs.com}"
           required=(
             relay_domain
             CLERK_PUBLISHABLE_KEY
             CLERK_JWT_TEMPLATE
             CLERK_CLI_OAUTH_CLIENT_ID
-            PATHWAY_CONVEX_URL
+            PATHWAY_CYNDRBASE_URL
           )
           missing=()
           for name in "${required[@]}"; do
@@ -273,7 +282,7 @@ jobs:
           echo "clerk_jwt_template=$CLERK_JWT_TEMPLATE" >> "$GITHUB_OUTPUT"
           echo "clerk_cli_oauth_client_id=$CLERK_CLI_OAUTH_CLIENT_ID" >> "$GITHUB_OUTPUT"
           echo "relay_url=https://$relay_domain" >> "$GITHUB_OUTPUT"
-          echo "convex_url=$PATHWAY_CONVEX_URL" >> "$GITHUB_OUTPUT"
+          echo "cyndrbase_url=$PATHWAY_CYNDRBASE_URL" >> "$GITHUB_OUTPUT"
 
           if [[ "$RELEASE_CHANNEL" == "stable" ]]; then
             channel_domain="${PATHWAY_WEB_LATEST_DOMAIN:-}"
@@ -291,7 +300,7 @@ jobs:
   build:
     name: Build ${{ matrix.label }}
     needs: [preflight, relay_public_config]
-    if: ${{ !cancelled() && needs.preflight.result == 'success' && needs.relay_public_config.result == 'success' }}
+    if: ${{ !cancelled() && needs.preflight.result == 'success' && needs.relay_public_config.result == 'success' && needs.relay_public_config.outputs.cyndrbase_configured == 'true' }}
     runs-on: ${{ fromJSON(vars.FLEET_MACOS_RUNNER || '["self-hosted","fleet-macos-arm64"]') }}
     timeout-minutes: 45
     environment:
@@ -301,8 +310,10 @@ jobs:
       PATHWAY_CLERK_JWT_TEMPLATE: ${{ needs.relay_public_config.outputs.clerk_jwt_template }}
       PATHWAY_CLERK_CLI_OAUTH_CLIENT_ID: ${{ needs.relay_public_config.outputs.clerk_cli_oauth_client_id }}
       PATHWAY_RELAY_URL: ${{ needs.relay_public_config.outputs.relay_url }}
-      PATHWAY_CONVEX_URL: ${{ needs.relay_public_config.outputs.convex_url }}
-      CONVEX_DEPLOY_KEY: ${{ secrets.CONVEX_DEPLOY_KEY }}
+      PATHWAY_CYNDRBASE_URL: ${{ needs.relay_public_config.outputs.cyndrbase_url }}
+      CYNDRBASE_URL: ${{ vars.CYNDRBASE_URL }}
+      CYNDRBASE_DEPLOYMENT: ${{ vars.CYNDRBASE_DEPLOYMENT }}
+      CYNDRBASE_DEPLOY_KEY: ${{ secrets.CYNDRBASE_DEPLOY_KEY }}
       PATHWAY_HOSTED_APP_URL: ${{ needs.relay_public_config.outputs.hosted_app_url }}
     strategy:
       fail-fast: false
@@ -721,7 +732,7 @@ jobs:
       PATHWAY_CLERK_JWT_TEMPLATE: ${{ needs.relay_public_config.outputs.clerk_jwt_template }}
       PATHWAY_CLERK_CLI_OAUTH_CLIENT_ID: ${{ needs.relay_public_config.outputs.clerk_cli_oauth_client_id }}
       PATHWAY_RELAY_URL: ${{ needs.relay_public_config.outputs.relay_url }}
-      PATHWAY_CONVEX_URL: ${{ needs.relay_public_config.outputs.convex_url }}
+      PATHWAY_CYNDRBASE_URL: ${{ needs.relay_public_config.outputs.cyndrbase_url }}
       PATHWAY_HOSTED_APP_URL: ${{ needs.relay_public_config.outputs.hosted_app_url }}
     steps:
       - name: Checkout
@@ -886,7 +897,7 @@ jobs:
       PATHWAY_CLERK_JWT_TEMPLATE: ${{ needs.relay_public_config.outputs.clerk_jwt_template }}
       PATHWAY_CLERK_CLI_OAUTH_CLIENT_ID: ${{ needs.relay_public_config.outputs.clerk_cli_oauth_client_id }}
       PATHWAY_RELAY_URL: ${{ needs.relay_public_config.outputs.relay_url }}
-      PATHWAY_CONVEX_URL: ${{ needs.relay_public_config.outputs.convex_url }}
+      PATHWAY_CYNDRBASE_URL: ${{ needs.relay_public_config.outputs.cyndrbase_url }}
       VERCEL_TOKEN: ${{ secrets.VERCEL_TOKEN }}
       VERCEL_ORG_ID: ${{ secrets.VERCEL_ORG_ID }}
       VERCEL_PROJECT_ID: ${{ secrets.VERCEL_PROJECT_ID }}
@@ -957,7 +968,7 @@ jobs:
             --build-env "PATHWAY_CLERK_JWT_TEMPLATE=${PATHWAY_CLERK_JWT_TEMPLATE:-}" \
             --build-env "PATHWAY_CLERK_CLI_OAUTH_CLIENT_ID=${PATHWAY_CLERK_CLI_OAUTH_CLIENT_ID:-}" \
             --build-env "PATHWAY_RELAY_URL=${PATHWAY_RELAY_URL:-}" \
-            --build-env "PATHWAY_CONVEX_URL=${PATHWAY_CONVEX_URL:-}" \
+            --build-env "PATHWAY_CYNDRBASE_URL=${PATHWAY_CYNDRBASE_URL:-}" \
             --build-env "VITE_HOSTED_APP_URL=https://$channel_domain" \
             --build-env "VITE_HOSTED_APP_CHANNEL=$channel_name"
 

.macroscope/check-run-agents/effect-service-conventions.md

@@ -40,7 +40,7 @@ Review changed TypeScript and directly affected call sites for the conventions b
 - Export a real `make` when the module owns construction. Do not create `make = Effect.succeed(...)` solely to force `Layer.effect`.
 - Export the canonical layer as `export const layer = Layer...`. `Layer.effect` is not required: use `Layer.succeed`, `Layer.scoped`, or another appropriate constructor when that matches the implementation.
 - In a concrete implementation module already named for the implementation, use plain `make` and `layer` (for example `BunPtyAdapter.ts` and `NodePtyAdapter.ts`).
-- Keep implementation-specific names when an abstract port module contains one of several possible implementations, for example `makeCloudflaredRelayClient` and `layerCloudflared` in `RelayClient.ts`.
+- Keep implementation-specific names when an abstract port module contains one of several possible implementations.
 - `infra/relay/src/db.ts` is an intentional exception: an inline `Layer.succeed(RelayDb, db)` is acceptable without generic `make`/`layer` exports.
 
 ## Dependency acquisition and runtime boundaries

AGENTS.md

@@ -83,6 +83,13 @@ The most common defect in this repo is a change that works on the path you teste
 - `vp i` installs. Worktrees get this from the pathway.json setup script; if module resolution looks broken, it probably did not run.
 - `vp run dev` starts server and web. In a worktree, state defaults to that worktree's gitignored `.pathway`, which deliberately outranks an ambient `PATHWAY_HOME` so you cannot land on shared state by accident. An explicit `--home-dir` still wins.
 - Ports derive from the worktree path and are stable across restarts, but read the real ones from the `[dev-runner]` line since occupied ports shift.
+- With cloud sync configured (`PATHWAY_CLERK_PUBLISHABLE_KEY` or `CLERK_JWT_ISSUER_DOMAIN`, plus `PATHWAY_RELAY_URL` or `PATHWAY_RELAY_JWT_ISSUER`), `vp run dev`, `dev:server` and `dev:desktop` also start a checkout-local Cyndrbase backend (`scripts/lib/local-cyndrbase.ts`); the `[dev-runner]` line reports `cyndrbase=local`, a URL, or `off`.
+  - It runs a Postgres cluster under `.pathway/cyndrbase` and a loopback `cyndrd --local-deploy`, then runs `cyndr dev`, which deploys `packages/backend` and redeploys whenever its sources change. Data persists; delete that directory for a fresh database.
+  - Build `cyndrd` first: `cargo build -p cyndrd -p cyndrbase-isolate --bins` in the Cyndrbase checkout that `packages/backend` links (Cyndrbase packages are `link:` paths until they publish to npm). Postgres comes from `PG_BIN`, then `pg_config --bindir`, then Homebrew's Postgres 17.
+  - Each start writes `.pathway/cyndrbase/cyndr.env` (`CYNDRBASE_URL`, `CYNDRBASE_DEPLOYMENT`, `CYNDRBASE_DEPLOY_KEY`, `CYNDRBASE_DATABASE_URL`) for `cyndr run`, `cyndr env` and `psql`.
+  - The server talks to the engine's loopback URL; web reaches it through Vite at `/cyndrbase`, so remote browsers and tunnels work. An explicit `PATHWAY_CYNDRBASE_URL` targets that deployment instead.
+  - Vite applies `server.fs.deny` to the requested path, not to a symlink's target, so never leave a symlink to `.env` or `.pathway` inside the repo: the dev origin would serve it.
+  - Storage (`ctx.storage`) needs an uploadfile binding: point `CYNDRBASE_FILES_CONFIG` at its JSON (Cyndrbase `docs/design/06-files.md`) and the engine gets `--files-config` and listens on the binding's `content_origin`. Without one, every storage call returns `ServiceDisabled`, so attachment uploads and project icon images fail.
 - To share a development environment remotely, use Pathway Connect rather than exposing the development server directly.
 - The web app requires pairing. Hand over the pairing URL, not the bare origin. A URL without its token is useless to whoever you gave it to. If the token got consumed, mint a fresh one with `node apps/server/src/bin.ts pair` — note it carries standard scopes, while the startup URL carries admin scopes (needed for Settings → Connections management).
 - Stop what you started, by the PID you tracked. See rule 1.

apps/pathway-ios/Config/Pathway.xcconfig

@@ -2,7 +2,7 @@
 // .env/.env.local files by `node scripts/configure-pathway-ios.ts`.
 PATHWAY_CLERK_PUBLISHABLE_KEY =
 PATHWAY_CLERK_JWT_TEMPLATE =
-PATHWAY_CONVEX_URL =
+PATHWAY_CYNDRBASE_URL =
 PATHWAY_RELAY_URL = https:/$()/relay.spiritdevs.com
 PATHWAY_SITE_URL = https:/$()/app.pathwayos.dev
 

apps/pathway-ios/Pathway/Info.plist

@@ -32,8 +32,8 @@
 	<string>$(PATHWAY_CLERK_PUBLISHABLE_KEY)</string>
 	<key>PATHWAY_CLERK_JWT_TEMPLATE</key>
 	<string>$(PATHWAY_CLERK_JWT_TEMPLATE)</string>
-	<key>PATHWAY_CONVEX_URL</key>
-	<string>$(PATHWAY_CONVEX_URL)</string>
+	<key>PATHWAY_CYNDRBASE_URL</key>
+	<string>$(PATHWAY_CYNDRBASE_URL)</string>
 	<key>PATHWAY_RELAY_URL</key>
 	<string>$(PATHWAY_RELAY_URL)</string>
 	<key>PATHWAY_SITE_URL</key>

apps/pathway-ios/Pathway/shared/constants/appConfiguration.swift

@@ -3,7 +3,7 @@ import Foundation
 enum AppConfiguration {
     static let clerkPublishableKey = nonemptyString(forInfoKey: "PATHWAY_CLERK_PUBLISHABLE_KEY")
     static let clerkJWTTemplate = nonemptyString(forInfoKey: "PATHWAY_CLERK_JWT_TEMPLATE")
-    static let convexDeploymentURL = optionalURL(forInfoKey: "PATHWAY_CONVEX_URL")
+    static let convexDeploymentURL = optionalURL(forInfoKey: "PATHWAY_CYNDRBASE_URL")
     static let relayURL = optionalURL(forInfoKey: "PATHWAY_RELAY_URL")
     static let siteURL = optionalURL(forInfoKey: "PATHWAY_SITE_URL")
     static let mailSetupURL = siteURL?.appending(path: "settings/email")
@@ -12,7 +12,7 @@ enum AppConfiguration {
         [
             clerkPublishableKey == nil ? "PATHWAY_CLERK_PUBLISHABLE_KEY" : nil,
             clerkJWTTemplate == nil ? "PATHWAY_CLERK_JWT_TEMPLATE" : nil,
-            convexDeploymentURL == nil ? "PATHWAY_CONVEX_URL" : nil,
+            convexDeploymentURL == nil ? "PATHWAY_CYNDRBASE_URL" : nil,
             relayURL == nil ? "PATHWAY_RELAY_URL" : nil
         ].compactMap(\.self)
     }