Quick Start

Go from a normal Flutter app to one you can patch over the air. The flow is: add the SDK, build once with the Koolbase engine, ship to the store, then push fixes whenever you need them.

Two modes, two levels of setup

Runtime Bundles (config, flags, assets) work with any Flutter build — just initialize the SDK. VM Patches (compiled Dart fixes) additionally require building with the Koolbase engine. This guide sets up both. If you only want config/flag push, stop after step 2.

Add the SDK

Add koolbase_flutter to your project:

flutter pub add koolbase_flutter

Initialize once at startup

A single Koolbase.initialize() enables both Code Push modes. There's nothing else to wire up — the SDK checks for bundles and stages any matching VM patch in the background.

main.dart

dart

import 'package:koolbase_flutter/koolbase_flutter.dart';

Future<void> main() async {
  WidgetsFlutterBinding.ensureInitialized();

  await Koolbase.initialize(
    KoolbaseConfig(
      baseUrl: 'https://api.koolbase.com',
      publicKey: 'pk_live_...',
      codePushChannel: 'stable',
    ),
  );

  runApp(const MyApp());
}

At this point Runtime Bundles are fully working. For VM Patches, continue.

Build with the Koolbase engine

VM Patches require your release binary to be built with the Koolbase Flutter engine matching your Flutter version. Use koolbase build instead of flutter build:

koolbase build android --release \
  --engine 3.32.0-koolbase.1 \
  --flutter-sdk /path/to/koolbase-engine

This produces your normal release artifact, built on the Koolbase engine and stamped with a build_id that future patches target. On iOS the same command shape applies:

koolbase build ios --release \
  --engine 3.44.4-koolbase.4

See Flutter Versions & Engines for picking the right engine.

Ship that build to the store

Submit the Koolbase-built artifact to the Play Store (and/or App Store) and let it go through normal review. This is a one-time step — once this build is live, you patch it over the air without resubmitting.

Push a fix

When you have a Dart bug fix, recompile your app binary and push a patch against the build that's live. A diff patch (--diff) ships only the bytes that changed — usually tens of kilobytes:

koolbase patch push \
  --app <project_id> \
  --binary ./base/libapp.so \
  --new ./fixed/libapp.so \
  --diff \
  --key ./private.key \
  --platform android \
  --channel stable \
  --rollout 100 \
  --publish

On iOS, author the patch from your fixed Dart source, then sign and publish it in one command:

koolbase patch ios build \
  --source lib/main.dart \
  --app-package myapp \
  --engine 3.44.4-koolbase.4

koolbase patch push-ios \
  --app <project_id> \
  --kbpi myapp_patch.kbpi \
  --binary ./Runner.app/Frameworks/App.framework/App \
  --key ./private.key \
  --channel stable

The release build_id is derived from the binary automatically. Devices running the matching build pick up the patch on their next launch check, download it in the background, and apply it on the following cold launch — verified, and on iOS applied before the app's first frame, so users simply relaunch into the fix.

What happens on the device

On launch, the SDK asks the resolver if a patch exists for this build.
If yes, it downloads the signed patch and stages it — the app keeps running normally this launch.
On the next cold launch, the engine verifies the patch (signature + build_id + reconstructed-target hash) and applies it before any Dart runs.
Your fix is now live. If the patched code fails to boot, the app auto-reverts to the last good version.

Patches apply on the next launch, not instantly

Like Runtime Bundles, a VM patch downloads on one launch and activates on the next. This is what lets the engine verify and apply it safely before your code starts.

Before you push to production

Code push is for bug fixes and tuning, not for shipping major features around store review. Read Store Compliance before pushing to a live app, and start rollouts small — see Rollout & Rollback.

Overview

How It Works