Firewalls, Proxies and Mirrors

This page lists every host Shorebird talks to, and how to point the Shorebird CLI at an internal mirror when your network can’t reach some of them. To test which hosts your network can reach right now, use the Endpoint Reachability checker. For how Shorebird protects your data and your app’s updates, see Security.

Hosts Shorebird uses

All traffic is HTTPS on port 443.

From your development machine or CI runner

Host	Used for
`api.shorebird.dev`	Every CLI command that talks to Shorebird
`auth.shorebird.dev`	Signing in, and refreshing or exchanging tokens
`console.shorebird.dev`	The web console, in your browser
`download.shorebird.dev`	Flutter and Shorebird engine artifacts
`storage.googleapis.com`	Uploading and downloading release and patch artifacts
`github.com/shorebirdtech/flutter.git`	Cloning Shorebird’s fork of Flutter
`github.com/google/bundletool/releases`	bundletool, for releases and patches on every platform
`github.com/shorebirdtech/shorebird.git`	Installing and upgrading the CLI, and its update check
`pub.dev`	Dart packages for the CLI and Flutter, on install and upgrade

A few of these hosts hand off to others:

download.shorebird.dev redirects every download to storage.googleapis.com.
GitHub serves release downloads, such as bundletool, from release-assets.githubusercontent.com or objects.githubusercontent.com.
shorebird login opens your browser to sign in with Google (accounts.google.com), Microsoft (login.microsoftonline.com), or your company’s SAML identity provider.

download.shorebird.dev, the Flutter fork, bundletool and pub.dev can come from an internal mirror instead. See Using an internal mirror.

From your users’ devices

Host	Used for
`api.shorebird.dev`	Checking for patches
`cdn.shorebird.cloud`	Downloading patches

To check for patches through your own domain, see Using a reverse proxy. For how your app’s requests use the device’s proxy and certificates, see Your users are behind a proxy or VPN.

Behind a corporate proxy

The CLI, and the git and dart commands it runs, use the standard HTTPS_PROXY, HTTP_PROXY and NO_PROXY environment variables. See network/TLS errors behind a proxy.

Gradle doesn’t read those variables, and Android builds download Shorebird’s engine through Gradle. Set Gradle’s own proxy settings too, for example in ~/.gradle/gradle.properties:

systemProp.https.proxyHost=your-proxy-server
systemProp.https.proxyPort=8080

Using an internal mirror

If your machines can reach api.shorebird.dev, auth.shorebird.dev and storage.googleapis.com but must download everything else from an internal mirror (Artifactory, Nexus, or your own server), point Shorebird at the mirror with these environment variables. The first three need Shorebird CLI 1.6.131 or later.

SHOREBIRD_DOWNLOAD_URL replaces https://download.shorebird.dev.
SHOREBIRD_FLUTTER_GIT_URL replaces https://github.com/shorebirdtech/flutter.git.
SHOREBIRD_BUNDLETOOL_URL replaces the URL of the bundletool jar on GitHub releases.
PUB_HOSTED_URL, Dart’s own variable, replaces https://pub.dev.

For example:

export SHOREBIRD_DOWNLOAD_URL=https://artifactory.example.com/artifactory/shorebird
export SHOREBIRD_FLUTTER_GIT_URL=https://git.example.com/mirrors/flutter.git
export SHOREBIRD_BUNDLETOOL_URL=https://artifactory.example.com/artifactory/tools/bundletool-all-1.18.3.jar
export PUB_HOSTED_URL=https://artifactory.example.com/artifactory/api/pub/pub-dev

Set them everywhere the CLI runs, including CI runners, and before you install Shorebird: the install script runs the CLI once, which clones Flutter and downloads its artifacts.

shorebird doctor checks that it can reach the download URL you set, in place of download.shorebird.dev, along with Shorebird’s API, auth, console, storage and CDN hosts. It doesn’t check GitHub, your Git mirror, your bundletool URL or pub.

`SHOREBIRD_DOWNLOAD_URL`

One host serves everything Shorebird’s Flutter downloads: the Dart SDK, Flutter’s engine artifacts, Shorebird’s modified engine, the Maven repository Android builds use, and the tools the CLI uses to build patches. Mirror https://download.shorebird.dev as a single remote repository, and set SHOREBIRD_DOWNLOAD_URL to the URL of that repository, not a folder inside it.

Use https. Android builds fetch the engine from this URL through Gradle, which refuses a plain http Maven repository.
The mirror must follow redirects, since download.shorebird.dev answers every download with a redirect to storage.googleapis.com. Check that your repository is set to follow them.
Shorebird ignores your own FLUTTER_STORAGE_BASE_URL. That variable usually names a mirror of Google’s Flutter artifacts, such as https://storage.flutter-io.cn, which doesn’t have Shorebird’s engine. The CLI sets FLUTTER_STORAGE_BASE_URL to SHOREBIRD_DOWNLOAD_URL for the Flutter it runs, and leaves your own Flutter installation alone.
Flutter prints “Flutter assets will be downloaded from” your mirror’s URL. That’s expected.

`SHOREBIRD_FLUTTER_GIT_URL`

Mirror every branch of https://github.com/shorebirdtech/flutter.git (for example with git clone --mirror) and keep the mirror up to date. Each Shorebird release pins a new commit of it, and --flutter-version looks up its release branches.

The variable is read when the CLI clones a Flutter revision. Revisions it cloned before you set it keep fetching from GitHub. To switch them to the mirror:

for dir in ~/.shorebird/bin/cache/flutter/*/; do
  git -C "$dir" remote set-url origin "$SHOREBIRD_FLUTTER_GIT_URL"
done

`SHOREBIRD_BUNDLETOOL_URL`

Set this to the full URL of the jar, not a folder. The CLI checks the jar’s SHA-256, so the mirror must serve the exact jar the CLI expects: 1.18.3 as of Shorebird 1.6.131, from the bundletool 1.18.3 release. A later Shorebird release may move to a newer bundletool, so check for a checksum error after you upgrade.

What still needs GitHub

The CLI itself is a clone of https://github.com/shorebirdtech/shorebird.git, and there is no variable for that yet. Installing clones it, upgrading fetches it, and every other command run without --json checks it for a newer version. If your machines can’t reach GitHub, clone that repository’s stable branch from a mirror to ~/.shorebird and add ~/.shorebird/bin to your PATH, as the install script does. The update check and shorebird upgrade then use your mirror, since they fetch from the clone’s origin.

Your users are behind a proxy or VPN

In releases built with Flutter 3.47.9 or newer, on iOS, macOS and Android, your app’s patch checks and downloads go through the platform’s own HTTP stack: URLSession on iOS and macOS, HttpURLConnection on Android. They follow the same network rules as the rest of your app:

The device’s system proxy and VPN apply, including a PAC file on iOS and macOS.
On Android, your app’s Network Security Config decides which certificates are trusted. A user-installed CA, such as a TLS-inspecting proxy’s, is trusted only if your config opts in.
On iOS and macOS, the system trust store applies, including roots installed by an MDM profile, and so does App Transport Security.
Certificate pinning in your Network Security Config (<pin-set>) or Info.plist (NSPinnedDomains) applies to these requests only for domains it names, so leave api.shorebird.dev, cdn.shorebird.cloud and your base_url host out unless you mean to pin them. Pinning you do in Dart or in an HTTP library such as OkHttp doesn’t cover these requests.

On Windows and Linux, the updater uses Shorebird’s own HTTP client. In releases built with Flutter 3.47.9 or newer it trusts the operating system’s certificate store. It doesn’t use the system proxy setting; it reads a proxy only from environment variables such as HTTPS_PROXY.

Releases built with an older Flutter use Shorebird’s own HTTP client with a built-in certificate list, so the device’s trust store, including MDM and user-installed roots, doesn’t apply. On iOS, macOS and Android they also don’t use the system proxy.

Using a reverse proxy

To send your app’s patch checks through your own domain, set base_url in shorebird.yaml to a server that forwards every request to https://api.shorebird.dev:

app_id: 8c846e87-1461-4b09-8708-170d78331aca
base_url: https://shorebird-proxy.example.com

Your app sends its patch checks and patch events to base_url. Patches still download from cdn.shorebird.cloud, so devices must be able to reach it. On releases built with Flutter 3.47.9 or newer, an http base_url is blocked by App Transport Security on iOS and macOS unless your Info.plist allows it, and on Android 9 and newer unless your Network Security Config allows cleartext traffic to it. Use https.

The CLI also sends its own API requests in that project to base_url. Its uploads and downloads still use the other hosts it needs. To point the CLI somewhere else, set SHOREBIRD_HOSTED_URL; it takes precedence over base_url. The CLI signs in through https://auth.shorebird.dev unless AUTH_SERVICE_URL names another auth service. shorebird doctor checks the URLs these settings name instead of api.shorebird.dev and auth.shorebird.dev.