Skip to main content

Local quickstart

Local quickstart

note

These docs cover React Native and Capacitor. Use the selector at the top of the sidebar to switch between them.

Evaluate Codemagic Patch on your machine before you have a domain. Step 1 is a choice: the local stack, or the same machine reached through ngrok so a phone can open it. If you want to see an OTA update before integrating your own app, try the optional on-device demo.

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

1. Start the stack​

You have two evaluation choices. Fully local reaches a simulator, an emulator, or a USB-connected Android device. Local and ngrok reaches a phone before you have a domain.

Fully local​

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. Sign-in is a local one-click login. When it finishes you get:

  • Dashboard at http://localhost:8080. Sign in as local-admin@example.com (prefilled, one click).
  • API at http://localhost:3000.
  • Seeded demo-app-ios and demo-app-android for the on-device demo, plus example releases and metrics

You can now connect your own app, explore the dashboard, or try the demo.

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

Local and ngrok​

npm install -g @codemagic/patch-cli
cmpatch selfhost install --ngrok

You need a free ngrok account, and a GitHub, Bitbucket, or GitLab account for sign-in. No domain, DNS records, certificates, or open ports. The command finds your ngrok address, walks you through the OAuth app with that address filled in, and installs the real server on this machine.

When it finishes you get:

  • Dashboard at https://<unique>.ngrok-free.app. Sign in with the provider you chose, as the administrator email. The first sign-in creates that account.
  • API at https://<unique>.ngrok-free.app.
  • Downloads at https://<unique>.ngrok-free.app/codemagic-patch.

The install prints your <unique> hostname.

Then run cmpatch login and, in your app's folder, cmpatch init.

2. Try it with your own app​

Use these addresses. The ngrok install prints your <unique> hostname. The deployment key comes from cmpatch deployment list after cmpatch init, or from cmpatch-capacitor deployment list.

CodemagicPatchApiUrlCodemagicPatchDownloadBaseUrl
Localhttp://localhost:3000http://localhost:9100/codemagic-patch
ngrokhttps://<unique>.ngrok-free.apphttps://<unique>.ngrok-free.app/codemagic-patch

Where each value goes is in Native setup for React Native and Native setup for Capacitor.

The local stack only answers on this machine. An iOS Simulator can use the localhost URLs directly. For an Android emulator or a USB-connected device, forward the two ports (add -s <serial> when more than one device is connected):

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

Repeat that after the device or adb restarts. Android release builds block plain HTTP. For this local stack only, set android:usesCleartextTraffic="true" on the <application> element in android/app/src/main/AndroidManifest.xml, and remove it before a store build. An ngrok install is HTTPS, so it does not need the port forwards or the cleartext setting.

Optional: watch an update apply (fully local)​

cmpatch demo

This uses the local evaluation stack. It builds a React Native app on a simulator or emulator, publishes one fix, and shows the running app install it. The command says what to look for. It does not run against an ngrok install. For Capacitor, the repository has an example app.

Optional: explore the dashboard (fully local)​

Open http://localhost:8080 and sign in as local-admin@example.com. Have a look around. The sample releases are there to browse. They are not downloadable.

To publish, open a deployment and choose New release. It writes the release create command for that app. Run the command it gives you.

The ngrok dashboard is the https://<unique>.ngrok-free.app address that install printed.

Tear down​

Fully local​

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.

Local and ngrok​

cmpatch selfhost local-eval down does not stop this install. From the checkout the installer keeps (~/.codemagic-patch/selfhost-local/codemagic-patch, or the path you passed as --checkout):

docker compose --project-name codemagic-patch-selfhost --env-file .env.selfhost \
  -f docker-compose.selfhost.yml \
  -f deploy/selfhost/compose.bundled-db.yml \
  -f deploy/selfhost/compose.bundled-storage.yml \
  -f deploy/selfhost/compose.ngrok.yml down

Where to go next​

GoalPage
Install and configure the app SDKNative setup
Confirm update behavior on your appVerify a test release
Coming from Expo UpdatesMigrating from Expo Updates
Coming from a CodePush forkMigrating from CodePush
Deploy with your own domainsInstall