envoyproxy/envoy

envoy-mobile

Envoy Mobile is the same Envoy networking core, packaged as a client-side HTTP / QUIC library for iOS, Android, Python, and C++. It lives at mobile/ — formerly a separate repository (envoyproxy/envoy-mobile), now merged into the main repo.

What it is

Envoy Mobile gives mobile applications:

A single networking stack across iOS and Android (same code, same configuration, same observability).
HTTP/2 and HTTP/3 client support (no native iOS QUIC restriction; Envoy Mobile ships its own QUIC).
Connection migration on network changes — important on mobile.
Stats and tracing flowing through the standard Envoy stats and tracing sinks.
Configurable filter chains so app-specific HTTP behaviour (auth, retry, redirects, instrumentation) can be implemented as Envoy filters running on-device.

Layout

mobile/
├── library/                    # Envoy as a library
│   ├── cc/                     # C++ entry points
│   ├── jni/                    # JNI glue for Android
│   ├── java/, kotlin/          # Android API
│   ├── objective-c/, swift/    # iOS API
│   ├── python/                 # Python bindings
│   └── common/                 # Shared C++ used by all platforms
├── envoy_build_config/         # Mobile-specific extension subset
├── examples/                   # Sample apps in Kotlin / Swift / Python
├── docs/                       # User-facing documentation source
├── ci/                         # Mobile CI workflows
├── tools/                      # Local dev tools
└── test/                       # Tests

The mobile-specific extension subset is configured in mobile/envoy_build_config/ — most server-side extensions (admin, hot restart, listener manager) are stripped, leaving the client-relevant subset.

Build

# Android AAR
bazel build //library/kotlin/io/envoyproxy/envoymobile:envoy_aar

# iOS framework
bazel build //library/swift/EnvoyMobile.swiftpackage

# Python wheel
bazel build //library/python:envoy_engine

The mobile build is its own bazel WORKSPACE-style root because the cross-compilation toolchains differ from server builds.

API surface

Kotlin (Android)

val engine = AndroidEngineBuilder(application)
  .addLogLevel(LogLevel.INFO)
  .addPlatformFilter("retry", ::RetryFilter)
  .build()

val client = engine.streamClient()
client.newStreamPrototype()
  .setOnResponseHeaders { headers, _, _ -> /* ... */ }
  .setOnResponseData { data, end, _ -> /* ... */ }
  .start()
  .sendHeaders(RequestHeadersBuilder(...).build(), false)
  .sendData(...)
  .close(...)

Swift (iOS)

let engine = try EngineBuilder()
  .addLogLevel(.info)
  .addPlatformFilter(name: "retry") { RetryFilter() }
  .build()

let client = engine.streamClient()
client.newStreamPrototype()
  .setOnResponseHeaders { headers, _, _ in /* ... */ }
  .setOnResponseData { data, end, _ in /* ... */ }
  .start()
  .sendHeaders(...)
  .close(...)

The two APIs are kept identical in shape so cross-platform code is straightforward.

Platform filters

A mobile-specific feature: filters can be implemented in Kotlin or Swift, not just C++. The platform filter API lets the host language register a filter that intercepts the same callbacks an in-process C++ filter would. Implementation: mobile/library/common/extensions/filters/http/platform_bridge/.

This is how Envoy Mobile lets app authors plug in arbitrary auth / retry / instrumentation logic without writing C++.

Differences from server Envoy

No listener manager / no acceptor — mobile is client-only.
No admin server.
No hot restart.
DNS resolution goes through the platform's resolver, not c-ares (configurable).
Network monitor: registers for OS-level network changes (Wi-Fi → cellular) and proactively migrates QUIC connections.
A subset of extensions is linked.

Stats and tracing

Mobile feeds the same stats and tracing machinery. The default metrics_service sink doesn't make sense on a phone, but the host app can install its own sink that uploads aggregated metrics on a schedule. See mobile/library/common/network/ for the network observability hooks.

Use cases

Lyft, Pinterest, and Reddit publicly use Envoy Mobile. The original use-case at Lyft was unifying mobile observability with server observability.
Custom retry / connection migration policies that aren't possible to express in iOS' URLSession or Android's OkHttp.
HTTP/3 on iOS without waiting for Apple to expose it broadly.