---
title: "Firewalls, Proxies and Mirrors"
description: "The hosts Shorebird uses, and how to run the Shorebird CLI behind a firewall, a proxy, or an internal mirror such as Artifactory."
---

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](/system/endpoint-reachability/) checker. For how Shorebird protects your data and your app’s updates, see [Security](/system/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](#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](#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](#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](/code-push/troubleshooting/#shorebird-commands-fail-with-networktls-connection-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](https://github.com/google/bundletool/releases/tag/1.18.3). 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](https://github.com/shorebirdtech/install) 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](https://developer.android.com/privacy-and-security/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`](/code-push/shorebird-yaml/) to a server that forwards every request to `https://api.shorebird.dev`:

shorebird.yaml

```
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](#from-your-development-machine-or-ci-runner). 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`.