cAppDeveloper docsTurn one application's source into a release, then package that exact release for Windows or Android. This guide takes you from a linked project to an identifiable output file, with clear checks before you distribute it.
Before you begin
MCP 0.24.34 adds storage retention after successful builds. It keeps two recent verified output sets, protects pinned or modified files, and trims older cached AI build environments. Models, saved assets and immutable compiler releases are preserved. The source launcher's normal start also performs maintenance; -DeepClean additionally clears regenerable compiler and package-download caches, so later builds may take longer. Busy builds are skipped. Rebuild/restart an installed owner to activate the new runtime helpers.
Open the intended project and application component. Confirm its source folders and version. You need a connected local cApp service for local compilation and packaging, and the target's build prerequisites for native outputs. Reading these public pages does not start a build.
Decide whether your app is browser-local, uses local runtime services, or needs a hosted backend. A native window does not turn hosted application code into a supported on-device service. Consult runtime environments when choosing capabilities.
Compile is not package
The normal flow is Project → Source → Compile → Sidecars → Platform → Build → Artifacts.
| Stage | What it produces | What it does not prove |
|---|---|---|
| Source inspection | Findings about entry points, framework, routes and service requirements | That the app compiles or runs |
| Compile | An immutable compiler release with source and compiler-owned context | That a native installer exists |
| Preview | A view of the selected release or rendered shell | That the installed native app works |
| Package / platform Build | Target-specific output files made from the selected release | That installation or product workflows have passed |
| Package verification | Checks linking the release, package settings and actual output bytes | A security audit, publisher certification or complete product test |
| Deploy and test | Observations from the selected device and application | That every other platform or workflow behaves the same |
Compiler release references start with capp:compiler-release:sha256:. Packaging consumes that release instead of silently reading a newer source folder. Keep the reference with your test results so you know which application was tested.
Compile your application
- In Build → Application source, select Project folders, then the correct App to build. Use Refresh app after editing source. A one-off Repository ZIP is a separate compatibility workflow, not a persistent project link.
- Check the Version, source analysis and build recommendation. In a split app, confirm the Frontend, Backend and Shared roles before proceeding.
- Review Runtime backend. For an online app, set the deployed backend origin before compilation. Test /api/capp/contract checks the configured cApp contract endpoint; a successful contract response is not a test of every business operation.
- Choose Compile. Wait for the result rather than starting a second run because an intermediate stage is taking time.
- Inspect Application topology, readiness and preview. In Selected release, use Copy reference to retain the exact identity, and Continue to package to use it for the native build.
The normal Compile action handles preparation, analysis and release creation. The separate low-level controls are useful for inspection, but are not extra mandatory steps in this first workflow.
For a multi-app project, inspect each component's result. Build project is the sequential project compilation flow; a diagnostic sibling is not automatically a functioning app, and an existing sibling release is not a fresh result for the component you selected.
Readiness and preview
A usable product, a diagnostic/compatibility surface and a blocked result are different outcomes. A diagnostic page may accurately explain unsupported source without rendering your application. Do not publish that page as a working product just because the archive exists.
Application topology explains what ships locally, what stays hosted and which selected release the targets consume. Expand Release contracts and diagnostics when a requirement is unclear. The preview should show your app's expected first screen and respond to a simple interaction. Verify build checks the selected compiled result; it is not the same action as verifying a native package in Deploy.
A backend origin identifies your app's service, not cApp's local build helper. Use localhost:3000 is a local development convenience, not a production deployment recipe. A different device does not automatically share your computer's loopback service. Ship a reachable backend and test the actual device's connection. Keep backend secrets out of the frontend, build configuration intended for clients and public demos.
Sidecars and window settings
Open Choose sidecars or Library with the intended application active. Select only the needed capabilities, review their targets and configure them. Selected, supported on this platform and running successfully are separate states. A desktop service may need a different implementation on Android; see building with Sidecars.
Choose Windows or Android and inspect the platform settings. Confirm the application identity, version, signing setup and included capabilities. For Android emulator testing, Deploy can request an x86_64 build and optionally include ARM phone architectures.
Windows can use a native title bar, an app bar or integrated browser tabs. Android has separate touch and safe-area behaviour. Build's window-bar preview is a visual aid, not an installed native window. A change to runtime assets or native commands requires a new package and an update of the installed application.
Library configuration, a selected project Guide and Studio customisation can affect the packaged result. Review their effective settings rather than assuming a single form is the whole configuration.
Build the platform package
With the verified release selected, start the target's Build action. Follow the reported stage and inspect Output when it finishes. Use cApp's artifact controls: installed cApp can reveal local outputs, while browser workflows offer downloads through the connected service.
A completed compile or package-preparation operation is not a completed installer build. The output should include actual files and, for new Windows/Android packages, the native package provenance record. An unavailable or failed toolchain stage needs a targeted correction; repeatedly recompiling unchanged source does not repair that prerequisite.
Windows C++ applications
For a linked application declaring capp-native.json, Build shows the native C++ workspace. Enable Windows C++ for the project, Compile source, then Build Windows app. The source release and package history belong to the selected application. Manage source expands its linked folders; Source configuration shows the current descriptor settings.
The build card and notification report the actual stage and elapsed time. Packages shows local completion dates, total build times and the source release used by each successful package. Timing includes runtime preparation and packaging. Older builds without timing metadata say Not recorded. Expanding a source reference reveals the full release ID and package checksum.
Use Copy log or Open logs for build diagnostics. App exits have a separate Run log with Copy run log and Open run output; an app crash does not change a successful package into a failed build. Run verifies the selected package before launch. Native C++ output is currently a portable Windows x64 ZIP.
What needs a new compile?
| Change | Next action |
|---|---|
| Application code, entry files, folder roles or compiler behaviour | Refresh/inspect source and compile a new release. |
| Application version, compiler-owned identity or backend/data/route planning | Set it before compilation and create a new release. Do not relabel the old release. |
| Target packaging options or a repaired packaging prerequisite | Package the same verified release again, after reviewing the new plan. |
| Sidecar package configuration, native shell assets or Studio/Guide selection | Produce a new package; also recompile when the change affects compiler-owned content or planning. |
| A new model loaded into an already installed Local AI runtime | Check that runtime's model controls; this is not automatically a new compiler release. |
Agent compilation does not yet carry every saved Build-page version, backend and planning choice. For distribution, review the exact Agent result in Build or compile through the configured Build workflow. A confident chat reply is not evidence of configuration parity.
Output and provenance
New Windows and Android outputs include a native package provenance record linking the compiler release, package settings, observed toolchain and file hashes. Keep it with the installer and test report. A matching hash identifies bytes; it does not independently establish who published them or whether all runtime behaviour is safe.
Historical artifacts lists files actually present on this computer, including builds started from Agent. Refresh and filter it by platform. An old receipt does not mean its file is still present, and opening history does not create a fresh build.
Keep build protects a managed output set from normal development cleanup. New packages use separate output sets instead of overwriting the previous installer. Keep still matters for cleanup, not as a substitute for an external backup. Source and project Guide content are not build-output cleanup targets.
Release checklist
Before sharing the package, check the selected release, app identity, version and signing configuration. Install it on the intended target, start it without relying on the authoring source folder or development helpers, and exercise the backend and selected Sidecars.
Test permission failures, unavailable services, offline/error states and a restart. For an update, verify the expected app data remains present and the correct signing identity is used. Use Test Runner for bounded app-surface tests and manual/device checks for behaviour it cannot observe. A public Showcase is a separate browser projection, not a replacement for these installed tests.
Troubleshooting
| Symptom | Next check |
|---|---|
| Compile produces a diagnostic page | Read readiness and unsupported requirements. Do not treat a wrapper around the diagnostic as product support. |
| Output belongs to the wrong app or version | Check the project, component and selected immutable reference before packaging again. |
| Packaging fails after compile succeeded | Identify the failed packaging/toolchain stage; preserve the release and retry only after correcting that prerequisite. |
| A Sidecar is missing or unavailable | Check selection, target support, runtime assets and configuration; then build and install an updated package. |
| Download/reveal fails | Use Output's artifact controls and confirm the file still exists; a copied host path is not a public download URL. |
| App works in preview but not installed | Check the installed service bridge, backend reachability and runtime diagnostics without masking the failure with development services. |
What success looks like
You have a specific compiler release, a target-specific package and provenance, and a test result tied to those exact bytes. Continue with Android deployment or Showcase and publishing for the next distinct step.