Skip to content

Releases: sudorandom/protodocs

Release list

v0.2.2

v0.2.2 Latest
Latest

Choose a tag to compare

View all tags
@sudorandom sudorandom released this 12 Sep 10:59
v0.2.2
fe8a0c8
This commit was created on GitHub.com and signed with GitHub’s verified signature.
GPG key ID: B5690EEEBB952194
Verified
Learn about vigilant mode.

0.2.2 (2026-09-12)

Bug Fixes

Installation

Choose the download that matches how you want to use ProtoDocs:

Artifact Platform Description
protodocs-desktop-darwin-universal.dmg macOS (Intel + Apple Silicon) Desktop app — drag to Applications
protodocs-desktop-windows-amd64.zip Windows x64 Desktop app — extract and run ProtoDocs.exe
protodocs-desktop-linux-amd64.tar.gz Linux x64 Desktop app — extract and run ProtoDocs
protodocs-cli-darwin-arm64.tar.gz macOS Apple Silicon CLI binary
protodocs-cli-darwin-amd64.tar.gz macOS Intel CLI binary
protodocs-cli-linux-arm64.tar.gz Linux ARM64 CLI binary
protodocs-cli-linux-amd64.tar.gz Linux x64 CLI binary
protodocs-cli-windows-amd64.zip Windows x64 CLI binary
protodocs-static.tar.gz Any web host Static HTML/JS bundle for self-hosting

Desktop App

The desktop app is the easiest way to browse .proto schemas locally — no server required.

Quick Start

  1. Download the .dmg (macOS), .zip (Windows), or .tar.gz (Linux) from the assets below.
  2. Install / extract the app.
  3. Launch ProtoDocs.
  4. At the schema loader, either:
    • Drag & drop a compiled descriptor file (.binpb or .pb) onto the window.
    • Click Open File and select your descriptor file.
    • Enter a reflection URL to connect to a live gRPC / Connect server with reflection enabled.
    • Click Load Demo to explore the built-in Eliza sample schema.

Generating a descriptor file from your .proto sources:

# Using buf:
buf build -o my-api.binpb

# Using protoc:
protoc --descriptor_set_out=my-api.binpb --include_imports your_file.proto

⚠️ macOS: "App is damaged" / Gatekeeper warning

The desktop builds are not code-signed or notarized. Code signing requires an Apple Developer account ($99/year), which this project doesn't have. macOS Gatekeeper will therefore block the app on first launch with a message like "ProtoDocs is damaged and can't be opened" or "ProtoDocs cannot be opened because the developer cannot be verified."

To open the app anyway:

Option A — Right-click method (recommended, one-time):

  1. In Finder, right-click (or Control-click) ProtoDocs.app.
  2. Choose Open from the context menu.
  3. Click Open in the confirmation dialog.

After doing this once, macOS remembers the exception and the app opens normally in the future.

Option B — Remove the quarantine attribute via Terminal:

xattr -dr com.apple.quarantine /Applications/ProtoDocs.app

This strips the quarantine flag entirely. Run it once after moving the app to /Applications.

CLI

# Run directly (no install needed):
go run github.com/sudorandom/protodocs/cmd/protodocs@latest [descriptor-files...]

# Or install permanently:
go install github.com/sudorandom/protodocs/cmd/protodocs@latest

# Serve a local descriptor file with proxy enabled:
protodocs --proxy my-api.binpb

# Connect to a live reflection server:
protodocs --reflection-url https://my-service.example.com

# Specify listen address:
protodocs --addr 127.0.0.1:9090 my-api.binpb

Self-Hosted Static Site

Extract protodocs-static.tar.gz to any static web host (Nginx, S3, GitHub Pages, Netlify, …):

tar -xzf protodocs-static.tar.gz -C /var/www/html/protodocs

Add a config.yaml in the web root to point at your descriptor files:

title: "My API Docs"
descriptor_files:
  - "/my-api.binpb"

Docker

docker run -d -p 8080:80 sudorandom/protodocs:latest
# Then open http://localhost:8080

Changelog

Installation

Choose the download that matches how you want to use ProtoDocs:

Artifact Platform Description
protodocs-desktop-darwin-universal.dmg macOS (Intel + Apple Silicon) Desktop app — drag to Applications
protodocs-desktop-windows-amd64.zip Windows x64 Desktop app — extract and run ProtoDocs.exe
protodocs-desktop-linux-amd64.tar.gz Linux x64 Desktop app — extract and run ProtoDocs
protodocs-cli-darwin-arm64.tar.gz macOS Apple Silicon CLI binary
protodocs-cli-darwin-amd64.tar.gz macOS Intel CLI binary
protodocs-cli-linux-arm64.tar.gz Linux ARM64 CLI binary
protodocs-cli-linux-amd64.tar.gz Linux x64 CLI binary
protodocs-cli-windows-amd64.zip Windows x64 CLI binary
protodocs-static.tar.gz Any web host Static HTML/JS bundle for self-hosting

Desktop App

The desktop app is the easiest way to browse .proto schemas locally — no server required.

Quick Start

  1. Download the .dmg (macOS), .zip (Windows), or .tar.gz (Linux) from the assets below.
  2. Install / extract the app.
  3. Launch ProtoDocs.
  4. At the schema loader, either:
    • Drag & drop a compiled descriptor file (.binpb or .pb) onto the window.
    • Click Open File and select your descriptor file.
    • Enter a reflection URL to connect to a live gRPC / Connect server with reflection enabled.
    • Click Load Demo to explore the built-in Eliza sample schema.

Generating a descriptor file from your .proto sources:

# Using buf:
buf build -o my-api.binpb

# Using protoc:
protoc --descriptor_set_out=my-api.binpb --include_imports your_file.proto

⚠️ macOS: "App is damaged" / Gatekeeper warning

The desktop builds are not code-signed or notarized. Code signing requires an Apple Developer account ($99/year), which this project doesn't have. macOS Gatekeeper will therefore block the app on first launch with a message like "ProtoDocs is damaged and can't be opened" or "ProtoDocs cannot be opened because the developer cannot be verified."

To open the app anyway:

Option A — Right-click method (recommended, one-time):

  1. In Finder, right-click (or Control-click) ProtoDocs.app.
  2. Choose Open from the context menu.
  3. Click Open in the confirmation dialog.

After doing this once, macOS remembers the exception and the app opens normally in the future.

Option B — Remove the quarantine attribute via Terminal:

xattr -dr com.apple.quarantine /Applications/ProtoDocs.app

This strips the quarantine flag entirely. Run it once after moving the app to /Applications.

CLI

# Run directly (no install needed):
go run github.com/sudorandom/protodocs/cmd/protodocs@latest [descriptor-files...]

# Or install permanently:
go install github.com/sudorandom/protodocs/cmd/protodocs@latest

# Serve a local descriptor file with proxy enabled:
protodocs --proxy my-api.binpb

# Connect to a live reflection server:
protodocs --reflection-url https://my-service.example.com

# Specify listen address:
protodocs --addr 127.0.0.1:9090 my-api.binpb

Self-Hosted Static Site

Extract protodocs-static.tar.gz to any static web host (Nginx, S3, GitHub Pages, Netlify, …):

tar -xzf protodocs-static.tar.gz -C /var/www/html/protodocs

Add a config.yaml in the web root to point at your descriptor files:

title: "My API Docs"
descriptor_files:
  - "/my-api.binpb"

Docker

docker run -d -p 8080:80 sudorandom/protodocs:latest
# Then open http://localhost:8080

Changelog

Installation

Choose the download that matches how you want to use ProtoDocs:

Artifact Platform Description
protodocs-desktop-darwin-universal.dmg macOS (Intel + Apple Silicon) Desktop app — drag to Applications
protodocs-desktop-windows-amd64.zip Windows x64 Desktop app — extract and run ProtoDocs.exe
protodocs-desktop-linux-amd64.tar.gz Linux x64 Desktop app — extract and run ProtoDocs
protodocs-cli-darwin-arm64.tar.gz macOS Apple Silicon CLI binary
protodocs-cli-darwin-amd64.tar.gz macOS Intel CLI binary
protodocs-cli-linux-arm64.tar.gz Linux ARM64 CLI binary
protodocs-cli-linux-amd64.tar.gz Linux x64 CLI binary
protodocs-cli-windows-amd64.zip Windows x64 CLI binary
protodocs-static.tar.gz Any web host Static HTML/JS bundle for self-hosting

Desktop App

The desktop app is the easiest way to browse .proto schemas locally — no server required.

Quick Start

  1. Download the .dmg (macOS), .zip (Windows), or .tar.gz (Linux) from the assets below.
  2. Install / extract the app.
  3. Launch ProtoDocs.
  4. At the schema loader, either:
    • Drag & drop a compiled descriptor file (.binpb or .pb) onto the window.
    • Click Open File and select your descriptor file.
    • Enter a reflection URL to connect to a live gRPC / Connect server with reflection enabled.
    • Click Load Demo to explore the built-in Eliza sample schema.

Generating a descriptor file from your .proto sources:

# Using buf:
buf build -o my-api.binpb

# Using protoc:
protoc --descriptor_set_out=my-api.binpb --include_imports your_file.proto

⚠️ macOS: "App is damaged" / Gatekeeper warning

The desktop builds are not code-signed or notarized. Code signing requires an Apple Developer account ($99/year), which this project doesn't have. macOS Gatekeeper will therefore block the app on first launch with a message like "ProtoDocs is damaged and can't be opened" or "ProtoDocs cannot be opened because the developer cannot be verified."

To open the app anyway:

Option A — Right-click method (recommended, one-time):

  1. In Finder, right-click (or Control-click) ProtoDocs.app.
  2. Choose Open from the context menu....
Read more
Assets 12
Loading

v0.2.1

v0.2.1

Choose a tag to compare

View all tags
@sudorandom sudorandom released this 12 Sep 07:39
v0.2.1
3877f89
This commit was created on GitHub.com and signed with GitHub’s verified signature.
GPG key ID: B5690EEEBB952194
Verified
Learn about vigilant mode.

0.2.1 (2026-09-12)

Bug Fixes

  • conn points on vertical graph layout (7716bb7)

Installation

Choose the download that matches how you want to use ProtoDocs:

Artifact Platform Description
protodocs-desktop-darwin-universal.dmg macOS (Intel + Apple Silicon) Desktop app — drag to Applications
protodocs-desktop-windows-amd64.zip Windows x64 Desktop app — extract and run ProtoDocs.exe
protodocs-desktop-linux-amd64.tar.gz Linux x64 Desktop app — extract and run ProtoDocs
protodocs-cli-darwin-arm64.tar.gz macOS Apple Silicon CLI binary
protodocs-cli-darwin-amd64.tar.gz macOS Intel CLI binary
protodocs-cli-linux-arm64.tar.gz Linux ARM64 CLI binary
protodocs-cli-linux-amd64.tar.gz Linux x64 CLI binary
protodocs-cli-windows-amd64.zip Windows x64 CLI binary
protodocs-static.tar.gz Any web host Static HTML/JS bundle for self-hosting

Desktop App

The desktop app is the easiest way to browse .proto schemas locally — no server required.

Quick Start

  1. Download the .dmg (macOS), .zip (Windows), or .tar.gz (Linux) from the assets below.
  2. Install / extract the app.
  3. Launch ProtoDocs.
  4. At the schema loader, either:
    • Drag & drop a compiled descriptor file (.binpb or .pb) onto the window.
    • Click Open File and select your descriptor file.
    • Enter a reflection URL to connect to a live gRPC / Connect server with reflection enabled.
    • Click Load Demo to explore the built-in Eliza sample schema.

Generating a descriptor file from your .proto sources:

# Using buf:
buf build -o my-api.binpb

# Using protoc:
protoc --descriptor_set_out=my-api.binpb --include_imports your_file.proto

⚠️ macOS: "App is damaged" / Gatekeeper warning

The desktop builds are not code-signed or notarized. Code signing requires an Apple Developer account ($99/year), which this project doesn't have. macOS Gatekeeper will therefore block the app on first launch with a message like "ProtoDocs is damaged and can't be opened" or "ProtoDocs cannot be opened because the developer cannot be verified."

To open the app anyway:

Option A — Right-click method (recommended, one-time):

  1. In Finder, right-click (or Control-click) ProtoDocs.app.
  2. Choose Open from the context menu.
  3. Click Open in the confirmation dialog.

After doing this once, macOS remembers the exception and the app opens normally in the future.

Option B — Remove the quarantine attribute via Terminal:

xattr -dr com.apple.quarantine /Applications/ProtoDocs.app

This strips the quarantine flag entirely. Run it once after moving the app to /Applications.

CLI

# Run directly (no install needed):
go run github.com/sudorandom/protodocs/cmd/protodocs@latest [descriptor-files...]

# Or install permanently:
go install github.com/sudorandom/protodocs/cmd/protodocs@latest

# Serve a local descriptor file with proxy enabled:
protodocs --proxy my-api.binpb

# Connect to a live reflection server:
protodocs --reflection-url https://my-service.example.com

# Specify listen address:
protodocs --addr 127.0.0.1:9090 my-api.binpb

Self-Hosted Static Site

Extract protodocs-static.tar.gz to any static web host (Nginx, S3, GitHub Pages, Netlify, …):

tar -xzf protodocs-static.tar.gz -C /var/www/html/protodocs

Add a config.yaml in the web root to point at your descriptor files:

title: "My API Docs"
descriptor_files:
  - "/my-api.binpb"

Docker

docker run -d -p 8080:80 sudorandom/protodocs:latest
# Then open http://localhost:8080

Changelog

Installation

Choose the download that matches how you want to use ProtoDocs:

Artifact Platform Description
protodocs-desktop-darwin-universal.dmg macOS (Intel + Apple Silicon) Desktop app — drag to Applications
protodocs-desktop-windows-amd64.zip Windows x64 Desktop app — extract and run ProtoDocs.exe
protodocs-desktop-linux-amd64.tar.gz Linux x64 Desktop app — extract and run ProtoDocs
protodocs-cli-darwin-arm64.tar.gz macOS Apple Silicon CLI binary
protodocs-cli-darwin-amd64.tar.gz macOS Intel CLI binary
protodocs-cli-linux-arm64.tar.gz Linux ARM64 CLI binary
protodocs-cli-linux-amd64.tar.gz Linux x64 CLI binary
protodocs-cli-windows-amd64.zip Windows x64 CLI binary
protodocs-static.tar.gz Any web host Static HTML/JS bundle for self-hosting

Desktop App

The desktop app is the easiest way to browse .proto schemas locally — no server required.

Quick Start

  1. Download the .dmg (macOS), .zip (Windows), or .tar.gz (Linux) from the assets below.
  2. Install / extract the app.
  3. Launch ProtoDocs.
  4. At the schema loader, either:
    • Drag & drop a compiled descriptor file (.binpb or .pb) onto the window.
    • Click Open File and select your descriptor file.
    • Enter a reflection URL to connect to a live gRPC / Connect server with reflection enabled.
    • Click Load Demo to explore the built-in Eliza sample schema.

Generating a descriptor file from your .proto sources:

# Using buf:
buf build -o my-api.binpb

# Using protoc:
protoc --descriptor_set_out=my-api.binpb --include_imports your_file.proto

⚠️ macOS: "App is damaged" / Gatekeeper warning

The desktop builds are not code-signed or notarized. Code signing requires an Apple Developer account ($99/year), which this project doesn't have. macOS Gatekeeper will therefore block the app on first launch with a message like "ProtoDocs is damaged and can't be opened" or "ProtoDocs cannot be opened because the developer cannot be verified."

To open the app anyway:

Option A — Right-click method (recommended, one-time):

  1. In Finder, right-click (or Control-click) ProtoDocs.app.
  2. Choose Open from the context menu.
  3. Click Open in the confirmation dialog.

After doing this once, macOS remembers the exception and the app opens normally in the future.

Option B — Remove the quarantine attribute via Terminal:

xattr -dr com.apple.quarantine /Applications/ProtoDocs.app

This strips the quarantine flag entirely. Run it once after moving the app to /Applications.

CLI

# Run directly (no install needed):
go run github.com/sudorandom/protodocs/cmd/protodocs@latest [descriptor-files...]

# Or install permanently:
go install github.com/sudorandom/protodocs/cmd/protodocs@latest

# Serve a local descriptor file with proxy enabled:
protodocs --proxy my-api.binpb

# Connect to a live reflection server:
protodocs --reflection-url https://my-service.example.com

# Specify listen address:
protodocs --addr 127.0.0.1:9090 my-api.binpb

Self-Hosted Static Site

Extract protodocs-static.tar.gz to any static web host (Nginx, S3, GitHub Pages, Netlify, …):

tar -xzf protodocs-static.tar.gz -C /var/www/html/protodocs

Add a config.yaml in the web root to point at your descriptor files:

title: "My API Docs"
descriptor_files:
  - "/my-api.binpb"

Docker

docker run -d -p 8080:80 sudorandom/protodocs:latest
# Then open http://localhost:8080

Changelog

Installation

Choose the download that matches how you want to use ProtoDocs:

Artifact Platform Description
protodocs-desktop-darwin-universal.dmg macOS (Intel + Apple Silicon) Desktop app — drag to Applications
protodocs-desktop-windows-amd64.zip Windows x64 Desktop app — extract and run ProtoDocs.exe
protodocs-desktop-linux-amd64.tar.gz Linux x64 Desktop app — extract and run ProtoDocs
protodocs-cli-darwin-arm64.tar.gz macOS Apple Silicon CLI binary
protodocs-cli-darwin-amd64.tar.gz macOS Intel CLI binary
protodocs-cli-linux-arm64.tar.gz Linux ARM64 CLI binary
protodocs-cli-linux-amd64.tar.gz Linux x64 CLI binary
protodocs-cli-windows-amd64.zip Windows x64 CLI binary
protodocs-static.tar.gz Any web host Static HTML/JS bundle for self-hosting

Desktop App

The desktop app is the easiest way to browse .proto schemas locally — no server required.

Quick Start

  1. Download the .dmg (macOS), .zip (Windows), or .tar.gz (Linux) from the assets below.
  2. Install / extract the app.
  3. Launch ProtoDocs.
  4. At the schema loader, either:
    • Drag & drop a compiled descriptor file (.binpb or .pb) onto the window.
    • Click Open File and select your descriptor file.
    • Enter a reflection URL to connect to a live gRPC / Connect server with reflection enabled.
    • Click Load Demo to explore the built-in Eliza sample schema.

Generating a descriptor file from your .proto sources:

# Using buf:
buf build -o my-api.binpb

# Using protoc:
protoc --descriptor_set_out=my-api.binpb --include_imports your_file.proto

⚠️ macOS: "App is damaged" / Gatekeeper warning

The desktop builds are not code-signed or notarized. Code signing requires an Apple Developer account ($99/year), which this project doesn't have. macOS Gatekeeper will therefore block the app on first launch with a message like "ProtoDocs is damaged and can't be opened" or "ProtoDocs cannot be opened because the developer cannot be verified."

To open the app anyway:

Option A — Right-click method (recommended, one-time):

  1. In Finder, right-click (or Control-click) ProtoDocs.app.
  2. Choose Open from th...
Read more
Loading

v0.2.0

v0.2.0

Choose a tag to compare

View all tags
@sudorandom sudorandom released this 12 Sep 06:40
v0.2.0
ab84bfd
This commit was created on GitHub.com and signed with GitHub’s verified signature.
GPG key ID: B5690EEEBB952194
Verified
Learn about vigilant mode.

0.2.0 (2026-09-12)

Features

  • add graph view of protobuf types (d39e48f)

Installation

Choose the download that matches how you want to use ProtoDocs:

Artifact Platform Description
protodocs-desktop-darwin-universal.dmg macOS (Intel + Apple Silicon) Desktop app — drag to Applications
protodocs-desktop-windows-amd64.zip Windows x64 Desktop app — extract and run ProtoDocs.exe
protodocs-desktop-linux-amd64.tar.gz Linux x64 Desktop app — extract and run ProtoDocs
protodocs-cli-darwin-arm64.tar.gz macOS Apple Silicon CLI binary
protodocs-cli-darwin-amd64.tar.gz macOS Intel CLI binary
protodocs-cli-linux-arm64.tar.gz Linux ARM64 CLI binary
protodocs-cli-linux-amd64.tar.gz Linux x64 CLI binary
protodocs-cli-windows-amd64.zip Windows x64 CLI binary
protodocs-static.tar.gz Any web host Static HTML/JS bundle for self-hosting

Desktop App

The desktop app is the easiest way to browse .proto schemas locally — no server required.

Quick Start

  1. Download the .dmg (macOS), .zip (Windows), or .tar.gz (Linux) from the assets below.
  2. Install / extract the app.
  3. Launch ProtoDocs.
  4. At the schema loader, either:
    • Drag & drop a compiled descriptor file (.binpb or .pb) onto the window.
    • Click Open File and select your descriptor file.
    • Enter a reflection URL to connect to a live gRPC / Connect server with reflection enabled.
    • Click Load Demo to explore the built-in Eliza sample schema.

Generating a descriptor file from your .proto sources:

# Using buf:
buf build -o my-api.binpb

# Using protoc:
protoc --descriptor_set_out=my-api.binpb --include_imports your_file.proto

⚠️ macOS: "App is damaged" / Gatekeeper warning

The desktop builds are not code-signed or notarized. Code signing requires an Apple Developer account ($99/year), which this project doesn't have. macOS Gatekeeper will therefore block the app on first launch with a message like "ProtoDocs is damaged and can't be opened" or "ProtoDocs cannot be opened because the developer cannot be verified."

To open the app anyway:

Option A — Right-click method (recommended, one-time):

  1. In Finder, right-click (or Control-click) ProtoDocs.app.
  2. Choose Open from the context menu.
  3. Click Open in the confirmation dialog.

After doing this once, macOS remembers the exception and the app opens normally in the future.

Option B — Remove the quarantine attribute via Terminal:

xattr -dr com.apple.quarantine /Applications/ProtoDocs.app

This strips the quarantine flag entirely. Run it once after moving the app to /Applications.

CLI

# Run directly (no install needed):
go run github.com/sudorandom/protodocs/cmd/protodocs@latest [descriptor-files...]

# Or install permanently:
go install github.com/sudorandom/protodocs/cmd/protodocs@latest

# Serve a local descriptor file with proxy enabled:
protodocs --proxy my-api.binpb

# Connect to a live reflection server:
protodocs --reflection-url https://my-service.example.com

# Specify listen address:
protodocs --addr 127.0.0.1:9090 my-api.binpb

Self-Hosted Static Site

Extract protodocs-static.tar.gz to any static web host (Nginx, S3, GitHub Pages, Netlify, …):

tar -xzf protodocs-static.tar.gz -C /var/www/html/protodocs

Add a config.yaml in the web root to point at your descriptor files:

title: "My API Docs"
descriptor_files:
  - "/my-api.binpb"

Docker

docker run -d -p 8080:80 sudorandom/protodocs:latest
# Then open http://localhost:8080

Changelog

Installation

Choose the download that matches how you want to use ProtoDocs:

Artifact Platform Description
protodocs-desktop-darwin-universal.dmg macOS (Intel + Apple Silicon) Desktop app — drag to Applications
protodocs-desktop-windows-amd64.zip Windows x64 Desktop app — extract and run ProtoDocs.exe
protodocs-desktop-linux-amd64.tar.gz Linux x64 Desktop app — extract and run ProtoDocs
protodocs-cli-darwin-arm64.tar.gz macOS Apple Silicon CLI binary
protodocs-cli-darwin-amd64.tar.gz macOS Intel CLI binary
protodocs-cli-linux-arm64.tar.gz Linux ARM64 CLI binary
protodocs-cli-linux-amd64.tar.gz Linux x64 CLI binary
protodocs-cli-windows-amd64.zip Windows x64 CLI binary
protodocs-static.tar.gz Any web host Static HTML/JS bundle for self-hosting

Desktop App

The desktop app is the easiest way to browse .proto schemas locally — no server required.

Quick Start

  1. Download the .dmg (macOS), .zip (Windows), or .tar.gz (Linux) from the assets below.
  2. Install / extract the app.
  3. Launch ProtoDocs.
  4. At the schema loader, either:
    • Drag & drop a compiled descriptor file (.binpb or .pb) onto the window.
    • Click Open File and select your descriptor file.
    • Enter a reflection URL to connect to a live gRPC / Connect server with reflection enabled.
    • Click Load Demo to explore the built-in Eliza sample schema.

Generating a descriptor file from your .proto sources:

# Using buf:
buf build -o my-api.binpb

# Using protoc:
protoc --descriptor_set_out=my-api.binpb --include_imports your_file.proto

⚠️ macOS: "App is damaged" / Gatekeeper warning

The desktop builds are not code-signed or notarized. Code signing requires an Apple Developer account ($99/year), which this project doesn't have. macOS Gatekeeper will therefore block the app on first launch with a message like "ProtoDocs is damaged and can't be opened" or "ProtoDocs cannot be opened because the developer cannot be verified."

To open the app anyway:

Option A — Right-click method (recommended, one-time):

  1. In Finder, right-click (or Control-click) ProtoDocs.app.
  2. Choose Open from the context menu.
  3. Click Open in the confirmation dialog.

After doing this once, macOS remembers the exception and the app opens normally in the future.

Option B — Remove the quarantine attribute via Terminal:

xattr -dr com.apple.quarantine /Applications/ProtoDocs.app

This strips the quarantine flag entirely. Run it once after moving the app to /Applications.

CLI

# Run directly (no install needed):
go run github.com/sudorandom/protodocs/cmd/protodocs@latest [descriptor-files...]

# Or install permanently:
go install github.com/sudorandom/protodocs/cmd/protodocs@latest

# Serve a local descriptor file with proxy enabled:
protodocs --proxy my-api.binpb

# Connect to a live reflection server:
protodocs --reflection-url https://my-service.example.com

# Specify listen address:
protodocs --addr 127.0.0.1:9090 my-api.binpb

Self-Hosted Static Site

Extract protodocs-static.tar.gz to any static web host (Nginx, S3, GitHub Pages, Netlify, …):

tar -xzf protodocs-static.tar.gz -C /var/www/html/protodocs

Add a config.yaml in the web root to point at your descriptor files:

title: "My API Docs"
descriptor_files:
  - "/my-api.binpb"

Docker

docker run -d -p 8080:80 sudorandom/protodocs:latest
# Then open http://localhost:8080

Changelog

Installation

Choose the download that matches how you want to use ProtoDocs:

Artifact Platform Description
protodocs-desktop-darwin-universal.dmg macOS (Intel + Apple Silicon) Desktop app — drag to Applications
protodocs-desktop-windows-amd64.zip Windows x64 Desktop app — extract and run ProtoDocs.exe
protodocs-desktop-linux-amd64.tar.gz Linux x64 Desktop app — extract and run ProtoDocs
protodocs-cli-darwin-arm64.tar.gz macOS Apple Silicon CLI binary
protodocs-cli-darwin-amd64.tar.gz macOS Intel CLI binary
protodocs-cli-linux-arm64.tar.gz Linux ARM64 CLI binary
protodocs-cli-linux-amd64.tar.gz Linux x64 CLI binary
protodocs-cli-windows-amd64.zip Windows x64 CLI binary
protodocs-static.tar.gz Any web host Static HTML/JS bundle for self-hosting

Desktop App

The desktop app is the easiest way to browse .proto schemas locally — no server required.

Quick Start

  1. Download the .dmg (macOS), .zip (Windows), or .tar.gz (Linux) from the assets below.
  2. Install / extract the app.
  3. Launch ProtoDocs.
  4. At the schema loader, either:
    • Drag & drop a compiled descriptor file (.binpb or .pb) onto the window.
    • Click Open File and select your descriptor file.
    • Enter a reflection URL to connect to a live gRPC / Connect server with reflection enabled.
    • Click Load Demo to explore the built-in Eliza sample schema.

Generating a descriptor file from your .proto sources:

# Using buf:
buf build -o my-api.binpb

# Using protoc:
protoc --descriptor_set_out=my-api.binpb --include_imports your_file.proto

⚠️ macOS: "App is damaged" / Gatekeeper warning

The desktop builds are not code-signed or notarized. Code signing requires an Apple Developer account ($99/year), which this project doesn't have. macOS Gatekeeper will therefore block the app on first launch with a message like "ProtoDocs is damaged and can't be opened" or "ProtoDocs cannot be opened because the developer cannot be verified."

To open the app anyway:

Option A — Right-click method (recommended, one-time):

  1. In Finder, right-click (or Control-click) ProtoDocs.app.
  2. Choose Open from the con...
Read more
Loading

v0.1.6

v0.1.6

Choose a tag to compare

View all tags
@sudorandom sudorandom released this 04 Aug 11:36
v0.1.6
bca94c4

Full Changelog: v0.1.5...v0.1.6

Installation

Choose the download that matches how you want to use ProtoDocs:

Artifact Platform Description
protodocs-desktop-darwin-universal.dmg macOS (Intel + Apple Silicon) Desktop app — drag to Applications
protodocs-desktop-windows-amd64.zip Windows x64 Desktop app — extract and run ProtoDocs.exe
protodocs-desktop-linux-amd64.tar.gz Linux x64 Desktop app — extract and run ProtoDocs
protodocs-cli-darwin-arm64.tar.gz macOS Apple Silicon CLI binary
protodocs-cli-darwin-amd64.tar.gz macOS Intel CLI binary
protodocs-cli-linux-arm64.tar.gz Linux ARM64 CLI binary
protodocs-cli-linux-amd64.tar.gz Linux x64 CLI binary
protodocs-cli-windows-amd64.zip Windows x64 CLI binary
protodocs-static.tar.gz Any web host Static HTML/JS bundle for self-hosting

Desktop App

The desktop app is the easiest way to browse .proto schemas locally — no server required.

Quick Start

  1. Download the .dmg (macOS), .zip (Windows), or .tar.gz (Linux) from the assets below.
  2. Install / extract the app.
  3. Launch ProtoDocs.
  4. At the schema loader, either:
    • Drag & drop a compiled descriptor file (.binpb or .pb) onto the window.
    • Click Open File and select your descriptor file.
    • Enter a reflection URL to connect to a live gRPC / Connect server with reflection enabled.
    • Click Load Demo to explore the built-in Eliza sample schema.

Generating a descriptor file from your .proto sources:

# Using buf:
buf build -o my-api.binpb

# Using protoc:
protoc --descriptor_set_out=my-api.binpb --include_imports your_file.proto

⚠️ macOS: "App is damaged" / Gatekeeper warning

The desktop builds are not code-signed or notarized. Code signing requires an Apple Developer account ($99/year), which this project doesn't have. macOS Gatekeeper will therefore block the app on first launch with a message like "ProtoDocs is damaged and can't be opened" or "ProtoDocs cannot be opened because the developer cannot be verified."

To open the app anyway:

Option A — Right-click method (recommended, one-time):

  1. In Finder, right-click (or Control-click) ProtoDocs.app.
  2. Choose Open from the context menu.
  3. Click Open in the confirmation dialog.

After doing this once, macOS remembers the exception and the app opens normally in the future.

Option B — Remove the quarantine attribute via Terminal:

xattr -dr com.apple.quarantine /Applications/ProtoDocs.app

This strips the quarantine flag entirely. Run it once after moving the app to /Applications.

CLI

# Run directly (no install needed):
go run github.com/sudorandom/protodocs/cmd/protodocs@latest [descriptor-files...]

# Or install permanently:
go install github.com/sudorandom/protodocs/cmd/protodocs@latest

# Serve a local descriptor file with proxy enabled:
protodocs --proxy my-api.binpb

# Connect to a live reflection server:
protodocs --reflection-url https://my-service.example.com

# Specify listen address:
protodocs --addr 127.0.0.1:9090 my-api.binpb

Self-Hosted Static Site

Extract protodocs-static.tar.gz to any static web host (Nginx, S3, GitHub Pages, Netlify, …):

tar -xzf protodocs-static.tar.gz -C /var/www/html/protodocs

Add a config.yaml in the web root to point at your descriptor files:

title: "My API Docs"
descriptor_files:
  - "/my-api.binpb"

Docker

docker run -d -p 8080:80 sudorandom/protodocs:latest
# Then open http://localhost:8080

Changelog

Installation

Choose the download that matches how you want to use ProtoDocs:

Artifact Platform Description
protodocs-desktop-darwin-universal.dmg macOS (Intel + Apple Silicon) Desktop app — drag to Applications
protodocs-desktop-windows-amd64.zip Windows x64 Desktop app — extract and run ProtoDocs.exe
protodocs-desktop-linux-amd64.tar.gz Linux x64 Desktop app — extract and run ProtoDocs
protodocs-cli-darwin-arm64.tar.gz macOS Apple Silicon CLI binary
protodocs-cli-darwin-amd64.tar.gz macOS Intel CLI binary
protodocs-cli-linux-arm64.tar.gz Linux ARM64 CLI binary
protodocs-cli-linux-amd64.tar.gz Linux x64 CLI binary
protodocs-cli-windows-amd64.zip Windows x64 CLI binary
protodocs-static.tar.gz Any web host Static HTML/JS bundle for self-hosting

Desktop App

The desktop app is the easiest way to browse .proto schemas locally — no server required.

Quick Start

  1. Download the .dmg (macOS), .zip (Windows), or .tar.gz (Linux) from the assets below.
  2. Install / extract the app.
  3. Launch ProtoDocs.
  4. At the schema loader, either:
    • Drag & drop a compiled descriptor file (.binpb or .pb) onto the window.
    • Click Open File and select your descriptor file.
    • Enter a reflection URL to connect to a live gRPC / Connect server with reflection enabled.
    • Click Load Demo to explore the built-in Eliza sample schema.

Generating a descriptor file from your .proto sources:

# Using buf:
buf build -o my-api.binpb

# Using protoc:
protoc --descriptor_set_out=my-api.binpb --include_imports your_file.proto

⚠️ macOS: "App is damaged" / Gatekeeper warning

The desktop builds are not code-signed or notarized. Code signing requires an Apple Developer account ($99/year), which this project doesn't have. macOS Gatekeeper will therefore block the app on first launch with a message like "ProtoDocs is damaged and can't be opened" or "ProtoDocs cannot be opened because the developer cannot be verified."

To open the app anyway:

Option A — Right-click method (recommended, one-time):

  1. In Finder, right-click (or Control-click) ProtoDocs.app.
  2. Choose Open from the context menu.
  3. Click Open in the confirmation dialog.

After doing this once, macOS remembers the exception and the app opens normally in the future.

Option B — Remove the quarantine attribute via Terminal:

xattr -dr com.apple.quarantine /Applications/ProtoDocs.app

This strips the quarantine flag entirely. Run it once after moving the app to /Applications.

CLI

# Run directly (no install needed):
go run github.com/sudorandom/protodocs/cmd/protodocs@latest [descriptor-files...]

# Or install permanently:
go install github.com/sudorandom/protodocs/cmd/protodocs@latest

# Serve a local descriptor file with proxy enabled:
protodocs --proxy my-api.binpb

# Connect to a live reflection server:
protodocs --reflection-url https://my-service.example.com

# Specify listen address:
protodocs --addr 127.0.0.1:9090 my-api.binpb

Self-Hosted Static Site

Extract protodocs-static.tar.gz to any static web host (Nginx, S3, GitHub Pages, Netlify, …):

tar -xzf protodocs-static.tar.gz -C /var/www/html/protodocs

Add a config.yaml in the web root to point at your descriptor files:

title: "My API Docs"
descriptor_files:
  - "/my-api.binpb"

Docker

docker run -d -p 8080:80 sudorandom/protodocs:latest
# Then open http://localhost:8080

Changelog

Installation

Choose the download that matches how you want to use ProtoDocs:

Artifact Platform Description
protodocs-desktop-darwin-universal.dmg macOS (Intel + Apple Silicon) Desktop app — drag to Applications
protodocs-desktop-windows-amd64.zip Windows x64 Desktop app — extract and run ProtoDocs.exe
protodocs-desktop-linux-amd64.tar.gz Linux x64 Desktop app — extract and run ProtoDocs
protodocs-cli-darwin-arm64.tar.gz macOS Apple Silicon CLI binary
protodocs-cli-darwin-amd64.tar.gz macOS Intel CLI binary
protodocs-cli-linux-arm64.tar.gz Linux ARM64 CLI binary
protodocs-cli-linux-amd64.tar.gz Linux x64 CLI binary
protodocs-cli-windows-amd64.zip Windows x64 CLI binary
protodocs-static.tar.gz Any web host Static HTML/JS bundle for self-hosting

Desktop App

The desktop app is the easiest way to browse .proto schemas locally — no server required.

Quick Start

  1. Download the .dmg (macOS), .zip (Windows), or .tar.gz (Linux) from the assets below.
  2. Install / extract the app.
  3. Launch ProtoDocs.
  4. At the schema loader, either:
    • Drag & drop a compiled descriptor file (.binpb or .pb) onto the window.
    • Click Open File and select your descriptor file.
    • Enter a reflection URL to connect to a live gRPC / Connect server with reflection enabled.
    • Click Load Demo to explore the built-in Eliza sample schema.

Generating a descriptor file from your .proto sources:

# Using buf:
buf build -o my-api.binpb

# Using protoc:
protoc --descriptor_set_out=my-api.binpb --include_imports your_file.proto

⚠️ macOS: "App is damaged" / Gatekeeper warning

The desktop builds are not code-signed or notarized. Code signing requires an Apple Developer account ($99/year), which this project doesn't have. macOS Gatekeeper will therefore block the app on first launch with a message like "ProtoDocs is damaged and can't be opened" or "ProtoDocs cannot be opened because the developer cannot be verified."

To open the app anyway:

Option A — Right-click method (recommended, one-time):

  1. In Finder, right-click (or Control-click) ProtoDocs.app.
  2. Choose Open from the context menu.
  3. Click Open in the confirmation dialog.

After doing this once, macOS remembers the exception and the app opens normally in the future.

**O...

Read more
Loading

v0.1.5

v0.1.5

Choose a tag to compare

View all tags
@sudorandom sudorandom released this 20 Jul 20:16
v0.1.5
1bcc76e
This commit was created on GitHub.com and signed with GitHub’s verified signature.
GPG key ID: B5690EEEBB952194
Verified
Learn about vigilant mode.

0.1.5 (2026-07-20)

Bug Fixes

  • fix generation of blank map types (6f9f2ec)

Installation

Choose the download that matches how you want to use ProtoDocs:

Artifact Platform Description
protodocs-desktop-darwin-universal.dmg macOS (Intel + Apple Silicon) Desktop app — drag to Applications
protodocs-desktop-windows-amd64.zip Windows x64 Desktop app — extract and run ProtoDocs.exe
protodocs-desktop-linux-amd64.tar.gz Linux x64 Desktop app — extract and run ProtoDocs
protodocs-cli-darwin-arm64.tar.gz macOS Apple Silicon CLI binary
protodocs-cli-darwin-amd64.tar.gz macOS Intel CLI binary
protodocs-cli-linux-arm64.tar.gz Linux ARM64 CLI binary
protodocs-cli-linux-amd64.tar.gz Linux x64 CLI binary
protodocs-cli-windows-amd64.zip Windows x64 CLI binary
protodocs-static.tar.gz Any web host Static HTML/JS bundle for self-hosting

Desktop App

The desktop app is the easiest way to browse .proto schemas locally — no server required.

Quick Start

  1. Download the .dmg (macOS), .zip (Windows), or .tar.gz (Linux) from the assets below.
  2. Install / extract the app.
  3. Launch ProtoDocs.
  4. At the schema loader, either:
    • Drag & drop a compiled descriptor file (.binpb or .pb) onto the window.
    • Click Open File and select your descriptor file.
    • Enter a reflection URL to connect to a live gRPC / Connect server with reflection enabled.
    • Click Load Demo to explore the built-in Eliza sample schema.

Generating a descriptor file from your .proto sources:

# Using buf:
buf build -o my-api.binpb

# Using protoc:
protoc --descriptor_set_out=my-api.binpb --include_imports your_file.proto

⚠️ macOS: "App is damaged" / Gatekeeper warning

The desktop builds are not code-signed or notarized. Code signing requires an Apple Developer account ($99/year), which this project doesn't have. macOS Gatekeeper will therefore block the app on first launch with a message like "ProtoDocs is damaged and can't be opened" or "ProtoDocs cannot be opened because the developer cannot be verified."

To open the app anyway:

Option A — Right-click method (recommended, one-time):

  1. In Finder, right-click (or Control-click) ProtoDocs.app.
  2. Choose Open from the context menu.
  3. Click Open in the confirmation dialog.

After doing this once, macOS remembers the exception and the app opens normally in the future.

Option B — Remove the quarantine attribute via Terminal:

xattr -dr com.apple.quarantine /Applications/ProtoDocs.app

This strips the quarantine flag entirely. Run it once after moving the app to /Applications.

CLI

# Run directly (no install needed):
go run github.com/sudorandom/protodocs/cmd/protodocs@latest [descriptor-files...]

# Or install permanently:
go install github.com/sudorandom/protodocs/cmd/protodocs@latest

# Serve a local descriptor file with proxy enabled:
protodocs --proxy my-api.binpb

# Connect to a live reflection server:
protodocs --reflection-url https://my-service.example.com

# Specify listen address:
protodocs --addr 127.0.0.1:9090 my-api.binpb

Self-Hosted Static Site

Extract protodocs-static.tar.gz to any static web host (Nginx, S3, GitHub Pages, Netlify, …):

tar -xzf protodocs-static.tar.gz -C /var/www/html/protodocs

Add a config.yaml in the web root to point at your descriptor files:

title: "My API Docs"
descriptor_files:
  - "/my-api.binpb"

Docker

docker run -d -p 8080:80 sudorandom/protodocs:latest
# Then open http://localhost:8080

Changelog

Installation

Choose the download that matches how you want to use ProtoDocs:

Artifact Platform Description
protodocs-desktop-darwin-universal.dmg macOS (Intel + Apple Silicon) Desktop app — drag to Applications
protodocs-desktop-windows-amd64.zip Windows x64 Desktop app — extract and run ProtoDocs.exe
protodocs-desktop-linux-amd64.tar.gz Linux x64 Desktop app — extract and run ProtoDocs
protodocs-cli-darwin-arm64.tar.gz macOS Apple Silicon CLI binary
protodocs-cli-darwin-amd64.tar.gz macOS Intel CLI binary
protodocs-cli-linux-arm64.tar.gz Linux ARM64 CLI binary
protodocs-cli-linux-amd64.tar.gz Linux x64 CLI binary
protodocs-cli-windows-amd64.zip Windows x64 CLI binary
protodocs-static.tar.gz Any web host Static HTML/JS bundle for self-hosting

Desktop App

The desktop app is the easiest way to browse .proto schemas locally — no server required.

Quick Start

  1. Download the .dmg (macOS), .zip (Windows), or .tar.gz (Linux) from the assets below.
  2. Install / extract the app.
  3. Launch ProtoDocs.
  4. At the schema loader, either:
    • Drag & drop a compiled descriptor file (.binpb or .pb) onto the window.
    • Click Open File and select your descriptor file.
    • Enter a reflection URL to connect to a live gRPC / Connect server with reflection enabled.
    • Click Load Demo to explore the built-in Eliza sample schema.

Generating a descriptor file from your .proto sources:

# Using buf:
buf build -o my-api.binpb

# Using protoc:
protoc --descriptor_set_out=my-api.binpb --include_imports your_file.proto

⚠️ macOS: "App is damaged" / Gatekeeper warning

The desktop builds are not code-signed or notarized. Code signing requires an Apple Developer account ($99/year), which this project doesn't have. macOS Gatekeeper will therefore block the app on first launch with a message like "ProtoDocs is damaged and can't be opened" or "ProtoDocs cannot be opened because the developer cannot be verified."

To open the app anyway:

Option A — Right-click method (recommended, one-time):

  1. In Finder, right-click (or Control-click) ProtoDocs.app.
  2. Choose Open from the context menu.
  3. Click Open in the confirmation dialog.

After doing this once, macOS remembers the exception and the app opens normally in the future.

Option B — Remove the quarantine attribute via Terminal:

xattr -dr com.apple.quarantine /Applications/ProtoDocs.app

This strips the quarantine flag entirely. Run it once after moving the app to /Applications.

CLI

# Run directly (no install needed):
go run github.com/sudorandom/protodocs/cmd/protodocs@latest [descriptor-files...]

# Or install permanently:
go install github.com/sudorandom/protodocs/cmd/protodocs@latest

# Serve a local descriptor file with proxy enabled:
protodocs --proxy my-api.binpb

# Connect to a live reflection server:
protodocs --reflection-url https://my-service.example.com

# Specify listen address:
protodocs --addr 127.0.0.1:9090 my-api.binpb

Self-Hosted Static Site

Extract protodocs-static.tar.gz to any static web host (Nginx, S3, GitHub Pages, Netlify, …):

tar -xzf protodocs-static.tar.gz -C /var/www/html/protodocs

Add a config.yaml in the web root to point at your descriptor files:

title: "My API Docs"
descriptor_files:
  - "/my-api.binpb"

Docker

docker run -d -p 8080:80 sudorandom/protodocs:latest
# Then open http://localhost:8080

Changelog

Installation

Choose the download that matches how you want to use ProtoDocs:

Artifact Platform Description
protodocs-desktop-darwin-universal.dmg macOS (Intel + Apple Silicon) Desktop app — drag to Applications
protodocs-desktop-windows-amd64.zip Windows x64 Desktop app — extract and run ProtoDocs.exe
protodocs-desktop-linux-amd64.tar.gz Linux x64 Desktop app — extract and run ProtoDocs
protodocs-cli-darwin-arm64.tar.gz macOS Apple Silicon CLI binary
protodocs-cli-darwin-amd64.tar.gz macOS Intel CLI binary
protodocs-cli-linux-arm64.tar.gz Linux ARM64 CLI binary
protodocs-cli-linux-amd64.tar.gz Linux x64 CLI binary
protodocs-cli-windows-amd64.zip Windows x64 CLI binary
protodocs-static.tar.gz Any web host Static HTML/JS bundle for self-hosting

Desktop App

The desktop app is the easiest way to browse .proto schemas locally — no server required.

Quick Start

  1. Download the .dmg (macOS), .zip (Windows), or .tar.gz (Linux) from the assets below.
  2. Install / extract the app.
  3. Launch ProtoDocs.
  4. At the schema loader, either:
    • Drag & drop a compiled descriptor file (.binpb or .pb) onto the window.
    • Click Open File and select your descriptor file.
    • Enter a reflection URL to connect to a live gRPC / Connect server with reflection enabled.
    • Click Load Demo to explore the built-in Eliza sample schema.

Generating a descriptor file from your .proto sources:

# Using buf:
buf build -o my-api.binpb

# Using protoc:
protoc --descriptor_set_out=my-api.binpb --include_imports your_file.proto

⚠️ macOS: "App is damaged" / Gatekeeper warning

The desktop builds are not code-signed or notarized. Code signing requires an Apple Developer account ($99/year), which this project doesn't have. macOS Gatekeeper will therefore block the app on first launch with a message like "ProtoDocs is damaged and can't be opened" or "ProtoDocs cannot be opened because the developer cannot be verified."

To open the app anyway:

Option A — Right-click method (recommended, one-time):

  1. In Finder, right-click (or Control-click) ProtoDocs.app.
  2. Choose Open from the context menu.
  3. Click Open in the confirmation dialog.

...

Read more
Loading

v0.1.4

v0.1.4

Choose a tag to compare

View all tags
@sudorandom sudorandom released this 05 Jul 07:47
v0.1.4
e3ad7c4
This commit was created on GitHub.com and signed with GitHub’s verified signature.
GPG key ID: B5690EEEBB952194
Verified
Learn about vigilant mode.

0.1.4 (2026-07-04)

Bug Fixes

  • go to definition now properly scrolls after loading a new file (0a28594)

Installation

Choose the download that matches how you want to use ProtoDocs:

Artifact Platform Description
protodocs-desktop-darwin-universal.dmg macOS (Intel + Apple Silicon) Desktop app — drag to Applications
protodocs-desktop-windows-amd64.zip Windows x64 Desktop app — extract and run ProtoDocs.exe
protodocs-desktop-linux-amd64.tar.gz Linux x64 Desktop app — extract and run ProtoDocs
protodocs-cli-darwin-arm64.tar.gz macOS Apple Silicon CLI binary
protodocs-cli-darwin-amd64.tar.gz macOS Intel CLI binary
protodocs-cli-linux-arm64.tar.gz Linux ARM64 CLI binary
protodocs-cli-linux-amd64.tar.gz Linux x64 CLI binary
protodocs-cli-windows-amd64.zip Windows x64 CLI binary
protodocs-static.tar.gz Any web host Static HTML/JS bundle for self-hosting

Desktop App

The desktop app is the easiest way to browse .proto schemas locally — no server required.

Quick Start

  1. Download the .dmg (macOS), .zip (Windows), or .tar.gz (Linux) from the assets below.
  2. Install / extract the app.
  3. Launch ProtoDocs.
  4. At the schema loader, either:
    • Drag & drop a compiled descriptor file (.binpb or .pb) onto the window.
    • Click Open File and select your descriptor file.
    • Enter a reflection URL to connect to a live gRPC / Connect server with reflection enabled.
    • Click Load Demo to explore the built-in Eliza sample schema.

Generating a descriptor file from your .proto sources:

# Using buf:
buf build -o my-api.binpb

# Using protoc:
protoc --descriptor_set_out=my-api.binpb --include_imports your_file.proto

⚠️ macOS: "App is damaged" / Gatekeeper warning

The desktop builds are not code-signed or notarized. Code signing requires an Apple Developer account ($99/year), which this project doesn't have. macOS Gatekeeper will therefore block the app on first launch with a message like "ProtoDocs is damaged and can't be opened" or "ProtoDocs cannot be opened because the developer cannot be verified."

To open the app anyway:

Option A — Right-click method (recommended, one-time):

  1. In Finder, right-click (or Control-click) ProtoDocs.app.
  2. Choose Open from the context menu.
  3. Click Open in the confirmation dialog.

After doing this once, macOS remembers the exception and the app opens normally in the future.

Option B — Remove the quarantine attribute via Terminal:

xattr -dr com.apple.quarantine /Applications/ProtoDocs.app

This strips the quarantine flag entirely. Run it once after moving the app to /Applications.

CLI

# Run directly (no install needed):
go run github.com/sudorandom/protodocs/cmd/protodocs@latest [descriptor-files...]

# Or install permanently:
go install github.com/sudorandom/protodocs/cmd/protodocs@latest

# Serve a local descriptor file with proxy enabled:
protodocs --proxy my-api.binpb

# Connect to a live reflection server:
protodocs --reflection-url https://my-service.example.com

# Specify listen address:
protodocs --addr 127.0.0.1:9090 my-api.binpb

Self-Hosted Static Site

Extract protodocs-static.tar.gz to any static web host (Nginx, S3, GitHub Pages, Netlify, …):

tar -xzf protodocs-static.tar.gz -C /var/www/html/protodocs

Add a config.yaml in the web root to point at your descriptor files:

title: "My API Docs"
descriptor_files:
  - "/my-api.binpb"

Docker

docker run -d -p 8080:80 sudorandom/protodocs:latest
# Then open http://localhost:8080

Changelog

Installation

Choose the download that matches how you want to use ProtoDocs:

Artifact Platform Description
protodocs-desktop-darwin-universal.dmg macOS (Intel + Apple Silicon) Desktop app — drag to Applications
protodocs-desktop-windows-amd64.zip Windows x64 Desktop app — extract and run ProtoDocs.exe
protodocs-desktop-linux-amd64.tar.gz Linux x64 Desktop app — extract and run ProtoDocs
protodocs-cli-darwin-arm64.tar.gz macOS Apple Silicon CLI binary
protodocs-cli-darwin-amd64.tar.gz macOS Intel CLI binary
protodocs-cli-linux-arm64.tar.gz Linux ARM64 CLI binary
protodocs-cli-linux-amd64.tar.gz Linux x64 CLI binary
protodocs-cli-windows-amd64.zip Windows x64 CLI binary
protodocs-static.tar.gz Any web host Static HTML/JS bundle for self-hosting

Desktop App

The desktop app is the easiest way to browse .proto schemas locally — no server required.

Quick Start

  1. Download the .dmg (macOS), .zip (Windows), or .tar.gz (Linux) from the assets below.
  2. Install / extract the app.
  3. Launch ProtoDocs.
  4. At the schema loader, either:
    • Drag & drop a compiled descriptor file (.binpb or .pb) onto the window.
    • Click Open File and select your descriptor file.
    • Enter a reflection URL to connect to a live gRPC / Connect server with reflection enabled.
    • Click Load Demo to explore the built-in Eliza sample schema.

Generating a descriptor file from your .proto sources:

# Using buf:
buf build -o my-api.binpb

# Using protoc:
protoc --descriptor_set_out=my-api.binpb --include_imports your_file.proto

⚠️ macOS: "App is damaged" / Gatekeeper warning

The desktop builds are not code-signed or notarized. Code signing requires an Apple Developer account ($99/year), which this project doesn't have. macOS Gatekeeper will therefore block the app on first launch with a message like "ProtoDocs is damaged and can't be opened" or "ProtoDocs cannot be opened because the developer cannot be verified."

To open the app anyway:

Option A — Right-click method (recommended, one-time):

  1. In Finder, right-click (or Control-click) ProtoDocs.app.
  2. Choose Open from the context menu.
  3. Click Open in the confirmation dialog.

After doing this once, macOS remembers the exception and the app opens normally in the future.

Option B — Remove the quarantine attribute via Terminal:

xattr -dr com.apple.quarantine /Applications/ProtoDocs.app

This strips the quarantine flag entirely. Run it once after moving the app to /Applications.

CLI

# Run directly (no install needed):
go run github.com/sudorandom/protodocs/cmd/protodocs@latest [descriptor-files...]

# Or install permanently:
go install github.com/sudorandom/protodocs/cmd/protodocs@latest

# Serve a local descriptor file with proxy enabled:
protodocs --proxy my-api.binpb

# Connect to a live reflection server:
protodocs --reflection-url https://my-service.example.com

# Specify listen address:
protodocs --addr 127.0.0.1:9090 my-api.binpb

Self-Hosted Static Site

Extract protodocs-static.tar.gz to any static web host (Nginx, S3, GitHub Pages, Netlify, …):

tar -xzf protodocs-static.tar.gz -C /var/www/html/protodocs

Add a config.yaml in the web root to point at your descriptor files:

title: "My API Docs"
descriptor_files:
  - "/my-api.binpb"

Docker

docker run -d -p 8080:80 sudorandom/protodocs:latest
# Then open http://localhost:8080

Changelog

Installation

Choose the download that matches how you want to use ProtoDocs:

Artifact Platform Description
protodocs-desktop-darwin-universal.dmg macOS (Intel + Apple Silicon) Desktop app — drag to Applications
protodocs-desktop-windows-amd64.zip Windows x64 Desktop app — extract and run ProtoDocs.exe
protodocs-desktop-linux-amd64.tar.gz Linux x64 Desktop app — extract and run ProtoDocs
protodocs-cli-darwin-arm64.tar.gz macOS Apple Silicon CLI binary
protodocs-cli-darwin-amd64.tar.gz macOS Intel CLI binary
protodocs-cli-linux-arm64.tar.gz Linux ARM64 CLI binary
protodocs-cli-linux-amd64.tar.gz Linux x64 CLI binary
protodocs-cli-windows-amd64.zip Windows x64 CLI binary
protodocs-static.tar.gz Any web host Static HTML/JS bundle for self-hosting

Desktop App

The desktop app is the easiest way to browse .proto schemas locally — no server required.

Quick Start

  1. Download the .dmg (macOS), .zip (Windows), or .tar.gz (Linux) from the assets below.
  2. Install / extract the app.
  3. Launch ProtoDocs.
  4. At the schema loader, either:
    • Drag & drop a compiled descriptor file (.binpb or .pb) onto the window.
    • Click Open File and select your descriptor file.
    • Enter a reflection URL to connect to a live gRPC / Connect server with reflection enabled.
    • Click Load Demo to explore the built-in Eliza sample schema.

Generating a descriptor file from your .proto sources:

# Using buf:
buf build -o my-api.binpb

# Using protoc:
protoc --descriptor_set_out=my-api.binpb --include_imports your_file.proto

⚠️ macOS: "App is damaged" / Gatekeeper warning

The desktop builds are not code-signed or notarized. Code signing requires an Apple Developer account ($99/year), which this project doesn't have. macOS Gatekeeper will therefore block the app on first launch with a message like "ProtoDocs is damaged and can't be opened" or "ProtoDocs cannot be opened because the developer cannot be verified."

To open the app anyway:

Option A — Right-click method (recommended, one-time):

  1. In Finder, right-click (or Control-click) ProtoDocs.app.
  2. Choose Open from the context menu.
  3. Click Open in the confirmation dialog.

After doing this once, m...

Read more
Loading

v0.1.3

v0.1.3

Choose a tag to compare

View all tags
@sudorandom sudorandom released this 02 Jul 06:53
v0.1.3
4c619e9
This commit was created on GitHub.com and signed with GitHub’s verified signature.
GPG key ID: B5690EEEBB952194
Verified
Learn about vigilant mode.

0.1.3 (2026-06-29)

Bug Fixes

  • add a couple new sections (0cf8f48)
  • add a new section for the live website (c629265)

Installation

Choose the download that matches how you want to use ProtoDocs:

Artifact Platform Description
protodocs-desktop-darwin-universal.dmg macOS (Intel + Apple Silicon) Desktop app — drag to Applications
protodocs-desktop-windows-amd64.zip Windows x64 Desktop app — extract and run ProtoDocs.exe
protodocs-desktop-linux-amd64.tar.gz Linux x64 Desktop app — extract and run ProtoDocs
protodocs-cli-darwin-arm64.tar.gz macOS Apple Silicon CLI binary
protodocs-cli-darwin-amd64.tar.gz macOS Intel CLI binary
protodocs-cli-linux-arm64.tar.gz Linux ARM64 CLI binary
protodocs-cli-linux-amd64.tar.gz Linux x64 CLI binary
protodocs-cli-windows-amd64.zip Windows x64 CLI binary
protodocs-static.tar.gz Any web host Static HTML/JS bundle for self-hosting

Desktop App

The desktop app is the easiest way to browse .proto schemas locally — no server required.

Quick Start

  1. Download the .dmg (macOS), .zip (Windows), or .tar.gz (Linux) from the assets below.
  2. Install / extract the app.
  3. Launch ProtoDocs.
  4. At the schema loader, either:
    • Drag & drop a compiled descriptor file (.binpb or .pb) onto the window.
    • Click Open File and select your descriptor file.
    • Enter a reflection URL to connect to a live gRPC / Connect server with reflection enabled.
    • Click Load Demo to explore the built-in Eliza sample schema.

Generating a descriptor file from your .proto sources:

# Using buf:
buf build -o my-api.binpb

# Using protoc:
protoc --descriptor_set_out=my-api.binpb --include_imports your_file.proto

⚠️ macOS: "App is damaged" / Gatekeeper warning

The desktop builds are not code-signed or notarized. Code signing requires an Apple Developer account ($99/year), which this project doesn't have. macOS Gatekeeper will therefore block the app on first launch with a message like "ProtoDocs is damaged and can't be opened" or "ProtoDocs cannot be opened because the developer cannot be verified."

To open the app anyway:

Option A — Right-click method (recommended, one-time):

  1. In Finder, right-click (or Control-click) ProtoDocs.app.
  2. Choose Open from the context menu.
  3. Click Open in the confirmation dialog.

After doing this once, macOS remembers the exception and the app opens normally in the future.

Option B — Remove the quarantine attribute via Terminal:

xattr -dr com.apple.quarantine /Applications/ProtoDocs.app

This strips the quarantine flag entirely. Run it once after moving the app to /Applications.

CLI

# Run directly (no install needed):
go run github.com/sudorandom/protodocs/cmd/protodocs@latest [descriptor-files...]

# Or install permanently:
go install github.com/sudorandom/protodocs/cmd/protodocs@latest

# Serve a local descriptor file with proxy enabled:
protodocs --proxy my-api.binpb

# Connect to a live reflection server:
protodocs --reflection-url https://my-service.example.com

# Specify listen address:
protodocs --addr 127.0.0.1:9090 my-api.binpb

Self-Hosted Static Site

Extract protodocs-static.tar.gz to any static web host (Nginx, S3, GitHub Pages, Netlify, …):

tar -xzf protodocs-static.tar.gz -C /var/www/html/protodocs

Add a config.yaml in the web root to point at your descriptor files:

title: "My API Docs"
descriptor_files:
  - "/my-api.binpb"

Docker

docker run -d -p 8080:80 sudorandom/protodocs:latest
# Then open http://localhost:8080

Changelog

Installation

Choose the download that matches how you want to use ProtoDocs:

Artifact Platform Description
protodocs-desktop-darwin-universal.dmg macOS (Intel + Apple Silicon) Desktop app — drag to Applications
protodocs-desktop-windows-amd64.zip Windows x64 Desktop app — extract and run ProtoDocs.exe
protodocs-desktop-linux-amd64.tar.gz Linux x64 Desktop app — extract and run ProtoDocs
protodocs-cli-darwin-arm64.tar.gz macOS Apple Silicon CLI binary
protodocs-cli-darwin-amd64.tar.gz macOS Intel CLI binary
protodocs-cli-linux-arm64.tar.gz Linux ARM64 CLI binary
protodocs-cli-linux-amd64.tar.gz Linux x64 CLI binary
protodocs-cli-windows-amd64.zip Windows x64 CLI binary
protodocs-static.tar.gz Any web host Static HTML/JS bundle for self-hosting

Desktop App

The desktop app is the easiest way to browse .proto schemas locally — no server required.

Quick Start

  1. Download the .dmg (macOS), .zip (Windows), or .tar.gz (Linux) from the assets below.
  2. Install / extract the app.
  3. Launch ProtoDocs.
  4. At the schema loader, either:
    • Drag & drop a compiled descriptor file (.binpb or .pb) onto the window.
    • Click Open File and select your descriptor file.
    • Enter a reflection URL to connect to a live gRPC / Connect server with reflection enabled.
    • Click Load Demo to explore the built-in Eliza sample schema.

Generating a descriptor file from your .proto sources:

# Using buf:
buf build -o my-api.binpb

# Using protoc:
protoc --descriptor_set_out=my-api.binpb --include_imports your_file.proto

⚠️ macOS: "App is damaged" / Gatekeeper warning

The desktop builds are not code-signed or notarized. Code signing requires an Apple Developer account ($99/year), which this project doesn't have. macOS Gatekeeper will therefore block the app on first launch with a message like "ProtoDocs is damaged and can't be opened" or "ProtoDocs cannot be opened because the developer cannot be verified."

To open the app anyway:

Option A — Right-click method (recommended, one-time):

  1. In Finder, right-click (or Control-click) ProtoDocs.app.
  2. Choose Open from the context menu.
  3. Click Open in the confirmation dialog.

After doing this once, macOS remembers the exception and the app opens normally in the future.

Option B — Remove the quarantine attribute via Terminal:

xattr -dr com.apple.quarantine /Applications/ProtoDocs.app

This strips the quarantine flag entirely. Run it once after moving the app to /Applications.

CLI

# Run directly (no install needed):
go run github.com/sudorandom/protodocs/cmd/protodocs@latest [descriptor-files...]

# Or install permanently:
go install github.com/sudorandom/protodocs/cmd/protodocs@latest

# Serve a local descriptor file with proxy enabled:
protodocs --proxy my-api.binpb

# Connect to a live reflection server:
protodocs --reflection-url https://my-service.example.com

# Specify listen address:
protodocs --addr 127.0.0.1:9090 my-api.binpb

Self-Hosted Static Site

Extract protodocs-static.tar.gz to any static web host (Nginx, S3, GitHub Pages, Netlify, …):

tar -xzf protodocs-static.tar.gz -C /var/www/html/protodocs

Add a config.yaml in the web root to point at your descriptor files:

title: "My API Docs"
descriptor_files:
  - "/my-api.binpb"

Docker

docker run -d -p 8080:80 sudorandom/protodocs:latest
# Then open http://localhost:8080

Changelog

Installation

Choose the download that matches how you want to use ProtoDocs:

Artifact Platform Description
protodocs-desktop-darwin-universal.dmg macOS (Intel + Apple Silicon) Desktop app — drag to Applications
protodocs-desktop-windows-amd64.zip Windows x64 Desktop app — extract and run ProtoDocs.exe
protodocs-desktop-linux-amd64.tar.gz Linux x64 Desktop app — extract and run ProtoDocs
protodocs-cli-darwin-arm64.tar.gz macOS Apple Silicon CLI binary
protodocs-cli-darwin-amd64.tar.gz macOS Intel CLI binary
protodocs-cli-linux-arm64.tar.gz Linux ARM64 CLI binary
protodocs-cli-linux-amd64.tar.gz Linux x64 CLI binary
protodocs-cli-windows-amd64.zip Windows x64 CLI binary
protodocs-static.tar.gz Any web host Static HTML/JS bundle for self-hosting

Desktop App

The desktop app is the easiest way to browse .proto schemas locally — no server required.

Quick Start

  1. Download the .dmg (macOS), .zip (Windows), or .tar.gz (Linux) from the assets below.
  2. Install / extract the app.
  3. Launch ProtoDocs.
  4. At the schema loader, either:
    • Drag & drop a compiled descriptor file (.binpb or .pb) onto the window.
    • Click Open File and select your descriptor file.
    • Enter a reflection URL to connect to a live gRPC / Connect server with reflection enabled.
    • Click Load Demo to explore the built-in Eliza sample schema.

Generating a descriptor file from your .proto sources:

# Using buf:
buf build -o my-api.binpb

# Using protoc:
protoc --descriptor_set_out=my-api.binpb --include_imports your_file.proto

⚠️ macOS: "App is damaged" / Gatekeeper warning

The desktop builds are not code-signed or notarized. Code signing requires an Apple Developer account ($99/year), which this project doesn't have. macOS Gatekeeper will therefore block the app on first launch with a message like "ProtoDocs is damaged and can't be opened" or "ProtoDocs cannot be opened because the developer cannot be verified."

To open the app anyway:

Option A — Right-click method (recommended, one-time):

  1. In Finder, right-click (or Control-click) ProtoDocs.app.
  2. Choos...
Read more
Loading

v0.0.25

v0.0.25

Choose a tag to compare

View all tags
@github-actions github-actions released this 29 Jun 16:09
v0.0.25
c629265

Installation

Choose the download that matches how you want to use ProtoDocs:

Artifact Platform Description
protodocs-desktop-darwin-universal.dmg macOS (Intel + Apple Silicon) Desktop app — drag to Applications
protodocs-desktop-windows-amd64.zip Windows x64 Desktop app — extract and run ProtoDocs.exe
protodocs-desktop-linux-amd64.tar.gz Linux x64 Desktop app — extract and run ProtoDocs
protodocs-cli-darwin-arm64.tar.gz macOS Apple Silicon CLI binary
protodocs-cli-darwin-amd64.tar.gz macOS Intel CLI binary
protodocs-cli-linux-arm64.tar.gz Linux ARM64 CLI binary
protodocs-cli-linux-amd64.tar.gz Linux x64 CLI binary
protodocs-cli-windows-amd64.zip Windows x64 CLI binary
protodocs-static.tar.gz Any web host Static HTML/JS bundle for self-hosting

Desktop App

The desktop app is the easiest way to browse .proto schemas locally — no server required.

Quick Start

  1. Download the .dmg (macOS), .zip (Windows), or .tar.gz (Linux) from the assets below.
  2. Install / extract the app.
  3. Launch ProtoDocs.
  4. At the schema loader, either:
    • Drag & drop a compiled descriptor file (.binpb or .pb) onto the window.
    • Click Open File and select your descriptor file.
    • Enter a reflection URL to connect to a live gRPC / Connect server with reflection enabled.
    • Click Load Demo to explore the built-in Eliza sample schema.

Generating a descriptor file from your .proto sources:

# Using buf:
buf build -o my-api.binpb

# Using protoc:
protoc --descriptor_set_out=my-api.binpb --include_imports your_file.proto

⚠️ macOS: "App is damaged" / Gatekeeper warning

The desktop builds are not code-signed or notarized. Code signing requires an Apple Developer account ($99/year), which this project doesn't have. macOS Gatekeeper will therefore block the app on first launch with a message like "ProtoDocs is damaged and can't be opened" or "ProtoDocs cannot be opened because the developer cannot be verified."

To open the app anyway:

Option A — Right-click method (recommended, one-time):

  1. In Finder, right-click (or Control-click) ProtoDocs.app.
  2. Choose Open from the context menu.
  3. Click Open in the confirmation dialog.

After doing this once, macOS remembers the exception and the app opens normally in the future.

Option B — Remove the quarantine attribute via Terminal:

xattr -dr com.apple.quarantine /Applications/ProtoDocs.app

This strips the quarantine flag entirely. Run it once after moving the app to /Applications.

CLI

# Run directly (no install needed):
go run github.com/sudorandom/protodocs/cmd/protodocs@latest [descriptor-files...]

# Or install permanently:
go install github.com/sudorandom/protodocs/cmd/protodocs@latest

# Serve a local descriptor file with proxy enabled:
protodocs --proxy my-api.binpb

# Connect to a live reflection server:
protodocs --reflection-url https://my-service.example.com

# Specify listen address:
protodocs --addr 127.0.0.1:9090 my-api.binpb

Self-Hosted Static Site

Extract protodocs-static.tar.gz to any static web host (Nginx, S3, GitHub Pages, Netlify, …):

tar -xzf protodocs-static.tar.gz -C /var/www/html/protodocs

Add a config.yaml in the web root to point at your descriptor files:

title: "My API Docs"
descriptor_files:
  - "/my-api.binpb"

Docker

docker run -d -p 8080:80 sudorandom/protodocs:latest
# Then open http://localhost:8080

Changelog

Installation

Choose the download that matches how you want to use ProtoDocs:

Artifact Platform Description
protodocs-desktop-darwin-universal.dmg macOS (Intel + Apple Silicon) Desktop app — drag to Applications
protodocs-desktop-windows-amd64.zip Windows x64 Desktop app — extract and run ProtoDocs.exe
protodocs-desktop-linux-amd64.tar.gz Linux x64 Desktop app — extract and run ProtoDocs
protodocs-cli-darwin-arm64.tar.gz macOS Apple Silicon CLI binary
protodocs-cli-darwin-amd64.tar.gz macOS Intel CLI binary
protodocs-cli-linux-arm64.tar.gz Linux ARM64 CLI binary
protodocs-cli-linux-amd64.tar.gz Linux x64 CLI binary
protodocs-cli-windows-amd64.zip Windows x64 CLI binary
protodocs-static.tar.gz Any web host Static HTML/JS bundle for self-hosting

Desktop App

The desktop app is the easiest way to browse .proto schemas locally — no server required.

Quick Start

  1. Download the .dmg (macOS), .zip (Windows), or .tar.gz (Linux) from the assets below.
  2. Install / extract the app.
  3. Launch ProtoDocs.
  4. At the schema loader, either:
    • Drag & drop a compiled descriptor file (.binpb or .pb) onto the window.
    • Click Open File and select your descriptor file.
    • Enter a reflection URL to connect to a live gRPC / Connect server with reflection enabled.
    • Click Load Demo to explore the built-in Eliza sample schema.

Generating a descriptor file from your .proto sources:

# Using buf:
buf build -o my-api.binpb

# Using protoc:
protoc --descriptor_set_out=my-api.binpb --include_imports your_file.proto

⚠️ macOS: "App is damaged" / Gatekeeper warning

The desktop builds are not code-signed or notarized. Code signing requires an Apple Developer account ($99/year), which this project doesn't have. macOS Gatekeeper will therefore block the app on first launch with a message like "ProtoDocs is damaged and can't be opened" or "ProtoDocs cannot be opened because the developer cannot be verified."

To open the app anyway:

Option A — Right-click method (recommended, one-time):

  1. In Finder, right-click (or Control-click) ProtoDocs.app.
  2. Choose Open from the context menu.
  3. Click Open in the confirmation dialog.

After doing this once, macOS remembers the exception and the app opens normally in the future.

Option B — Remove the quarantine attribute via Terminal:

xattr -dr com.apple.quarantine /Applications/ProtoDocs.app

This strips the quarantine flag entirely. Run it once after moving the app to /Applications.

CLI

# Run directly (no install needed):
go run github.com/sudorandom/protodocs/cmd/protodocs@latest [descriptor-files...]

# Or install permanently:
go install github.com/sudorandom/protodocs/cmd/protodocs@latest

# Serve a local descriptor file with proxy enabled:
protodocs --proxy my-api.binpb

# Connect to a live reflection server:
protodocs --reflection-url https://my-service.example.com

# Specify listen address:
protodocs --addr 127.0.0.1:9090 my-api.binpb

Self-Hosted Static Site

Extract protodocs-static.tar.gz to any static web host (Nginx, S3, GitHub Pages, Netlify, …):

tar -xzf protodocs-static.tar.gz -C /var/www/html/protodocs

Add a config.yaml in the web root to point at your descriptor files:

title: "My API Docs"
descriptor_files:
  - "/my-api.binpb"

Docker

docker run -d -p 8080:80 sudorandom/protodocs:latest
# Then open http://localhost:8080

Changelog

Installation

Choose the download that matches how you want to use ProtoDocs:

Artifact Platform Description
protodocs-desktop-darwin-universal.dmg macOS (Intel + Apple Silicon) Desktop app — drag to Applications
protodocs-desktop-windows-amd64.zip Windows x64 Desktop app — extract and run ProtoDocs.exe
protodocs-desktop-linux-amd64.tar.gz Linux x64 Desktop app — extract and run ProtoDocs
protodocs-cli-darwin-arm64.tar.gz macOS Apple Silicon CLI binary
protodocs-cli-darwin-amd64.tar.gz macOS Intel CLI binary
protodocs-cli-linux-arm64.tar.gz Linux ARM64 CLI binary
protodocs-cli-linux-amd64.tar.gz Linux x64 CLI binary
protodocs-cli-windows-amd64.zip Windows x64 CLI binary
protodocs-static.tar.gz Any web host Static HTML/JS bundle for self-hosting

Desktop App

The desktop app is the easiest way to browse .proto schemas locally — no server required.

Quick Start

  1. Download the .dmg (macOS), .zip (Windows), or .tar.gz (Linux) from the assets below.
  2. Install / extract the app.
  3. Launch ProtoDocs.
  4. At the schema loader, either:
    • Drag & drop a compiled descriptor file (.binpb or .pb) onto the window.
    • Click Open File and select your descriptor file.
    • Enter a reflection URL to connect to a live gRPC / Connect server with reflection enabled.
    • Click Load Demo to explore the built-in Eliza sample schema.

Generating a descriptor file from your .proto sources:

# Using buf:
buf build -o my-api.binpb

# Using protoc:
protoc --descriptor_set_out=my-api.binpb --include_imports your_file.proto

⚠️ macOS: "App is damaged" / Gatekeeper warning

The desktop builds are not code-signed or notarized. Code signing requires an Apple Developer account ($99/year), which this project doesn't have. macOS Gatekeeper will therefore block the app on first launch with a message like "ProtoDocs is damaged and can't be opened" or "ProtoDocs cannot be opened because the developer cannot be verified."

To open the app anyway:

Option A — Right-click method (recommended, one-time):

  1. In Finder, right-click (or Control-click) ProtoDocs.app.
  2. Choose Open from the context menu.
  3. Click Open in the confirmation dialog.

After doing this once, macOS remembers the exception and the app opens normally in the future.

Option B — Remove the quarantine attribute via Terminal:

xattr -dr com.apple.quarantine /Applications/ProtoDocs.app

This strips...

Read more
Loading

v0.1.2

v0.1.2

Choose a tag to compare

View all tags
@sudorandom sudorandom released this 25 Jun 15:42
v0.1.2
f3b9660
This commit was created on GitHub.com and signed with GitHub’s verified signature.
GPG key ID: B5690EEEBB952194
Verified
Learn about vigilant mode.

0.1.2 (2026-06-25)

Bug Fixes

  • support wkt when generating 'empty' json template (1381f70)

Installation

Choose the download that matches how you want to use ProtoDocs:

Artifact Platform Description
protodocs-desktop-darwin-universal.dmg macOS (Intel + Apple Silicon) Desktop app — drag to Applications
protodocs-desktop-windows-amd64.zip Windows x64 Desktop app — extract and run ProtoDocs.exe
protodocs-desktop-linux-amd64.tar.gz Linux x64 Desktop app — extract and run ProtoDocs
protodocs-cli-darwin-arm64.tar.gz macOS Apple Silicon CLI binary
protodocs-cli-darwin-amd64.tar.gz macOS Intel CLI binary
protodocs-cli-linux-arm64.tar.gz Linux ARM64 CLI binary
protodocs-cli-linux-amd64.tar.gz Linux x64 CLI binary
protodocs-cli-windows-amd64.zip Windows x64 CLI binary
protodocs-static.tar.gz Any web host Static HTML/JS bundle for self-hosting

Desktop App

The desktop app is the easiest way to browse .proto schemas locally — no server required.

Quick Start

  1. Download the .dmg (macOS), .zip (Windows), or .tar.gz (Linux) from the assets below.
  2. Install / extract the app.
  3. Launch ProtoDocs.
  4. At the schema loader, either:
    • Drag & drop a compiled descriptor file (.binpb or .pb) onto the window.
    • Click Open File and select your descriptor file.
    • Enter a reflection URL to connect to a live gRPC / Connect server with reflection enabled.
    • Click Load Demo to explore the built-in Eliza sample schema.

Generating a descriptor file from your .proto sources:

# Using buf:
buf build -o my-api.binpb

# Using protoc:
protoc --descriptor_set_out=my-api.binpb --include_imports your_file.proto

⚠️ macOS: "App is damaged" / Gatekeeper warning

The desktop builds are not code-signed or notarized. Code signing requires an Apple Developer account ($99/year), which this project doesn't have. macOS Gatekeeper will therefore block the app on first launch with a message like "ProtoDocs is damaged and can't be opened" or "ProtoDocs cannot be opened because the developer cannot be verified."

To open the app anyway:

Option A — Right-click method (recommended, one-time):

  1. In Finder, right-click (or Control-click) ProtoDocs.app.
  2. Choose Open from the context menu.
  3. Click Open in the confirmation dialog.

After doing this once, macOS remembers the exception and the app opens normally in the future.

Option B — Remove the quarantine attribute via Terminal:

xattr -dr com.apple.quarantine /Applications/ProtoDocs.app

This strips the quarantine flag entirely. Run it once after moving the app to /Applications.

CLI

# Run directly (no install needed):
go run github.com/sudorandom/protodocs/cmd/protodocs@latest [descriptor-files...]

# Or install permanently:
go install github.com/sudorandom/protodocs/cmd/protodocs@latest

# Serve a local descriptor file with proxy enabled:
protodocs --proxy my-api.binpb

# Connect to a live reflection server:
protodocs --reflection-url https://my-service.example.com

# Specify listen address:
protodocs --addr 127.0.0.1:9090 my-api.binpb

Self-Hosted Static Site

Extract protodocs-static.tar.gz to any static web host (Nginx, S3, GitHub Pages, Netlify, …):

tar -xzf protodocs-static.tar.gz -C /var/www/html/protodocs

Add a config.yaml in the web root to point at your descriptor files:

title: "My API Docs"
descriptor_files:
  - "/my-api.binpb"

Docker

docker run -d -p 8080:80 sudorandom/protodocs:latest
# Then open http://localhost:8080

Changelog

Installation

Choose the download that matches how you want to use ProtoDocs:

Artifact Platform Description
protodocs-desktop-darwin-universal.dmg macOS (Intel + Apple Silicon) Desktop app — drag to Applications
protodocs-desktop-windows-amd64.zip Windows x64 Desktop app — extract and run ProtoDocs.exe
protodocs-desktop-linux-amd64.tar.gz Linux x64 Desktop app — extract and run ProtoDocs
protodocs-cli-darwin-arm64.tar.gz macOS Apple Silicon CLI binary
protodocs-cli-darwin-amd64.tar.gz macOS Intel CLI binary
protodocs-cli-linux-arm64.tar.gz Linux ARM64 CLI binary
protodocs-cli-linux-amd64.tar.gz Linux x64 CLI binary
protodocs-cli-windows-amd64.zip Windows x64 CLI binary
protodocs-static.tar.gz Any web host Static HTML/JS bundle for self-hosting

Desktop App

The desktop app is the easiest way to browse .proto schemas locally — no server required.

Quick Start

  1. Download the .dmg (macOS), .zip (Windows), or .tar.gz (Linux) from the assets below.
  2. Install / extract the app.
  3. Launch ProtoDocs.
  4. At the schema loader, either:
    • Drag & drop a compiled descriptor file (.binpb or .pb) onto the window.
    • Click Open File and select your descriptor file.
    • Enter a reflection URL to connect to a live gRPC / Connect server with reflection enabled.
    • Click Load Demo to explore the built-in Eliza sample schema.

Generating a descriptor file from your .proto sources:

# Using buf:
buf build -o my-api.binpb

# Using protoc:
protoc --descriptor_set_out=my-api.binpb --include_imports your_file.proto

⚠️ macOS: "App is damaged" / Gatekeeper warning

The desktop builds are not code-signed or notarized. Code signing requires an Apple Developer account ($99/year), which this project doesn't have. macOS Gatekeeper will therefore block the app on first launch with a message like "ProtoDocs is damaged and can't be opened" or "ProtoDocs cannot be opened because the developer cannot be verified."

To open the app anyway:

Option A — Right-click method (recommended, one-time):

  1. In Finder, right-click (or Control-click) ProtoDocs.app.
  2. Choose Open from the context menu.
  3. Click Open in the confirmation dialog.

After doing this once, macOS remembers the exception and the app opens normally in the future.

Option B — Remove the quarantine attribute via Terminal:

xattr -dr com.apple.quarantine /Applications/ProtoDocs.app

This strips the quarantine flag entirely. Run it once after moving the app to /Applications.

CLI

# Run directly (no install needed):
go run github.com/sudorandom/protodocs/cmd/protodocs@latest [descriptor-files...]

# Or install permanently:
go install github.com/sudorandom/protodocs/cmd/protodocs@latest

# Serve a local descriptor file with proxy enabled:
protodocs --proxy my-api.binpb

# Connect to a live reflection server:
protodocs --reflection-url https://my-service.example.com

# Specify listen address:
protodocs --addr 127.0.0.1:9090 my-api.binpb

Self-Hosted Static Site

Extract protodocs-static.tar.gz to any static web host (Nginx, S3, GitHub Pages, Netlify, …):

tar -xzf protodocs-static.tar.gz -C /var/www/html/protodocs

Add a config.yaml in the web root to point at your descriptor files:

title: "My API Docs"
descriptor_files:
  - "/my-api.binpb"

Docker

docker run -d -p 8080:80 sudorandom/protodocs:latest
# Then open http://localhost:8080

Changelog

Installation

Choose the download that matches how you want to use ProtoDocs:

Artifact Platform Description
protodocs-desktop-darwin-universal.dmg macOS (Intel + Apple Silicon) Desktop app — drag to Applications
protodocs-desktop-windows-amd64.zip Windows x64 Desktop app — extract and run ProtoDocs.exe
protodocs-desktop-linux-amd64.tar.gz Linux x64 Desktop app — extract and run ProtoDocs
protodocs-cli-darwin-arm64.tar.gz macOS Apple Silicon CLI binary
protodocs-cli-darwin-amd64.tar.gz macOS Intel CLI binary
protodocs-cli-linux-arm64.tar.gz Linux ARM64 CLI binary
protodocs-cli-linux-amd64.tar.gz Linux x64 CLI binary
protodocs-cli-windows-amd64.zip Windows x64 CLI binary
protodocs-static.tar.gz Any web host Static HTML/JS bundle for self-hosting

Desktop App

The desktop app is the easiest way to browse .proto schemas locally — no server required.

Quick Start

  1. Download the .dmg (macOS), .zip (Windows), or .tar.gz (Linux) from the assets below.
  2. Install / extract the app.
  3. Launch ProtoDocs.
  4. At the schema loader, either:
    • Drag & drop a compiled descriptor file (.binpb or .pb) onto the window.
    • Click Open File and select your descriptor file.
    • Enter a reflection URL to connect to a live gRPC / Connect server with reflection enabled.
    • Click Load Demo to explore the built-in Eliza sample schema.

Generating a descriptor file from your .proto sources:

# Using buf:
buf build -o my-api.binpb

# Using protoc:
protoc --descriptor_set_out=my-api.binpb --include_imports your_file.proto

⚠️ macOS: "App is damaged" / Gatekeeper warning

The desktop builds are not code-signed or notarized. Code signing requires an Apple Developer account ($99/year), which this project doesn't have. macOS Gatekeeper will therefore block the app on first launch with a message like "ProtoDocs is damaged and can't be opened" or "ProtoDocs cannot be opened because the developer cannot be verified."

To open the app anyway:

Option A — Right-click method (recommended, one-time):

  1. In Finder, right-click (or Control-click) ProtoDocs.app.
  2. Choose **O...
Read more
Loading

v0.1.1

v0.1.1

Choose a tag to compare

View all tags
@sudorandom sudorandom released this 24 Jun 16:24
v0.1.1
23d8c2d
This commit was created on GitHub.com and signed with GitHub’s verified signature.
GPG key ID: B5690EEEBB952194
Verified
Learn about vigilant mode.

0.1.1 (2026-06-24)

Bug Fixes

Loading