cAppDeveloper docsThree environments, different capabilities
Your frontend may look similar in each environment while its available services, storage and authority differ. Choose the intended delivery environment before relying on a particular API. The September 2026 documentation focuses on Windows and Android; a source directory or build option for another platform is not an additional supported-product promise.
| Delivery environment | What to expect | What not to assume |
|---|---|---|
| Public website or Showcase | Public content, a deliberately reduced demo and explicitly supported browser capabilities. | Native services, device wallets, local models, owner tools or access to a visitor's cApp project. |
| Installed Windows application | A native shell with the selected Windows capabilities and declared local services. | Arbitrary access to other apps, every catalogue component being present, or a model already being downloaded. |
| Installed Android application | Android-specific assets, touch layout, activity lifecycle and the selected mobile capabilities. | Desktop process/service support, identical window ownership, or native wallet handoff merely because a browser wallet integration exists. |
A portable JavaScript module can be usable in a browser without its native provider being present. Likewise, selecting Local AI packages/provisions an engine, not a ready model or a demonstrated GPU completion. Read each Sidecar reference for its declared targets, dependencies and observed-readiness interface.
Authoring and preview are not installed acceptance
The cApp authoring workspace manages your project, source, compilation and packaging through its local services. The public documentation does none of those operations. A browser-hosted authoring UI connected to your local services is also different from a public visitor viewing a demonstration.
Build preview shows the selected release. A window-bar preview shows proposed presentation. Neither is the installed native process, its service supervisor or its device permissions. Source-agent tests and controlled provider fixtures establish only the boundaries they actually execute.
When an app works only while the development environment is running, identify which service or origin it is using. Do not declare it self-contained until the installed application starts and performs its required workflow using its intended services, independent of the authoring checkout.
Select, package, observe
A Sidecar in the catalogue is not necessarily selected. A selected Sidecar is not necessarily supported on your target. A packaged capability is not necessarily ready when the first script runs.
| Check | What it establishes | What remains to be checked |
|---|---|---|
| Catalogue and declared targets | A documented package and the targets it declares. | Selection, effective configuration and installed support. |
| Application selection and package output | Which capabilities were requested and included for the target. | Successful runtime initialisation and provider policy. |
| SDK discovery or a present method | An interface can be found in the current context. | Compatible version, loaded resources, connection health and permission. |
| A readiness/status result | The specific state reported by that implementation. | The requested operation and its actual result. |
| An observed result | Evidence for that operation on that target. | Broader device coverage, independent verification and application business rules. |
Use the app client API to inspect or await the intended interface, then follow that capability's readiness and error contract. A found owner object or a method that returns without error is not universal proof of success. Check the required method and meaningful result; optional bridges and alpha compatibility adapters need their documented limitations.
Keep unavailable capabilities explicit. Do not quietly change a disabled/manual provider, replace local inference with a hosted service, or repeat an uncertain payment through another connection. Shared engine or service ownership also means one view must clean up its own subscriptions and requests, not shut down another feature's resource.
Frontend and backend responsibilities
The frontend presents controls, requests capabilities and displays results. A wrapped frontend is still client code. Your backend remains responsible for users, sessions, resource authorization, provider secrets, billing and business effects.
| Owner | Responsibilities |
|---|---|
| Authoring workspace | Source/project records, build tools, immutable release selection and package preparation. These are not automatically product capabilities. |
| Installed shell and selected Sidecars | Target-scoped bridges, supervised local resources and the documented application interfaces. The presence of a Sidecar does not grant arbitrary host privileges. |
| Application frontend | Input bounds, visible state, explicit capability demand, safe output handling and cleanup. |
| Application backend | Authentication, authorization, trusted provider access, replay/idempotency decisions and durable business records. |
| Public projection | Reviewed demo content and permitted browser behaviour, without private authoring configuration or owner credentials. |
The route, data and sync APIs declare how integration is intended to work; they do not deploy a backend or implement its business rules. A hash identifies bytes. A receipt records an observed result. Neither substitutes for authorization or trusted external evidence. Use server integration for the server-side boundary.
Origins, loopback and service connections
A hosted backend origin is your application's reachable service, not cApp's development build helper. A device's loopback address refers to that device's environment; the Android application does not automatically reach a service running on your Windows computer by calling localhost.
Installed cApp must use its native service ownership and dynamic bridge. A fixed development port is not a fallback plan for a missing installed service. Your product may deliberately depend on an external backend, but that dependency must be explicit and tested from the target device.
Authentication is equally environment-specific. A browser login or a returned navigation request does not establish an installed session. Verify account state through the application's established session path and follow Links and authentication for native/browser distinctions. Preserve external URL origins and query strings rather than routing everything with a matching pathname through a privileged bridge.
Storage, lifecycle and updates
Source folders, project metadata, compiler releases and installed application data are separate records. A source edit requires a new compile; a change to packaged runtime assets requires a new package and installation. A documentation publication does neither.
Local state belongs to its application/storage context. Do not assume a browser preview, a different origin, a fresh installation or another device shares it. A data-preserving update needs the intended app identity and signing setup; uninstalling or clearing storage can destroy the very recovery records you need. Export important application data through that application's documented controls.
On Android, test leaving and returning to the activity, reload/restart, touch controls and safe areas. On Windows, test startup without unrelated development helpers and with the intended local services. Pause/resume and service ownership are runtime behaviour, not things a responsive CSS screenshot can prove.
A readable failure is part of the interface
Preserve operation IDs and show a bounded error when a provider is missing. A model response is not a tool result. A configured connection is not a verified network. A lost reply is not evidence that an action never happened.
| Failure | Appropriate application response |
|---|---|
| Optional interface absent | Explain what is unavailable and keep unrelated product functions usable. |
| Resource not prepared or engine busy | Offer explicit preparation or wait for the existing request to settle; do not create clients to bypass ownership. |
| Authentication or permission refused | Correct the session/grant at its owner boundary, not through a more privileged fallback. |
| Network unavailable | Distinguish local work from remote acknowledgement. A local save is not successful synchronization. |
| Effect may have happened but reply was lost | Retain the original identity and reconcile authoritative evidence before attempting another effect. |
| Persisted recovery record is missing | Explain the evidence gap; inventing a replacement local record is not proof that an external effect did not occur. |
A minimum runtime test record
Record the application version, selected compiler release, package identity, target, effective capability configuration and the workflow you observed. Check first launch, one successful operation, one refusal/unavailable path and a restart. For updates, check retained data and the intended package/signing identity.
Test backend reachability, wallet handoff or actual model completion separately when your product needs them. Record controlled mocks as mocks. Test Runner is useful for admitted application surfaces, but it is not desktop automation or proof of native services. Help and troubleshooting provides the next checks; credentials, privacy and authority covers sensitive data and approval boundaries.