envoyproxy/envoy

Getting started

This page covers how to build, test, and run Envoy from source. The exhaustive build documentation is in bazel/README.md. The user-facing install guide lives at envoyproxy.io/docs/envoy/latest/start/start.

Prerequisites

Envoy requires:

A modern Linux, macOS, or Windows host. Linux x86_64 is the most heavily exercised target.
Bazelisk installed as bazel. The required Bazel version is pinned in .bazelversion (currently 7.7.1).
A C++20-capable toolchain. The repo also ships a hermetic Clang toolchain that Bazel will download for you when you pass --config=clang.
python3, git, curl, unzip, autoconf, libtool, patch. On Ubuntu the canonical package list is in bazel/README.md.
~50 GB of free disk for a clean build cache.

A pre-baked container with everything installed is published as envoyproxy/envoy-build-ubuntu. The ci/ directory has scripts that drive it; see ci/README.md.

Cloning

git clone https://github.com/envoyproxy/envoy.git
cd envoy

The main branch is what is built and tested in CI; release branches live as release/v1.X. The current development version is recorded in VERSION.txt.

Building the binary

The two production targets are:

# envoy-static: the standard binary (extensions in source/extensions/).
bazel build -c opt //source/exe:envoy-static

# envoy-static (contrib): adds extensions from contrib/ as well.
bazel build -c opt //contrib/exe:envoy-static

-c opt selects the optimized build configuration. For day-to-day iteration use -c dbg or -c fastbuild. For sanitizer builds use --config=asan, --config=tsan, --config=msan (definitions in .bazelrc).

The resulting binary is bazel-bin/source/exe/envoy-static. It is statically linked except for libc.

Running

./bazel-bin/source/exe/envoy-static -c configs/envoyproxy_io_proxy.yaml

configs/ contains a handful of canonical configurations. The minimum useful config is a Bootstrap message in YAML.

Frequently-used flags (full list in source/server/options_impl.cc):

Flag	Effect
`-c, --config-path PATH`	Bootstrap file path (YAML/JSON/protobuf-text)
`--config-yaml STR`	Inline YAML overrides merged onto `--config-path`
`--mode {serve,validate,init_only}`	Run, validate config and exit, or initialize but don't accept connections
`--concurrency N`	Number of worker threads (default: physical CPUs)
`--base-id ID`	Hot-restart base ID (must be unique per Envoy on the host)
`--restart-epoch N`	Hot-restart epoch; the new process passes `N+1`
`--admin-address-path PATH`	Write the admin listener address to this path on startup
`--log-level {trace,debug,info,warn,error,critical}`	Global log level
`--component-log-level COMP:LEVEL,...`	Per-subsystem log overrides
`--cpuset-threads`	Honour cgroup cpuset for `--concurrency` default

Testing

Envoy's test suite is built as Bazel test targets. Common idioms:

# Run all unit tests.
bazel test //test/...

# Run a single test target.
bazel test //test/common/http:conn_manager_impl_test

# Match by name.
bazel test //test/common/http:conn_manager_impl_test --test_filter=HttpConnectionManagerImplTest.NormalRequest

# Run integration tests for one filter.
bazel test //test/extensions/filters/http/jwt_authn/...

# Run with a sanitizer.
bazel test --config=asan //test/common/http/...

# Run a fuzz test.
bazel test --config=asan-fuzzer //test/common/json:json_sanitizer_fuzz_test

Test infrastructure lives in test/test_common/ and test/integration/. Mock implementations of all public interfaces live in test/mocks/. See Testing for details.

Code formatting

Envoy enforces formatting via clang-format and a set of repo-specific checks:

# Check formatting (read-only).
tools/code_format/check_format.py check

# Fix formatting in place.
tools/code_format/check_format.py fix

# A fast wrapper that figures out what changed.
./tools/local_fix_format.sh

The .clang-format and .clang-tidy files at the repo root encode the canonical style. Pre-commit hooks are in support/ — see support/README.md.

Development containers

Two ready-to-use environments are checked in:

.devcontainer/ — VS Code dev container backed by envoyproxy/envoy-build-ubuntu.
tools/vscode/ — local VS Code launch and IntelliSense configuration. See tools/vscode/README.md.

For coverage builds and benchmarking, see bazel/PPROF.md and test/coverage.yaml.