Skip to content

Architecture#

A self-hosted BSR runs entirely inside the customer’s infrastructure with no automatic outbound traffic to Buf. This page is for the platform engineers planning the deployment and the security reviewers evaluating its isolation posture.

The diagram below shows the BSR’s main services, their external dependencies, and the OCI image registry that holds plugin and SDK images:

BSR architecture diagram

External dependencies#

A self-hosted BSR depends on three customer-provided services:

  • PostgreSQL for relational data.
  • Redis for caching.
  • Blob storage for module content, generated artifacts, and other large objects.

For the supported versions and capacity sizing, see On-premise deployment with Kubernetes.

Services#

bufd#

The main HTTP/RPC service. The Buf CLI and the BSR web UI both talk to bufd directly, and bufd reaches the external dependencies (PostgreSQL, Redis, blob storage) and every other daemon.

bufd covers:

  • The public BSR API used by the CLI and the web UI.
  • Generated SDK endpoints that serve packages to language tooling (npm install, go get, mvn, and so on).
  • Buf Studio, the in-browser RPC client.
  • Orchestration of remote code generation by handing work to bufsandboxd.

bufsandboxd#

A sandboxed runtime that executes plugin images to generate code. Called only by bufd; never reachable from outside the cluster.

bufpluginsd#

A read-only feed of Buf-managed plugin images, packaged with the BSR release.

bufmodulesd#

A read-only feed of Buf-managed module sources (for example, googleapis, protovalidate), packaged with the BSR release.

buftoolsd#

A read-only feed of pre-built tool images that bufsandboxd invokes during code generation. Default contents include typedoc, doc2go, dotnet-sdk, and maven-jdk.

OCI image registry#

A Buf-shipped OCI registry running inside the cluster. It holds the container images for remote plugins, generated SDKs, and generated documentation. This is part of the BSR install, not a customer-provided dependency.

Request flow#

A typical buf push and a remote-generation pull look like this:

  1. Push. The Buf CLI sends the module to bufd over RPC. bufd validates it, writes the module content to blob storage, records metadata in PostgreSQL, and updates relevant Redis caches.

  2. Pull and generate. A client requests a generated SDK or remote-plugin output from bufd. bufd reads the module from blob storage and PostgreSQL, then asks bufsandboxd to run the plugin. bufsandboxd pulls the plugin image from the OCI image registry (originally fed by bufpluginsd) and any required tool images from buftoolsd, runs the plugin in a sandbox, and returns the generated artifact to bufd.

  3. Serve. bufd returns the artifact to the client and caches it where applicable.

Data egress#

A self-hosted BSR doesn’t send analytics, telemetry, or user data to Buf at runtime. The only outbound traffic to Buf-controlled hosts happens when an administrator triggers it: pulling new release images from us-docker.pkg.dev/buf-images-1 during install or upgrade.

Whether the cluster reaches those hosts at all is up to the operator. A fully air-gapped install is supported by mirroring the BSR release images into customer-controlled infrastructure.