envoyproxy/envoy

envoy-static

envoy-static is the canonical Envoy binary — a statically-linked executable that bundles the proxy core, every in-tree extension, and BoringSSL. It's what people mean when they say "Envoy".

Bazel target

//source/exe:envoy-static

The build target is in source/exe/BUILD. Common build invocation:

bazel build -c opt //source/exe:envoy-static

The output is bazel-bin/source/exe/envoy-static. CI also produces stripped variants and debug symbol files.

Entry point

source/exe/main.cc is intentionally tiny. It hands off to Envoy::MainCommon::main (in main_common.cc) which:

Constructs OptionsImpl from argv (parsing --config-path, --service-cluster, --restart-epoch, --base-id, --concurrency, etc.).
Builds a MainCommonBase, which holds the global signals, real platform impl, and Server::InstanceImpl.
Initialises the server lifecycle.
Runs the main thread's dispatcher until exit.

The stack is:

main()
└── MainCommon::main(argc, argv)
    └── MainCommonBase::run()
        └── Server::InstanceImpl::run()
            └── main thread dispatcher.run()

What's linked in

envoy-static is "static" in the sense that it links in:

The proxy core (source/server/, source/common/).
All extensions enabled by source/extensions/extensions_build_config.bzl. The list is huge: ~70 HTTP filters, ~30 network filters, ~15 cluster types, etc.
Every transport socket, tracer, access logger, stat sink in source/extensions/.
BoringSSL, c-ares, nghttp2, QUICHE, abseil, protobuf, cel-cpp, opencensus, OpenTelemetry, and dozens of other static dependencies.
Architecture-specific compression (zlib, brotli, zstd) and crypto.

The result is a single binary on the order of 100–200 MB unstripped (~20–30 MB stripped) that can run anywhere with a recent glibc.

What's not linked in

The contrib extensions — see envoy-contrib.
Mobile-specific support — see envoy-mobile.

A custom build can opt out of any extension by editing extensions_build_config.bzl (the well-known list EXTENSIONS = [...]). Some users build a slimmer Envoy by stripping extensions they don't need. The macro ENVOY_EXTENSIONS in source/extensions/extensions_metadata.yaml records the set per build.

Distribution

Pre-built binaries are produced by the Envoy release pipeline (see .github/workflows/). They land in:

The envoyproxy/envoy Docker image.
The envoyproxy/envoy-distroless distroless variant.
GitHub releases under envoyproxy/envoy/releases for each tag.
The Linux Foundation–hosted Envoy package archive.

Both envoy-static and envoy-contrib (see below) are published; envoy-static is the default.

Run command

envoy-static -c /path/to/envoy.yaml \
  --service-cluster my-cluster \
  --service-node my-node \
  --concurrency 8 \
  --log-level info

The full flag list comes from OptionsImplPlatformLinux::OptionsImplPlatformLinux plus the parent OptionsImplBase (source/server/options_impl_base.cc) — see also envoy --help.

Lifecycle inside the binary

graph TB
    main[main.cc] --> MC[MainCommon]
    MC --> MCB[MainCommonBase]
    MCB --> Inst[Server::InstanceImpl]
    Inst --> Init[InitManager + Bootstrap]
    Init --> XdsLoop[xDS warming loop]
    XdsLoop --> Ready[Ready]
    Ready --> Workers[Worker dispatch]
    Workers --> Drain[Drain on signal/admin]
    Drain --> Exit[Exit]

See server lifecycle for the full sequence; hot restart covers in-place upgrades.

Useful build configurations

Define / config	Effect
`--config=clang`	Build with clang.
`--config=clang-tsan` / `clang-asan` / `clang-msan`	Sanitizer builds.
`--define=hot_restart=disabled`	Disable hot restart machinery.
`--define=admin_html=disabled`	Strip the HTML admin UI.
`--define=signal_trace=disabled`	Disable libunwind signal trace.
`--define=tcmalloc=gperftools`	Switch malloc implementation.
`--define=wasm=v8`/`wamr`/`wasmtime`/`disabled`	Pick a Wasm engine.

The full set is documented in bazel/README.md.