Buf Studio#

Buf Studio is a browser-based client that calls live gRPC, Connect, and gRPC-Web APIs using the schemas published to the Buf Schema Registry. Studio is available to any BSR user; private BSR instances additionally surface admin-only features like Agent presets.

Publishing schemas to the BSR gives every authorized developer a ready-made API client: they can discover a method, compose a typed request, and call the live service without installing generated code or checking out the producer repository.

Studio supports unary RPC; streaming endpoints in the method picker are greyed out.

Compose a request#

Pick the Protobuf method to call from the Select Method menu. Studio’s fuzzy search filters across BSR modules, services, and methods.

Set the Target URL to the host of the API to call. Don’t include the service or RPC path; Studio appends them based on the selected method.

Compose the request body in the JSON editor. Studio uses the request message’s schema to provide:

• Autocomplete: trigger suggestions with Ctrl+Space.
• Validation: invalid JSON or invalid field types are underlined inline.
• Documentation: hover a field, or use the Docs tab above the editor, to see the Protobuf comments for that field.

Use the Headers tab for any metadata or authorization headers the request needs.

How Studio reaches your server#

Studio sends requests in one of two ways: directly from the browser, or through Buf Studio Agent. Pick based on what your server speaks:

• Direct browser request: use this if the server speaks Connect or gRPC-Web and is configured to allow CORS from your BSR origin.
• Buf Studio Agent: use this for plain gRPC, or for any server that doesn’t satisfy the browser’s CORS requirements.

Studio doesn’t proxy through Buf servers in either mode.

Direct browser request#

Studio uses the browser’s fetch() API to call the target URL directly. This works with any browser-compatible Protobuf server, including Connect.

sequenceDiagram
    participant St as Studio
    participant S as Server (Target URL)
    St->>S: fetch({request headers and body})
    S->>St: {response headers and body}

The server must respond with a CORS policy that allows requests from your BSR origin:

Access-Control-Allow-Origin: https://buf.build

Access-Control-Allow-Origin: https://your-bsr-instance.example.com

For a concrete server-side example, see the Connect CORS documentation.

Through Buf Studio Agent#

Buf Studio Agent is an open-source proxy bundled with the Buf CLI under buf beta studio-agent. It accepts a browser-friendly request from Studio, reframes it as plain gRPC (or any HTTP shape the target needs), and forwards it to the server. This unlocks two scenarios that direct browser requests can’t reach:

• gRPC servers, since the gRPC wire format isn’t usable from any major browser.
• Servers without browser-friendly CORS, since the Agent ships with the CORS configuration Studio needs.

sequenceDiagram
    participant St as Studio
    participant Sa as Studio Agent
    participant S as Service (Target URL)
    St->>Sa: fetch({request headers and body})
    Sa->>S: {request headers and body}
    S->>Sa: {response headers and body}
    Sa->>St: {response headers and body}

Run a local Agent and point Studio at it:

$ buf beta studio-agent

The default bind is 127.0.0.1:8080; paste http://127.0.0.1:8080 into Studio’s Buf Studio Agent URL field.

buf beta studio-agent is available in Buf CLI v1.6.0 and later. For the full flag set, see Buf Studio Agent flags.

Save and share requests#

Composing a well-formed payload can take real effort, so Studio offers two ways to keep one around:

• Favorites save the target URL, request body, headers, and protocol to your profile when you click the star icon next to a request in History. You must be signed in to use Favorites.
• Share links copy a URL that opens the same request in another user’s Studio (subject to their access).

Authenticated requests#

Cookies#

Some APIs use cookies to authenticate. Enable Include cookies in Studio’s options to attach cookies for the target URL to outgoing requests.

For Studio to send a cookie, it must be set with SameSite=None; Secure. The server also needs to allow credentialed cross-origin requests with two headers:

Access-Control-Allow-Origin: https://buf.build
Access-Control-Allow-Credentials: true

Allowing credentials limits other CORS features (no wildcards on response headers, for example). See the CORS documentation for the full set of constraints.

Private BSR setup#

The features in this section are available on Pro and Enterprise plans only.

Buf Studio Agent presets#

A BSR admin can set preset Agent URLs that show up in Studio’s Buf Studio Agent URL dropdown for everyone on the instance.

Set presets from the admin panel. Each preset accepts an optional name to alias the URL.

Users see the configured presets in the Agent URL dropdown and can select one or enter their own URL:

Long-running Buf Studio Agent#

For SSO-fronted access to internal services, deploy a long-running Agent inside your network. Combined with Studio’s cookie option, this lets authenticated users call any internal Protobuf endpoint from Studio without setting their own auth headers.

For example, route an authenticated user’s request through an SSO-aware edge that injects the auth header, and use the Agent to forward that header on to the target service while preventing the user from setting their own:

The user enables the cookie option to forward their session:

A Dockerfile for a long-running Agent that forwards the auth header from the edge but blocks user-set values:

FROM bufbuild/buf:latest

ENTRYPOINT /usr/local/bin/buf beta studio-agent --timeout=0s \
  --bind=${BUFSTUDIOAGENTD_BIND} \
  --port=${BUFSTUDIOAGENTD_PORT} \
  --origin=${BUFSTUDIOAGENTD_ORIGIN} \
  --log-format=json \
  --forward-header=authorization=authorization \
  --disallowed-header authorization

• --forward-header=<from>=<to> takes a header from the incoming Studio request and forwards it on the outgoing request to the target service. In the example, the edge has already set authorization, and the Agent passes it through.
• --disallowed-header <name> causes the Agent to reject any request that carries this header (HTTP 400) instead of forwarding it to the target. In the example, the user can’t override authorization; if Studio sends it the Agent returns an error and the upstream value from the cookie-validated edge wins.

The resulting flow:

sequenceDiagram
    actor U as User (Studio)
    participant E as Edge to Production Env
    participant Sa as Buf Studio Agent
    participant PS as Production Service (Target URL)
    Note over E: Handles ingress to Production and populates ${auth-header}
    U->>E: {request body and headers};
    rect rgb(191, 223, 255)
        Note right of E: Production Environment
        E->>Sa: {request body and headers + ${auth-header}};
        Sa->>PS: {request body and headers + ${auth-header}};
        PS->>Sa: {response body and headers};
        Sa->>E: {response body and headers};
    end
    E->>U: {response body and headers};

Reference: Buf Studio Agent flags#

Buf Studio Agent ships with the Buf CLI under buf beta studio-agent (v1.6.0 and later). The command runs an HTTP(S) server that forwards requests from Studio to the target URL.

FAQ#

How do I encode a bytes field in Studio?#

The Studio editor accepts the Protobuf JSON format. For a bytes field, encode the value as a Base64 string.