Local quickstart

Evaluate the full Codemagic Patch service on your machine before provisioning domains or OAuth. The local evaluation stack runs the real server, worker, Postgres, MinIO, and dashboard, with sign-in replaced by a local one-click login. If you want to see an OTA update before integrating your own app, try the optional on-device demo to watch an OTA update apply on a simulator or emulator.

Using these docs with AI

Use this button to send your AI assistant to the full markdown index.

What you need

macOS, Linux, or WSL 2 on Windows — the command runs a bash script, so a native Windows shell is not supported
Node.js 20.19+ or 22.12+ for the cmpatch CLI, plus git and curl (the CLI downloads its copy of the repository and runs its bootstrap script)
Docker with Compose v2 — if it is missing or not running, the CLI offers to install or start it
Only if you want to run the demo app: an iOS Simulator (macOS, Xcode, and CocoaPods or the Bundler version required by the demo lockfile) and/or an Android emulator (Android SDK, Java, and adb on PATH), plus Node.js ≥ 22.20 and Yarn via Corepack

1. Start the stack

npm install -g @codemagic/patch-cli
cmpatch selfhost local-eval

The command checks Docker first (offering to install or start it), prepares the source it needs, builds and starts the stack, seeds demo apps, and points cmpatch at it. The first run can take a few minutes while images build. Running it again is safe: an already-running stack is just re-checked.

When it finishes you get:

Dashboard — http://localhost:8080 (sign in as local-admin@example.com, prefilled, one click; the CLI offers to open it)
API — http://localhost:3000; the CLI makes it the default when no higher-precedence project or environment setting overrides it
Seeded demo-app-ios / demo-app-android for the on-device demo, plus Example Data (Staging / Production releases and metrics) so the dashboard looks populated before you publish

You can now connect your own app, explore the dashboard, or try the demo if you want to see an OTA update on a ready-made app first.

cmpatch selfhost local-eval status prints everything else about the stack whenever you need it: the services and their state, the MinIO console, the seeded API token, and a sample publish command.

From a clone instead

If you would rather work from your own clone of the repository, the script the CLI wraps does the same thing (it also needs Node.js ≥ 22.20 and Yarn, and installs cmpatch globally itself):

git clone https://github.com/codemagic-ci-cd/codemagic-patch.git
cd codemagic-patch
./scripts/local-eval/up.sh

warning

Evaluation only, not a production install. Authentication is disabled and all ports bind to localhost. To deploy with your own domains, follow Install.

2. Try it with your own app

You can start here as soon as the stack is running; the demo is optional. To use Patch in your project, wire the SDK against localhost:

Config key	Local value
`CodemagicPatchApiUrl`	`http://localhost:3000`
`CodemagicPatchDownloadBaseUrl`	`http://localhost:9100/codemagic-patch`
`CodemagicPatchDeploymentKey`	from `cmpatch deployment list` for your app

Run cmpatch init --server-url http://localhost:3000 from your project root. The command creates one app per platform (do not reuse demo-app-* unless you only need the bundled demo) and links the project. The iOS Simulator can use these localhost URLs directly. For an Android emulator or a USB-connected Android device, keep both URLs above and forward the API and download ports with adb (use -s <serial> if multiple devices are connected):

adb reverse tcp:3000 tcp:3000
adb reverse tcp:9100 tcp:9100

Repeat the forwarding after restarting the device or adb server. The guided demo handles it automatically. The evaluation stack binds only to your laptop's loopback interface, so replacing localhost with a LAN IP does not make it reachable from an iPhone or another machine. For those devices, use a reachable server from the Install guide.

Native setup for bare React Native or the Expo config plugin
Coming from Expo Updates: Migrating from Expo Updates (local PoC path first)
Coming from a CodePush fork: Migrating from CodePush

Optional: watch an update apply (on-device demo)

If you would like to try Patch with a ready-made app, run the guided walkthrough:

cmpatch demo

It uses the evaluation checkout, so you do not need a separate clone, a prior cmpatch login, or manual dependency installation. If you started the stack from your own clone, run the command inside that clone or pass --checkout /path/to/codemagic-patch. Use --platform ios or --platform android to choose a platform explicitly.

The command checks the demo prerequisites, signs you in to the local stack if needed, installs dependencies, and builds and launches a Release app. The first native build can take several minutes. This build boots from its embedded JavaScript bundle, which the OTA update will replace.

Look at the running storefront: its product cards should show "Couldn't load product" / "Invalid product response".
The CLI shows the one-line fix it will make automatically and asks whether to publish it. Approve after you have seen the error. You do not need to edit any source files.
The CLI publishes the JavaScript fix, waits for publication, then backgrounds and returns to the same app. On iOS, Settings briefly appears; on Android, the Home screen appears. The app downloads the update and reloads automatically, without rebuilding or reinstalling the native app.
Confirm that the product cards now load and Add to cart confirms the order. The CLI then offers to open the release in the dashboard.

If automatic app switching fails, follow the CLI's instructions to background the app and bring it back manually. A published release alone does not confirm that the device applied it; check the storefront after it reloads.

For prerequisites, troubleshooting, or the optional walkthrough by hand, see the on-device demo README.

Optional: explore the dashboard

Open http://localhost:8080 and sign in as local-admin@example.com to browse Example Data, including sample releases and metrics. These sample releases are not downloadable. If you ran the demo, open demo-app-ios or demo-app-android and its staging deployment to see the release you published.

If you have an editable repository clone, you can also sign in with cmpatch login --server-url http://localhost:3000 and publish the bundled fixture from its root (it uses the seeded cli-smoke-test deployment so it does not collide with the on-device demo):

cmpatch release create \
  --server-url http://localhost:3000 \
  --app demo-app-ios \
  --deployment cli-smoke-test \
  --bundle-path examples/local-dev/bundles/ios-hermes-v1.zip \
  --target-binary-version 1.0.0 \
  --fingerprint local-dev-fingerprint \
  --release-notes "Local quickstart" \
  --yes

Tear down

cmpatch selfhost local-eval down

The stack's data (database and stored bundles) is kept for the next start; add --delete-data to remove it too. From a clone, the equivalent is docker compose -f docker-compose.dev.yml down -v.

What you just ran

Piece	Local value
Dashboard	`http://localhost:8080`
API	`http://localhost:3000`
Artifact downloads	`http://localhost:9100/codemagic-patch`
Demo apps	`demo-app-ios` / `demo-app-android` (each with `staging`)
Demo deployment keys	`dev_local_ios_deployment_key` / `dev_local_android_deployment_key`
Fixture publish	`demo-app-ios` / `cli-smoke-test` (`dev_local_deployment_key`)

warning

The seeded API token (cm_pat_local-dev-token-change-me-00000001) is for local scripting only. Do not reuse it in production.

Where to go next

Goal	Page
Install and configure the app SDK	Native setup
Confirm update behavior on your app	Verify a test release
Coming from Expo Updates	Migrating from Expo Updates
Coming from a CodePush fork	Migrating from CodePush
Deploy with your own domains	Install

What you need​

1. Start the stack​

2. Try it with your own app​

Optional: watch an update apply (on-device demo)​

Optional: explore the dashboard​

Tear down​

What you just ran​

Where to go next​