Markdown

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

PieceOpen source?Role
Flutter engine/framework forkFork of Flutter (BSD)Contains the updater and, on iOS, an interpreter for patched code
updater (Rust)Yes, Apache-2.0 or MITRuns inside the app: asks the server for a patch, downloads, verifies, applies on next boot
shorebird_cli (Dart)Yes, Apache-2.0 or MITshorebird release / shorebird patch: builds with the fork, computes the diff, uploads
Protocol and client packagesYesThe API contract between CLI/app and server
Server (api.shorebird.dev)Not in the repo that was readThe 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/check and POST {base_url}/api/v1/patches/events. base_url is a plain key in the app's shorebird.yaml, so each app can point at any server.
  • Check request: app_id, channel, release_version, platform, arch, client_id, plus optional host_bundle_id, host_version, current_patch_number.
  • Check response: patch_available, optional patch {number, hash, download_url, hash_signature?}, optional rolled_back_patch_numbers.
  • Events: {"event": {type, app_id, arch, client_id, patch_number, platform, release_version, timestamp, message, ...}}; only a 2xx matters.
  • Download: plain GET of download_url (with Range resume). The file is zstd-compressed bipatch data; 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_URL overrides the API address, and SHOREBIRD_DOWNLOAD_URL overrides 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 in patch_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

ShorebirdStacklift
appProject
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 artifactsNew: Patch, PatchArtifact (number per release, arch, hash, signature, rollout %)
channel, promote, rollout %, rollbackChannels, deployments, rollouts, rollbacks (already built)
patch install events, client_idUpdateEvent, 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)

PiecePublic?
updater (Rust), shorebird CLI, protocol and client packagesYes, Apache-2.0 or MIT
flutter forkYes, BSD-3-Clause
engine forkYes, BSD-3-Clause, but the repository is archived (read-only)
The server behind api.shorebird.devNo public repository found
The iOS interpreterNo 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)

  1. 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.
  2. Protocol drift. The CLI sends an x-version header and the server can answer 426 to 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 patch downloads 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.
  1. Send the three questions above to Shorebird and wait for an answer in writing.
  2. 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, run shorebird release android and shorebird patch android on 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.