Spike: Flutter code push on Stacklift
Question. Can Stacklift be the server and dashboard for Shorebird-style Flutter code push (Dart code updated over the air: downloaded when the app opens, applied on the next launch), without building a Flutter engine fork ourselves?
Verdict: technically yes, but do not build it on Shorebird's engine without their written permission. The Terms (read in full; see Terms of Service on this page) neither forbid nor license running Shorebird's builds against another server. That is a grey zone, and the engine binaries, the iOS interpreter and the CLI's artifact downloads all come from Shorebird. Not legal advice.
How this was done: reading Shorebird's open-source repositories (shorebirdtech/shorebird, shorebirdtech/updater) and docs. Nothing was executed yet. Facts marked *read* come from source files; *unverified* means not yet read or run.
What Shorebird is made of
| Piece | Open source? | Role |
|---|---|---|
| Flutter engine/framework fork | Fork of Flutter (BSD) | Contains the updater and, on iOS, an interpreter for patched code |
updater (Rust) | Yes, Apache-2.0 or MIT | Runs inside the app: asks the server for a patch, downloads, verifies, applies on next boot |
shorebird_cli (Dart) | Yes, Apache-2.0 or MIT | shorebird release / shorebird patch: builds with the fork, computes the diff, uploads |
| Protocol and client packages | Yes | The API contract between CLI/app and server |
| Server (api.shorebird.dev) | Not in the repo that was read | The part Stacklift would replace |
Verified: the server can be replaced
All *read* from source:
- App to server (2 endpoints).
POST {base_url}/api/v1/patches/checkandPOST {base_url}/api/v1/patches/events.base_urlis a plain key in the app'sshorebird.yaml, so each app can point at any server. - Check request:
app_id, channel, release_version, platform, arch, client_id, plus optionalhost_bundle_id, host_version, current_patch_number. - Check response:
patch_available, optionalpatch {number, hash, download_url, hash_signature?}, optionalrolled_back_patch_numbers. - Events:
{"event": {type, app_id, arch, client_id, patch_number, platform, release_version, timestamp, message, ...}}; only a 2xx matters. - Download: plain
GETofdownload_url(withRangeresume). The file is zstd-compressedbipatchdata; the server only stores and serves it. - Behaviour matches what you want. The patch is downloaded in the background, verified, and takes effect when the engine next boots. A patch that fails to start falls back to the last good one.
- CLI to server.
SHOREBIRD_HOSTED_URLoverrides the API address, andSHOREBIRD_DOWNLOAD_URLoverrides where engine artifacts come from. - CLI auth is shimmable. An API key is sent as
Authorization: Bearer sb_api_…and "the server validates it on every request", so a server can accept its own keys with that prefix. - Signing is simple and the server holds no private key. The developer signs; the server just relays
hash_signature. Scheme: RSASSA-PKCS1-v1_5 with SHA-256 over the ASCII hex hash string; the public key is base64 DER RSA inpatch_public_key. This is RSA, not Ed25519, so Stacklift's existing signer cannot be reused for patches.
CLI-facing API a compatible server must implement (about 20 endpoints)
GET /users/me · GET/POST /apps, GET /apps/{id} · GET/POST /apps/{id}/channels · POST /apps/{id}/releases, GET …/releases, PATCH …/releases/{id} · POST/GET …/releases/{id}/artifacts (multipart, then upload to a returned URL, resumable PUT in 8 MiB chunks) · POST /apps/{id}/patches, POST …/patches/{id}/artifacts · POST /apps/{id}/patches/promote · PUT/POST …/patches/{id}/rollout|rollback|rollforward · GET /apps/{id}/signing-key. Organizations, enterprises, billing, service accounts and metrics endpoints exist but are not needed for a first version.
How it maps onto Stacklift
| Shorebird | Stacklift |
|---|---|
| app | Project |
release (version, Flutter revision) | Release (release_version becomes the runtime-version key) |
| release artifacts (aab / ipa / per-arch libapp) | Artifact, hosted (new kind; these are large binaries) |
| patch + patch artifacts | New: Patch, PatchArtifact (number per release, arch, hash, signature, rollout %) |
| channel, promote, rollout %, rollback | Channels, deployments, rollouts, rollbacks (already built) |
patch install events, client_id | UpdateEvent, device counts (already built) |
The dashboard side (rollouts, rollback, per-version devices, audit) is the part already done. New work: patch models, about 20 endpoints, an sb_api_ key shim, RSA key handling, large-file storage, and patch pages in the dashboard. Rough estimate: 2 to 3 weeks.
Terms of Service (read in full)
Source: Shorebird Code Push Terms of Service, "Last updated and Effective as of August 15th, 2025" (shorebird.dev/terms). Paraphrased; section letters are theirs.
- There is no clause that bans competing services, self-hosting or reverse engineering of Shorebird. The only reverse-engineering sentence (D) is a promise by Shorebird not to reverse engineer *your* app.
- But the licence is narrow (E). You get a licence to access, download, install and use "the Services", *solely during the applicable term of Your use of the Services*, and to distribute apps built with them without distributing the Services themselves. It belongs to an account holder who accepts the Terms and pays (F).
- Everything else is reserved (I). Shorebird owns the Services, software and materials; you may not copy, modify, distribute or make derivative works of materials accessible on the Service, and any use not expressly permitted is "strictly prohibited". Shorebird's own engine binaries and CLI downloads are served from its hosts, so using them *without* using the hosted Service is not clearly covered.
- They can change or stop it at any time (H), with or without notice, and terminate an account at their sole discretion (G). All your apps and data are deleted on termination.
- Beta (B). The Services are described as beta, "a work in progress".
- Other limits that matter for a third party: no automated systems that send more requests than a human browser would (E); no bypassing restrictions or deciphering transmissions to and from their servers (G); a login may be used by one person only (C).
What the Terms do not cover: the open-source repositories carry their own licences (updater and CLI: Apache-2.0 or MIT; the Flutter fork: BSD-3-Clause). Those licences let anyone use that *source*. They do not say anything about Shorebird's prebuilt binaries, and the Terms above apply to those.
What is and is not open source (read)
| Piece | Public? |
|---|---|
updater (Rust), shorebird CLI, protocol and client packages | Yes, Apache-2.0 or MIT |
flutter fork | Yes, BSD-3-Clause |
engine fork | Yes, BSD-3-Clause, but the repository is archived (read-only) |
| The server behind api.shorebird.dev | No public repository found |
| The iOS interpreter | No public repository found among the roughly 30 of 36 listed; not confirmed either way |
Prebuilt engine artifacts (download.shorebird.dev) | Downloadable, but covered by the Terms, not an open-source licence |
So a fully independent stack (our own server *and* our own engine builds) would be legal to build from the open-source code, but you would build and host the patched engine for every Flutter version and platform yourself, and the iOS interpreter may not be available as source.
Blockers (answer these before building)
- Permission to use Shorebird's binaries with another server. Not forbidden, not licensed. Ask in writing (contact@shorebird.dev, the address the Terms give): (a) may customers run Shorebird's CLI and engine builds against a third-party server? (b) may the engine artifacts be mirrored? (c) is the iOS interpreter source available under an open-source licence? A "no" or no answer means: do not build on their binaries.
- Protocol drift. The CLI sends an
x-versionheader and the server can answer426to force an upgrade, so the contract changes as Shorebird changes it. A compatible server is a permanent catch-up job. The exact JSON of the release and patch models has not been read yet (*unverified*).
Other risks
- iOS. Patches run in Shorebird's custom interpreter, only on physical arm64 devices and only in release builds. Stacklift cannot touch that; it all comes from their engine.
- Storage cost.
shorebird patchdownloads the original release binary to diff against it, so Stacklift must store every release's aab/ipa, unlike the current "record only" store builds. - Apple and Google policy. Patches must not change the primary purpose of the app (App Store Guideline 3.3.2).
Alternatives if blocker 1 is a no
- Own engine fork + updater. Months of work, re-ported for every Flutter release. The Rust updater is permissively licensed and reusable, but the iOS interpreter is the hard part.
- Config and asset updates only (already built): no Dart code changes.
Recommended next step
- Send the three questions above to Shorebird and wait for an answer in writing.
- Only if the answer is yes, a throwaway proof on Android only: a minimal fake server (check, events, and the CLI endpoints in memory), install Shorebird's CLI, point it at the fake server with
SHOREBIRD_HOSTED_URL, runshorebird release androidandshorebird patch androidon a Flutter app, install on an emulator, and watch the patch apply on the second launch. This proves the whole chain before any Stacklift schema or UI work. It downloads Shorebird's CLI and its Flutter fork (several GB).
Sources: Code Push Terms of Service (Aug 15, 2025), shorebirdtech repositories, shorebirdtech/shorebird, shorebirdtech/updater, Shorebird FAQ, iOS beta announcement.