Cloud

Cloud endpoints connect a self-hosted installation to Openship Cloud and support browser handoffs, managed routing, and transfers. The self-hosted connection routes and Cloud control-plane routes share /api/cloud; the process mode determines which are available.

There is no named native cloud group. To manage Cloud projects through the SDK, use the remote client with the canonical Cloud API and Cloud organization ID. A local owner's Cloud link does not authorize fixed requests or bound/scoped credentials to manage Cloud-stored records; see Cloud compatibility.

Self-hosted endpoints

Present only on a self-hosted instance (not in CLOUD_MODE). The cloud connection is org-owned: it belongs to the organization owner, so every member sees the same verdict. Disconnect and connect-finalize require the owner role, not merely a cloud:admin grant.

Check connection status

GET /api/cloud/status

curl "$OPENSHIP_URL/api/cloud/status" \
  -H "Authorization: Bearer $OPENSHIP_TOKEN"

Connecting itself is a browser flow started from the dashboard (Settings → Cloud): a popup runs the PKCE handshake against Openship Cloud, then posts the result to connect-finalize below. There is no dedicated openship cloud connect CLI verb.

Finalize a connection

The dashboard popup reads its PKCE verifier from localStorage and posts the returned code here to store the org's cloud bearer.

POST /api/cloud/connect-finalize

Cloud control-plane endpoints

Present only in cloud mode (CLOUD_MODE) — i.e. these run on Openship Cloud, not on your self-hosted box. All tenant-scoped operations forward to Oblien through the caller's namespace token; Oblien enforces the namespace boundary natively, so there is no SaaS-side ownership ledger. The public handoff routes are reached by browser redirects and authenticated by a signed, single-use token in the URL.

Handoff & code exchange

The connect and desktop-login flows never hand the local instance a browser cookie. Instead a short-lived, PKCE-bound handoff code is minted (connect-authorize), then swapped for a dedicated session (exchange-code).

POST /api/cloud/connect-authorize

POST /api/cloud/exchange-code

The public GET handoff routes take query params, not a body — desktop-handoff and connect-handoff expect redirect, state, and code_challenge; github/install-callback expects installation_id, setup_action, and state; github/oauth-bridge expects token.

GitHub installation links first open Openship's account selection using flow=select and state. The user can reconnect an existing installation or continue to GitHub for a new one. This also works in the external browser used by self-hosted and desktop instances: the temporary state binds the choice to its initiating user and workspace without requiring a Cloud browser session. Discovery and selection recheck access, and the installation claim uses the same verification and transaction as the dashboard picker.

Deploy proxies (preflight, edge proxy, analytics)

POST /api/cloud/preflight

POST /api/cloud/edge-proxy

POST /api/cloud/analytics

Dashboard product telemetry

POST /api/cloud/telemetry

This optional, first-party endpoint accepts only allowlisted dashboard page and checkout-navigation events. It is separate from the customer traffic analytics relay above and is not an SDK or MCP operation. It returns 404 unless production Cloud telemetry is explicitly configured.

Requests must come from the configured dashboard Origin, use the browser's cookie session when signed in, and omit bearer authorization. The server verifies the current session before associating events with a user or organization. Browser events cannot report payments or other business outcomes; unrecognized properties and bodies larger than 4 KiB are rejected.

Pages

pages creates a managed static page; the enable/disable/delete actions each take just a slug.

POST /api/cloud/pages

POST /api/cloud/pages/disable   (also /enable, /delete)

Invitation relay

Used when a self-hosted operator sets invitationMailSource = "cloud" — the SaaS sends the email from its own infrastructure. Capped at 20/hour per org inside the service.

POST /api/cloud/send-invitation

Subgraph transfer & teardown

The ingest/export pair moves an org's or a single project's rows between a self-hosted instance and the SaaS (team-mode migration and project transfer). Instance-scope dumps are refused.

POST /api/cloud/ingest-subgraph

POST /api/cloud/promote-project

Explicit project promotion uses this receipt-aware variant with { dump, promotionId }. The source persists the transfer ID and original Cloud identity before making the request. Cloud commits the receipt in the same transaction as the project data. A retry with that receipt returns the original import counts, allowing the source to retry local cleanup without importing or overwriting again. Matching project IDs alone do not authorize cleanup; older duplicates without a receipt require review. Both instances must support this endpoint. An older Cloud API rejects it before importing.

Before local cleanup starts, Openship blocks configuration writes and checks the source snapshot again. An edit committed before this check preserves the local copy with TRANSFER_SOURCE_CHANGED; edits attempted during cleanup return PROJECT_TRANSFER_IN_PROGRESS. Failed cleanup releases this guard so the project remains editable. New builds admitted after import are preserved, not cancelled as part of promotion.

Promotion transfers configuration; it does not migrate running workloads or persistent application data. Deploying a local project on a connected Cloud server uses serverId and does not require promotion. See the desktop MCP workflow.

POST /api/cloud/export-subgraph

POST /api/cloud/teardown-project

GitHub App proxy

Cloud holds the GitHub App private key; self-hosted instances never do. Local hands off (userId, request) and gets resolved data back — it never signs a JWT or sees the App credentials.

POST /api/cloud/github/installation-token

Errors

Operations

Managed server connections

HTTP endpoints