Deploy and operate

Validate

opencloud validate "$APP_DIR"

The command prints the exact manifest-reachable file list. Only the canonical manifest, frontend tree, declared migrations, and declared Function source trees enter the deterministic archive.

Validation also resolves runtime.sdk.version to one exact version. The deployment records that pin, so later platform SDK releases cannot change the running app.

Frontends OpenCloud builds

A frontend with a build step can be built by OpenCloud instead of being uploaded prebuilt. Declare the npm script and keep package-lock.json in the app root:

frontend:
  directory: frontend/dist
  spa: true
  build:
    script: build

Validation then runs npm ci --ignore-scripts and npm run build in an isolated sandbox with no credentials, and bundles the directory the script writes. Any uploaded files in that directory are ignored. The validated revision keeps that exact output, so dev sessions, verification and the release all use the same build. A failed build is a FRONTEND_BUILD_FAILED validation error with the end of the build log.

A validation request waits about a minute for its build. A longer build keeps running while the request answers FRONTEND_BUILD_BUSY; validating the same revision again waits for that build and uses its output instead of starting over. The CLI retries for you.

frontend.directory must be a plain relative path such as frontend/dist, without ./ or .. segments, and the script must write regular files there: links and other special files are refused.

Develop and verify the candidate

Use an isolated development session before changing production:

opencloud app dev start "$APP_DIR"
# edit locally
opencloud app dev sync "$APP_DIR"
opencloud app dev verify "$APP_DIR"

The stable capability URL serves the exact active dev revision with an isolated schema and no production data or secrets. Migration changes replay from empty. Functions remain dormant until the CLI or a deliberate preview interaction invokes them. Verification issues a short-lived receipt bound to the source digest, migration digest, and production base deployment. See Develop safely before production.

For human review before promotion, use the dev session's browserPreviewUrl. It admits only a signed-in owner or builder and opens the isolated revision in a clearly marked Not live preview window with Full size, Tablet, Mobile, and Reload tools. The framed app runs as synthetic user A without changing the reviewer's normal OpenCloud login.

Deploy

Promote the exact verified candidate with a unique idempotency key:

opencloud app dev promote "$APP_DIR" --idempotency-key "$UNIQUE_KEY"

The command follows the durable deployment, runs feature-aware production verification, prints the live URL, and stops dev after success. The platform verifies the artifact and selects the appropriate deployment mode. Maintenance deployments reconcile runtime boundaries, preflight migrations in a disposable constrained schema, create a pre-deployment backup, apply new migrations, activate the release, check health, and reconcile cron. For automation that intentionally does not use a development session, direct deploy "$APP_DIR" remains available but does not carry a dev verification receipt.

With the owner-parity CLI release, success and failure are structured JSON. Preserve the operation ID and use the same idempotency key if the response is lost. A local wait timeout does not mean the deployment failed; recover the durable result without starting a duplicate deployment:

opencloud operation get "$OPERATION_ID" --follow

Serving during an update

Installations can enable online updates for an existing active app. Eligible updates change Function code or frontend assets while preserving the SDK, SQL migration contents, routes, access rules, cron, queues, and other runtime declarations. Deployment health must target an existing static asset, including / for index.html. Initial releases, changed declarations or SQL, and Function-backed health use maintenance mode and can interrupt serving.

An online deployment keeps the current release serving while preparing files, checking runtime readiness, taking a backup and checking the candidate's health. Publication selects the new immutable release. Work already started can finish using its captured release and capabilities, within its original deadline; suspension and revoked access still take effect. An unsuccessful candidate leaves the current release selected. Online preparation does not reapply schema guardrails or run migrations.

Deployment records expose deploymentMode (online or maintenance) and preparationPhase (preparing, ready, published, or failed; null for maintenance). Online updates require the operator's APP_ONLINE_DEPLOYMENTS_ENABLED setting, which defaults to false. They do not change the separate platform-software upgrade process.

Use content-hashed filenames and include the build's asset manifest for lazy-loaded assets. Currently the platform reads .vite/manifest.json, emitted by Vite with build.manifest: true. Only hashed files listed in that manifest may be served from a compatible release replaced in the previous 24 hours (at most 100 prior releases are searched). Copied public files, plain sites without a build manifest, HTML and source maps do not use this fallback. Long-open browsers must still handle an expired asset by reloading; do not rely on arbitrary older source files remaining reachable. Deleting an inactive release ends its asset fallback. Cleanup returns DEPLOYMENT_STILL_IN_USE while a prepared or running Function still needs that release; retry after it finishes.

Release source and newer releases

Each release deployed from a draft keeps that draft's complete file tree as its source, next to the artifact it serves. Owners and builders can download either archive:

GET /v1/apps/{appId}/deployments/{deploymentId}/source
GET /v1/apps/{appId}/deployments/{deploymentId}/artifact

A new draft created from the live release starts from that source. Releases uploaded without a draft, and releases made before release source existed, have only their artifact.

A copy of an app is based on one release. To stop a stale copy from silently replacing someone else's work, a deploy or a new dev session can name that release as expectedActiveDeploymentId. A draft cloned from a release does this automatically. If a newer release is live or still deploying, the request fails with ACTIVE_DEPLOYMENT_CHANGED and names the latest release; start from it and reapply your change.

The CLI does this for you: it records each copy's release in .opencloud/base.json and sends it with deploy and app dev start. opencloud pull <directory> brings a newer release into an unchanged copy. When it conflicts with your edits, pull it into a separate directory (--app and --deployment), merge, and record the merge with opencloud pull <directory> --deployment <id> --merged. deploy --force replaces the newer release deliberately.

Verify

opencloud app verify "$APP_ID"

app verify creates a durable server-side verification operation for active release state, exact runtime metadata, deployment-pinned SDK, canonical HTTPS health, Chromium diagnostics, and the immutable external E2E specification. CLI v3 has no second verification file or partial local substitute. Exercise Data, Files, Auth, and every declared Function in the isolated development revision before promotion, then inspect cron, logs, and usage after normal production traffic. A deliberate 4xx from a Function's own handler counts as exercising it, such as a webhook rejecting a missing signature where owner secrets are unavailable; see Verification.

Inspect

opencloud app sdk-inspect "$APP_ID"
opencloud deployment list "$APP_ID"
opencloud deployment get "$APP_ID" "$DEPLOYMENT_ID"
opencloud cron history "$APP_ID"
opencloud logs "$APP_ID" --level error
opencloud usage "$APP_ID"

A normally replaced healthy deployment becomes superseded. rolled_back means an explicit operator rollback targeted that deployment. SDK upgrades are normal new releases; rollback restores both the frontend and its previous SDK pin.

Recovery

Backups are non-destructive to create and inspect. Restore and code rollback can discard or replace state. An exact-app owner Agent may choose either for its assigned app without another operation-specific approval, then must inspect the terminal operation and verify the resulting state. Ordinary human-directed sessions and legacy or narrower Agent credentials retain the requirement for explicit user authorization of that exact destructive action.