sankofa engine · Sankofa Docs

Flutter OTA requires the Sankofa Flutter engine — a build of the Flutter runtime that can load code patches. sankofa engine manages the local copy of that runtime plus the bundled Flutter SDK the CLI uses to build and patch your app. These commands are Flutter Deploy only; React Native projects don't use them.

bash

sankofa engine <subcommand> [options]

Engine versions

Every Sankofa engine is identified as <flutter-version>+sankofa-<N> — for example 3.44.1+sankofa-2. Your project pins one in sankofa.yaml (engine_version:) and in .sankofa/flutter-version. A patch built against one engine only applies to a baseline built against the same engine, so the pin keeps releases and patches coherent.

`sankofa engine install`

The "do everything for this version" command. Run it once per engine version on a fresh machine. It clones the bundled Sankofa Flutter SDK into ~/.sankofa/flutter/<version>/ (your own flutter on PATH is untouched) and downloads every engine ABI binary into the cache.

bash

sankofa engine install                 # install the project's / latest version
sankofa engine install 3.44.1+sankofa-2
sankofa engine install --skip-engines  # bundled SDK only, skip the per-ABI download
sankofa engine install --force         # re-clone / re-download even if present

[version]string

Engine version to install. Falls back to SANKOFA_ENGINE_VERSION, then the latest published on the CDN.

--local-path <path>path

Use a local sankofa-flutter checkout instead of cloning.

--ref <branch|tag|sha>string

Install a specific git ref (default: the branch tracking the version).

--skip-enginesflag

Install only the bundled Flutter SDK; skip the per-ABI engine binary download.

--forceflag

Re-clone / re-download even if a valid copy already exists.

`sankofa engine upgrade`

The one-command engine bump. Inside a project it resolves the newest published engine, installs its bundled SDK + binaries, and re-pins the project (sankofa.yaml engine_version: and .sankofa/flutter-version). Subsequent releases and patches build with the new engine automatically.

bash

sankofa engine upgrade                    # upgrade to the latest published engine + re-pin
sankofa engine upgrade --check            # report what would change; install nothing
sankofa engine upgrade --version 3.44.1+sankofa-2   # target a specific version
sankofa engine upgrade --force

--version <version>string

Target a specific engine version instead of the latest.

--checkflag

Report what would change (re-pin, install) without doing it.

--forceflag

Re-clone / re-download even if already present.

`sankofa engine list`

Show what's cached locally and everything the registry offers, with a ●/○ marker for cached vs. downloadable.

bash

sankofa engine list
sankofa engine list --flutter-version 3.44.1
sankofa engine list --target android
sankofa engine list --modified-only     # only Sankofa-modified engine builds

--flutter-version <version>string

Filter to one Flutter version.

--target <android|ios>string

Filter to one target platform.

--modified-onlyflag

Only show Sankofa-modified engine builds (hide vanilla baselines).

`sankofa engine download`

Pull specific engine binaries into the cache — handy for priming a CI cache before a build.

bash

sankofa engine download                            # for the active flutter --version
sankofa engine download --flutter-version 3.44.1 --target android
sankofa engine download --target ios --abi device-arm64
sankofa engine download --force                    # re-download over a cache hit

--flutter-version <version>string

Flutter version. Defaults to the active flutter --version.

--target <android|ios>string

Target platform. Defaults to both.

--abi <abi>string

Specific ABI (e.g. arm64-v8a, device-arm64). Defaults to every ABI for the target.

--forceflag

Re-download even when a valid cache hit exists.

`sankofa engine verify`

Re-hash every cached engine binary and compare against the registry. Use it when a build complains about engine integrity, or in CI to assert the cache is trustworthy. Exits non-zero if any binary fails.

bash

sankofa engine verify

A mismatch prints the exact re-download command, for example:

bash

sankofa engine download --force --target android --abi arm64-v8a

`sankofa engine path`

Print the cache root (default ~/.sankofa/engines, or $SANKOFA_HOME/engines). Useful in shell scripts.

bash

sankofa engine path
export ENGINE_CACHE="$(sankofa engine path)"

Cache location & environment

Path / variable	Meaning
`~/.sankofa/engines/`	Cached engine binaries (`libflutter.so` / `Flutter.framework`).
`~/.sankofa/flutter/<version>/`	Bundled Sankofa Flutter SDK per version.
`SANKOFA_HOME`	Override the cache root (default `~/.sankofa`). Used by CI/tests to isolate caches.
`SANKOFA_ENGINE_VERSION`	Override the resolved engine version.

`sankofa engine register` — internal only

How the trust check works

At sankofa release, the CLI hashes the libflutter.so embedded in your build and looks it up in the registry. If it isn't a known Sankofa engine, the release is refused (a vanilla-Flutter binary can't load patches, so publishing it would strand every device on patch download). If you hit this, install the Sankofa engine and rebuild — see Troubleshooting.

Configuration & auth — where the engine pin lives.
sankofa patch — why engine and baseline must match.
Troubleshooting — engine mismatch and skip-check recipes.