Distribution checked 12 September 2026: GitHub, signed APT, Homebrew and Scoop are
live. Microsoft Store is in certification and will publish automatically after
approval. The corrected Snap artifact is on GitHub; the exact protopeek name
is reserved outside this account. Name resolution and classic review remain.
Snap Store and Flatpak are not published.
See the shared publication status.
Official downloads and package links: ProtoPeek distribution tracker. Stable release, Homebrew and Scoop links are kept separate from planned distribution channels.
Microsoft Store: MSIX preparation and release automation are in progress. The name is reserved; there is no published Store download yet.
Stable GitHub releases also include protopeek_<version>_amd64.snap. The
candidate uses classic confinement so ProtoPeek can inspect local sockets and
invoke explicitly installed tools such as Tailscale, Nmap, dumpcap, aria2, and
cloudflared. The Snap Store candidate workflow is manual and credential-gated;
publication is not claimed until the package has passed a Linux desktop smoke
test.
Agent discovery resources are published with the website: the API catalog, OpenAPI document, ARD manifest, MCP Server Card, and Auth metadata.
ProtoPeek (Protocol Peek) is a lightweight local workbench for finding, reaching, inspecting and publishing services. Inspect gRPC, HTTP, WebSocket, SSE and Cap’n Proto; discover ports and private network services; follow network hops; examine packet metadata and this device’s activity; manage local Tailscale and Cloudflare tools; and queue resumable downloads without an external database.
Built by Shreyam Adhikari · Website · Docs · Learn gRPC
Latest stable: v0.6.1. Six permanent destinations: Home, Inspect, Network, Publish, Files and Settings. The verified installers resolve stable releases; Nightly is an explicit opt-in. Windows x64 includes aria2 inside the executable. Other platforms use installed aria2.
Vertical protocol/settings tabs, independent scrolling, recoverable drafts and fuzzy command search keep the workbench practical on a desktop. HTTP recipes and appearance belong to the browser origin; download configuration, resumable jobs and bounded completed history belong to the local host. Closing the browser leaves active downloads running while ProtoPeek stays open. Restarting the server restores recoverable queue state for explicit resume.
See the release notes, feature roadmap and acceptance record for measured behavior and limitations.
The current-source UI overhaul adds a persistent tool navigator, last-tool destination resume, shared headers and loading states, compact connection flows, and a searchable roadmap. It is available on the explicit edge channel; stable remains v0.6.1.
Actual edge capture from verified implementation 1970338. Browser acceptance
records 776 UI tests, cross-platform CI, real requests and transfers, and the remaining native-tool gaps.
New in current source: local AI agents attach through protopeek mcp
or the JSON CLI. Pair from Settings → AI agents to share HTTP, listener, port/route, Tailscale
inspection and download tools with visible results and cancellation. This addition is not in
the v0.6.1 stable binaries. It uses your agent's model; ProtoPeek itself runs no model.
v0.6.1 has six permanent destinations:
| Destination | Responsibility | Current and compatibility paths retained |
|---|---|---|
| Home | resume and bounded discovery | / |
| Inspect | gRPC, HTTP, WebSocket/SSE, Cap’n Proto, website and TLS evidence | /protocols, /protocols/grpc, /protocols/http, /security, /grpc, /http |
| Network | this device, next hop, path, authorized discovery, map, and history | /network/*, /this-pc, /routes |
| Publish | Cloudflare host evidence and guarded service actions | /tunnels |
| Files | Downloader and artifact evidence | /downloader, /downloads |
| Settings | appearance, local dependencies, host policy, and About | /settings, /roadmap |
Existing deep links remain valid. Installed Tailscale status, peers, netcheck and reviewed CLI actions are available under Network. Headscale, NetBird, integrated sign-in/elevation and Tailscale Serve/Funnel remain planned. A feature belongs in ProtoPeek only when it operates on a service or related artifact, strengthens an existing journey or typed handoff, remains useful local-first, stays lazy/bounded/quiet, and has a truthful Windows, Linux, and macOS story that one maintainer can support. See the suite strategy and selected desktop workbench contract.
Roadmap and Help remain available through commands and About/documentation, not as permanent destinations.
The screenshot is a real local Chrome capture of the v0.3.0 embedded dashboard. It remains versioned as historical shipped-product evidence; the release gallery also includes real v0.5.0 Downloader captures.
Debian / Ubuntu: add the signed APT repository once, then run
sudo apt update && sudo apt install protopeek. Includes the pp alias.
Ubuntu amd64 installation and removal through the public HTTPS repository passed
on 12 September 2026. Snap Store publication is still pending.
Homebrew on macOS or Linux:
brew install shreyam1008/tap/protopeekScoop on Windows:
scoop bucket add shreyam https://github.com/shreyam1008/scoop-bucket
scoop install shreyam/protopeekOr use the verified release resolver on Unix:
curl -fsSL https://raw.githubusercontent.com/shreyam1008/ProtoPeek/master/install.sh | shOr with wget:
wget -qO- https://raw.githubusercontent.com/shreyam1008/ProtoPeek/master/install.sh | shWindows PowerShell, per user:
irm https://raw.githubusercontent.com/shreyam1008/ProtoPeek/master/install.ps1 | iexThe verified installers select the latest stable release and verify its published SHA-256 archive. Windows x64 bundles pinned aria2 1.37.0, with its notices and source companion included in release packaging. A configured executable takes priority, followed by PATH and then the bundle. Homebrew and Scoop can supply aria2 as a package dependency; see their manifests for the packaged version. The install guide covers updates, pinned releases, PATH, rollback and uninstall.
New on Nightly: run pp update or protopeek update on Windows, macOS, or Linux.
Use --check to check only and --channel stable|nightly|edge to choose a channel; the default
follows the installed channel. Settings → Updates provides the same release preview,
explicit install confirmation, cancellation and restart guidance. Direct installs verify
SHA-256 and update both owned commands; managed installs show the manager's commands.
Older binaries need one installer upgrade to a Nightly build containing this command first.
Set PROTOPEEK_CHANNEL=nightly when running the installer; see Nightly setup.
Pushes to main/master refresh one rolling Nightly prerelease. Stable stays v0.6.1;
new stable versions and package updates require explicit promotion. Legacy Edge is manual-only.
Go fallback:
go install github.com/shreyam1008/ProtoPeek/cmd/protopeek@latest
go install github.com/shreyam1008/ProtoPeek/cmd/pp@latestpp # Home workbench
pp localhost # Home + bounded inspection of localhost:50051 and :443
pp https://api.example.test # Home + inspection of the stated/default verified-TLS port
pp -plaintext localhost:50051 # exact direct mode in gRPC under InspectIn v0.6.1, Home opens at / with side navigation for Home, Inspect, Network, Publish, Files and
Settings. Legacy /grpc, /http, /routes and /downloads links remain compatible.
v0.6.1 retains /this-pc as the canonical deep link for This Device under Network. Its
first render is local-only: it reads capabilities, hostname/OS/architecture, and bounded interface
evidence from the running ProtoPeek process. Linux and native Windows can explicitly inspect bounded
TCP/UDP socket ownership and sample aggregate interface counters; macOS reports both operations as
unsupported. Windows process basenames are best-effort and permission-sensitive, and a Windows UDP
bind is endpoint evidence, not proof that an application receives datagrams. Public IPv4/IPv6 and
BGP-origin lookup and the small Cloudflare quality run remain separate user-triggered operations.
An eligible fresh, unscoped TCP listener can open typed unsent HTTP, gRPC, next-hop, or Publish
drafts, but consuming a handoff performs no DNS, probe, connection, request, or publishing action. A
traffic rate uses the measured interval between representative counter reads rather than merely the
selected wait; partial reads compare only interfaces present in both observations and remain
labelled. A local listener is never presented as an Internet-open port, interface counters are never
presented as per-process traffic, and provider throughput is never presented as the ISP line maximum.
Current-source scan and inspection actions start directly from their action buttons,
with visible request disclosures, elapsed-time feedback, progress, and cancellation.
The current-source port scanner supports all 65,535 TCP ports on one IP through cancellable batches with progress and partial results. Large results remain in the tab.
The current-source port scanner connects loopback checks, private-network discovery, and single-IP scans. Discovered devices can prefill a port scan, and “What can I scan?” explains the available checks before you run them.
The current-source socket table adds port-first rows, numeric sorting, combined search and TCP/UDP filters, and snapshot counts for ports and observed processes.
See the This Device boundary and Connected Workbench contract.
v0.6.1 retains /tunnels as the canonical deep link for the domain-native Cloudflare
Tunnel workspace under Publish. It performs no work until Inspect this host is chosen, then
uses the real host adapter to read only the canonical cloudflared OS service, documented config
candidates, and bounded executable metadata. An absent executable or service is a valid empty
result, never replaced by a sample deployment. It identifies effective versus competing YAML,
redacts credential values, and shows ingress routes with parsed counts that include the final
catch-all. A remote-managed connector retains Cloudflare account authority and no local YAML
destination. ProtoPeek detects Wrangler and Docker without reusing Wrangler authentication or
contacting the Docker daemon. A separate Check latest version action reads the official latest
GitHub release; no
release request runs on load. Confirmed start/stop/restart actions target only the canonical
Windows SCM, systemd, or launchd service, reject stale state, and verify the re-observed result. If
permission is missing, the OS—not ProtoPeek—owns any Administrator/UAC/sudo password interaction.
Installation, updates, route/config writes, and Cloudflare account/cloud mutation never run
automatically. Draft ingress route treats paths as regular expressions (for example,
^/api/.*) and remains a browser-only preview with no Apply action.
A new gRPC target defaults to localhost:50051; each saved
target keeps its own plaintext/TLS settings, authority override, schema source (reflection, a
browser-folder snapshot, host proto paths, or host protoset paths), and cert paths. A new HTTP draft
defaults to http://localhost:8080/. Exact localhost, 127.0.0.1, and [::1] shorthand may omit
the scheme and is normalized to HTTP; every non-loopback host must state http:// or https://.
HTTP history shows its 12 newest secret-safe entries with total observed time, and JSON formatting
is optional—invalid JSON remains sendable verbatim. You can also import an explicit,
bounded OpenAPI 3.x or Swagger 2.0 JSON definition by file or URL, including a Swagger UI or Scalar
page that exposes its linked JSON definition. Light is the first-run theme; dark mode and local
histories are stored only in the browser profile.
v0.5.0 adds a local Downloader surface plus one explicit one-shot transfer command. The browser queues one URL or up to 32 independent jobs, reports partial batch success without retrying jobs that already started, supports per-job destination, bounded request headers and User-Agent, and exposes job and whole-queue pause/resume controls. Output naming and expected SHA-256 remain single-job options so evidence cannot be applied to the wrong artifact.
Exact retry/resume requires the source URL and any supplied headers. The form clears those values after queueing and queue/API results never return them, but ProtoPeek and aria2c retain the required values in private local host state (mode 0600 where supported). Do not use credentials on a machine whose local account or transfer-state directory you do not trust.
The CLI contract remains deliberately smaller:
pp download [--output NAME] [--sha256 64_HEX] URLIt accepts exactly one absolute HTTP(S) URL and uses configured, PATH or bundled Windows x64
aria2c, in that order. The command owns its local engine session, writes progress
to stderr, prints only the completed path to stdout, and preserves partial data plus the aria2
session when interrupted. It does not attach to an already-running ProtoPeek process. The command
ships in v0.5.0 and is available through the release installers, Homebrew, and Scoop.
v0.5.0 also includes a read-first, non-destructive GoBarryGo state bridge:
pp migrate-gobarry # preview only; no writes
pp migrate-gobarry --apply # copy compatible state
pp migrate-gobarry --rollback RECEIPT_ID # guarded restoreThe preview reads only GoBarryGo's known local profile after the command or Settings action is explicitly invoked. Import keeps the original preferences, session, executable cache, and downloaded files untouched; compatible HTTP(S) session jobs enter ProtoPeek paused, unsafe options are rejected, and a mode-0600 receipt records source hashes, exact before/after target hashes, and private backups. Proposed setting conversions remain preview-only. Rollback proceeds only when the current ProtoPeek config/session still match that receipt, otherwise it refuses and preserves the newer state. The bridge does not retire the standalone GoBarryGo v0.0.9 release. Its public redirect and repository retirement remain incomplete and separately gated.
For a server without reflection, choose Browser folder and then Choose folder. ProtoPeek
preserves relative imports and uploads only lowercase .proto files when Connect is pressed. The
snapshot is bounded to 512 files, 4 MiB per file, and 16 MiB total. It goes to the machine or
container running this ProtoPeek instance, never to the gRPC target. ProtoPeek compiles the bounded
bytes in memory and clears the upload buffers before dialing or publishing the session. Every import
must resolve inside the selected root (apart from built-in Google well-known protos). Folder handles,
file bytes, root names, and temporary paths are never saved; a saved browser-folder target therefore
requires a fresh selection after reload.
Host proto paths and Host protoset paths remain separate advanced modes. Those values are read by the ProtoPeek process, so a path in a remotely opened or containerized console is not a path on the browser machine. A JSON schema connection accepts at most 128 proto entry paths, 64 import roots, or 32 protoset paths; each path is at most 4,096 UTF-8 bytes and all configured paths share a 32 KiB budget. Explicit proto entry and protoset files must be regular files and are preflighted before dialing or parsing at 4 MiB each and 16 MiB total. An import root grants the host process authority to resolve referenced imports under that root; ProtoPeek does not pre-read every file in the directory. Parsed imports are instead covered by the retained descriptor limits below.
At most two non-upload workspace schema connections run per manager. Reflection resolves exposed services incrementally and stops requesting descriptors when a limit is reached instead of issuing an unbounded all-files fetch. Before any reflection, host-path, protoset, or browser-folder session is published, ProtoPeek retains at most 512 services, 10,000 methods, 1,024 descriptor files, 10,000 messages, 50,000 fields, 4,096 enums, 50,000 enum values, and 32 levels of message nesting, plus 8 MiB of serialized descriptors and a 16 MiB generated schema catalog. Structural limits run before catalog summaries and proto text are materialized. Cancellation and manager shutdown stop work before dialing or publication wherever the parser/transport permits. Limit and parse errors identify the source and corrective action without echoing schema contents or metadata values.
Ambient discovery checks only a fixed list of loopback candidates. A private or link-local IP requires the per-scan private-network opt-in. A public address or hostname is accepted only as the single explicit target: ProtoPeek does not expand it into an arbitrary port scan. Hostnames are resolved once, every returned address is classified against that opt-in, and probes dial a validated numeric address so DNS cannot silently change the destination between policy and connection. Passing that explicit target to the CLI opens the same visible scan dialog. A host without a port tries only 50051 with plaintext and 443 with verified TLS; an explicit HTTP(S) authority uses its stated or default port. Each candidate has fixed time limits and can report verified gRPC, a safe non-following HTTP HEAD response, or open TCP evidence. At most two scan requests run at once; retained service names, reflection responses, HTTP fields, errors, and details have explicit byte limits, and the result says when evidence was truncated. Scans are cancellable, never follow redirects, and never send a state-changing request.
Next-hop lookup asks the local kernel for one currently selected route per resolved address from the ProtoPeek process. It resolves at most eight addresses, performs at most four route lookups concurrently, and requests a two-second aggregate deadline. It reports source address, interface, reported gateway or on-link status, prefix, and metric/table when the platform provides them. It is not traceroute: it performs no hop probes, mutates no routes, and requires no elevation. Entering a hostname can still perform normal DNS resolution. VPN, proxy, policy-routing, ECMP, and later route changes remain explicit sources of uncertainty.
Network Path adds a separate active observation. Linux uses ProtoPeek's built-in unprivileged UDP error-queue backend; it does not shell out, install a tool, or request root. A trace resolves once, pins one numeric address, retains bounded DNS answers and the kernel-selected route, then preserves every per-TTL probe sample—including timeouts and multiple responders. The default plan is 24 hops × 3 probes; hard bounds are 32 hops, 4 probes per hop, 96 probes total, 100–2,000 ms per probe, a 30-second wall, and 20 probes per second. Returned total duration is accepted only through the selected wall plus a fixed 2-second resolver/return allowance; that allowance is not extra probe time or a latency measurement. Every RTT is round-trip time from the ProtoPeek process to one responder, never claimed as latency between adjacent hops. Minimum, median, and maximum values are calculated independently per responder instead of blending ECMP replies. The destination median appears only when reply samples came from the exact pinned destination; ProtoPeek never substitutes the last responding router. Silent hops do not prove a device is down, and ECMP or other load balancing can produce several responders at one TTL. The Run action starts the displayed active probe plan, including public targets. Windows uses native IPv4/IPv6 ICMP echo; Darwin currently reports active hop probing as unsupported. No elevation is requested. Optional, explicitly requested IPWHOIS labels add dated ASN/ISP and approximate location evidence to responding public IPs. Local addresses are skipped, and labels survive saving the trace.
Network opens Nearby devices with an available local interface selected and a map/list of this computer plus cached neighbors. Choose a device to inspect its ports or prepare a local traffic capture. Neither opening the page nor these handoffs starts a scan or capture. Scan network adds fresh bounded TCP and mDNS/DNS-SD evidence, including advertised names/services when received. Device types remain source-backed clues, and cached addresses are not a live device census.
Local network discovery is an explicit operation. Its capability check reads interface metadata,
the OS neighbor cache, and the selected route. A scan accepts an authorized RFC 1918 IPv4 CIDR no broader than
/24 and one visible TCP profile. The capability response returns at most 32 deduplicated interface
suggestions and omits a configured CIDR unless the whole prefix is inside one RFC 1918 block; a
broad accepted interface is suggested as its containing /24. Each profile exposes both ports
and the exact applicationProbePorts: Quick uses 80, 443, 50051, 8080 for both; gRPC common uses
443, 6565, 7000, 7443, 9090, 50051 for both; Web/API uses 80, 443, 3000, 4000, 5000, 8000, 8080, 8443 for both; Expanded selects 22, 53, 80, 443, 445, 631, 1883, 3000, 3306, 3389, 5432, 6379, 8000, 8080, 8443, 9090, 9100, 50051, but its application subset is only 80, 443, 3000, 8000, 8080, 8443, 9090, 50051.
Application-probe ports may receive bounded gRPC reflection plus HTTP HEAD /; redirects are off.
Every other selected port—including Expanded's 22, 53, 445, 631, 1883, 3306, 3389, 5432, 6379, 9100—receives a TCP connect only. Limits are 18 ports, 4,572 attempts, 32 workers, 15 seconds, and
one scan at a time. A 64 KiB aggregate verbose-evidence budget can omit additional protocol detail,
but every observed open-port record remains. probeDurationMs is the full elapsed duration of that
TCP-connect or application probe, not network latency. attemptsCompleted counts selected endpoint
probe calls that returned, including cancellation returns; it is not an open-port,
successful-connect, or reached-target count. Only positive selected-TCP evidence is retained. An
absent address is not labeled offline, and inferred roles are never presented as OS,
hardware, ownership, VLAN, or physical-link evidence.
Path and discovery evidence can be saved into a versioned protopeek-network JSON workspace with
editable labels, tags, notes, groups, positions, and immutable snapshots. Appending a later
observation preserves saved manual labels, tags, notes, pinned positions, group assignments, manual
groups, and manual relationships instead of replacing them with scanner output. Unsaved edits are
guarded before switching workspaces, importing, appending an observation, restoring history,
deleting, unloading, or leaving the network workbench; the user must save or deliberately discard
them. Saved path responders are observed; silent-hop placeholders, an unconfirmed synthetic
destination, and logical trace-adjacency edges are inferred. Scoped IPv6 identities are retained
only with a bounded safe interface zone. The map is logical evidence, not physical topology. Its
interactive canvas is capped at 160 nodes, 640 relationships, and 64 groups; larger workspaces use
a complete 100-record paged inventory instead of dropping evidence.
IndexedDB persistence uses a 20-record bounded cursor restore and refuses overflow instead of evicting old work: at most 20 workspaces, 4 MiB each, and 32 MiB total. Compare-and-swap writes and deletes reject a stale cross-tab copy without overwriting it. A failed persistent delete keeps the workspace visibly present, while denial, quota failure, unavailability, or corrupt/overflow restore produces a visible session-only fallback. Historical snapshot restore takes two explicit actions and replaces only the editable current map. Canonical JSON is the lossless import/export path. GraphML is lossy and accepts only one flat directed graph; undirected or mixed edges, nested graphs, hyperedges, ports, duplicate structures, and XML 1.0-invalid controls are rejected rather than reinterpreted. CSV is an export-only flat inventory.
The Scan dialog can also import up to 8 MiB of XML previously written by nmap -oX, without Nmap installed. Current source additionally offers Network → Nmap for an installed Nmap: one literal IP or an authorized private IPv4 /24-or-smaller subnet, TCP connect or light service detection, an exact scope preview, cancellation, and JSON export. It does not bundle or install Nmap/Npcap and accepts no arbitrary arguments. See the Nmap workflow for limits. Imported or scanned service labels remain hints; Inspect service opens the selected endpoint for explicit verification before gRPC or HTTP. Uploaded XML and scanned inventory are not persisted automatically.
One running ProtoPeek handler also shares small admission budgets across browser sessions: eight
ordinary gRPC invokes total across the direct and workspace paths, four HTTP relays, and two native
route requests. Method and CSRF policy run before admission; a full budget returns 429 Too Many Requests with no-store and nosniff before reading the rejected body or starting network work.
Success, validation failure, cancellation, panic unwinding, and workspace-session deletion release
their slots. These process budgets are separate from—and do not replace—the existing per-request
candidate, message, redirect, address, and route-worker caps.
Each admitted ordinary gRPC invoke retains at most 512 response messages and 8 MiB of serialized response-message JSON. Message 513 or the first message that would cross the byte boundary cancels the RPC and returns the retained headers/messages as explicitly partial local-limit evidence; ProtoPeek does not invent a server status or trailers. Exactly 512 messages or exactly 8 MiB may still finish normally. An omitted or greater-than-60-second deadline receives a 60-second local handler wall, while a positive user deadline at or below 60 seconds remains unchanged.
| Surface | What it does |
|---|---|
| Method rail | Search and filter reflected services/methods with clear unary and streaming modes |
| Target registry | Save and switch gRPC endpoints without restarting |
| Local discovery | Distinguish reflection, gRPC-without-reflection, safe HTTP response evidence, and open TCP with bounded loopback and explicit-target policies |
| Next-hop evidence | Read one kernel-selected route per resolved address from the ProtoPeek process without hop probes, polling, privilege, or route mutation |
| Network Path | On Linux, resolve and pin one destination, retain kernel-route context, and run consented unprivileged UDP probes with truthful per-TTL source RTT, silent hops, ECMP responders, and fixed limits |
| Private-network inventory | Preview one RFC 1918 IPv4 /24-or-smaller plan; only profile-declared application ports receive bounded gRPC/HTTP probes, every other selected port is TCP-connect-only, and full probe duration is not labeled network latency |
| Topology notebook | Save tagged immutable snapshots, preserve manual annotations across later observations, guard unsaved edits, and use a bounded logical canvas with a complete paged-list fallback—never a physical-link or VLAN claim |
| Network exchange | Use canonical protopeek-network JSON for lossless round trips, one-flat-directed-graph disclosed-loss GraphML, and CSV for flat inventory export |
| Offline Nmap import | Parse bounded nmap -oX host/port hints and require ProtoPeek verification before opening a workbench |
| Payload generator | Scaffold JSON from reflected protobuf schemas |
| Browser proto folder | Upload one bounded, temporary .proto snapshot with nested imports while keeping browser handles and server paths out of saved profiles |
| Proto explorer | Browse files, messages, enums, deps; export .proto or catalog JSON |
| Metadata and auth | Editable live metadata, Bearer helper, and deadlines; automatic history and default exports redact credentials and binary metadata |
| Saved gRPC requests | Keep secret-sanitized gRPC recipes locally, replay them, and import/export workspace JSON |
| Unary Repeat | Run 2–50 sequential unary checks with cancellation, explicit deadlines, a 60 s cap, separate gRPC status and relay/transport failures, and honest handler-vs-console timing |
| gRPC Health | Run canonical grpc.health.v1 Check or one bounded live Watch with headers, transitions, trailers, cancellation, and final gRPC status kept distinct |
| Response timeline | Ordered messages with callback-observed timing, filtering, copy/export, headers, trailers, and final status |
| Fast controls | Cancel active calls, Cmd/Ctrl+Enter to invoke, / to search, and Cmd/Ctrl+K for commands |
| Assertions | Validate status, latency, metadata, and payload text locally |
| Transport lens | gRPC-Web, Envoy bridging, and transport context alongside the console |
| HTTP workbench | Send bounded HTTP(S) requests with method, URL, params, headers, auth, body, timeout, cancellation, redirect policy, and native response evidence; import OpenAPI/Swagger JSON; save up to 50 named requests with explicit body opt-in; load saved requests through fuzzy global search without sending; export redacted cURL |
| Downloader · v0.5.0 | Queue 1–32 independent HTTP(S) jobs with partial-success reporting, shared bounded per-job destination/headers/User-Agent, job and whole-queue controls, single-job naming/SHA-256 evidence, or one explicit pp download; configured/system aria2c, never bundled |
| Security evidence · v0.5.0 | With separate disclosures and consent, query historical certificate-name candidates through crt.name or send exactly one public-only, non-following, bodyless HEAD with pinned DNS/TLS/HTTP evidence; no security score |
| Website workbench · current source | Side sections for response/TLS, five standard-path HEAD checks and historical indexed names; rejected-certificate evidence, JSON exports, name filtering and reviewed Inspect handoffs; bounded browser-local origin/domain memory |
| This Device · current source after v0.5.0 | Read process-perspective identity and interfaces locally; explicitly inspect bounded Linux or native Windows TCP/UDP socket-owner evidence, sample aggregate interface load once, observe public IPv4/IPv6 plus provider-reported BGP origin, or run an opt-in, data-bounded Cloudflare connection-quality plan; Windows owner labels are best-effort, macOS activity/counters remain unsupported, and there is no ambient monitor or Internet-open-port claim |
| Cloudflare Tunnel · current source after v0.5.0 | Explicitly inspect the real host for cloudflared, the canonical Windows SCM/systemd/launchd service, config authority, and parsed routes including catch-all; manually compare the installed version with the official release; confirm and verify canonical-service start/stop/restart with stale-state protection and OS-owned elevation guidance; Draft ingress route uses regex paths and stays browser-only, remote-managed drafts have no local YAML destination, and there is no secret/password collection, automatic install/update, config mutation, Docker daemon call, or account/cloud mutation |
gRPC timing is cumulative from invoke start and marks lifecycle boundaries observed by ProtoPeek's grpcurl handler callbacks and invoke return. Unary callbacks may cluster after transport completion; the values are not packet-arrival, server-processing, or TTFB measurements. Handler invoke duration includes JSON/protobuf conversion and callbacks but excludes the browser/HTTP relay; console round trip includes that relay and response parsing. Every Unary Repeat attempt is a real RPC that may mutate service data; protobuf descriptors do not reliably guarantee idempotency.
While Repeat owns the request, assertions are disabled and ordinary Invoke is refused. Leaving Checks cancels the run and preserves partial evidence instead of continuing hidden. Completed results retain their run-start timestamp and frozen count, think time, and deadline; changed controls are marked as a previous run.
Unary Repeat export includes the method, target, run ID/start timestamp, frozen configuration, counts, per-attempt offsets/timings, classifications, and error/status text. It excludes request bodies and metadata; review internal addresses and service/relay text before sharing.
Health is an explicit diagnostic, never background polling. A blank service asks for overall server
health; an unknown named service is canonical NOT_FOUND for Check and SERVICE_UNKNOWN for Watch.
Watch observes one selected backend connection for 1–600 seconds, retains the latest 200 of at most
512 status observations, and never retries. Its timestamps are ProtoPeek handler/relay observations,
not server emission time or fleet-wide proof. Health results and request metadata are neither saved
nor exported.
Workspace export writes the explicit protopeek-workspace version 1 format. The default export
contains saved requests, environments, assertions, and inactive target profiles, but excludes
automatic RPC history. Saved request bodies are deliberate workspace data, so review them before
sharing a file. Import rejects files larger than 4 MiB before reading them, validates bounded
collections and strings, contains errors inside the running console, and never connects an imported
target. Imported host proto, protoset, CA, client-certificate, and key paths are paths on the machine
running ProtoPeek; explicitly connecting that profile authorizes the ProtoPeek process to read those
local paths. Browser-folder profiles contain no folder handle, file bytes, root name, or path and
remain inactive until the user chooses a fresh folder and explicitly connects.
Every deliberate workspace write is validated before it reaches browser storage. Full saved-request, environment, and target lists refuse the new item instead of evicting an older one. If an existing section is malformed or over its bound, ProtoPeek keeps the exact readable original untouched, recovers only valid bounded records for the live session, and offers separate download and explicit adoption actions. A normal export remains paused until that recovery is resolved.
Saved and historical gRPC requests are scoped to the target/profile that created them. Legacy
unscoped records remain usable when their method exists, then bind to the current target on first
replay. Redacted metadata is restored blank with a re-entry warning, and blank or [redacted]
sensitive metadata is never sent. Automatic HTTP history retains the URL, method, a small allowlist
of non-credential header values, and response summary—not request bodies. It strips URL user info,
redacts credential-like query values and every header outside that allowlist, then resets all
non-persisted request/response settings on replay. Opening a newly discovered HTTP origin also
cancels and invalidates prior work before starting from a clean GET request.
Copy as cURL is an explicit export-only action. Send and Copy first apply the same URL, user-info, header, body, and timeout validation; the command preserves the prepared method, duplicate query parameters, non-sensitive headers, timeout, and active body while omitting auth and credential-like headers and leaving credential-like URL values blank. Redirect-enabled drafts are refused because one portable cURL command cannot reproduce ProtoPeek's bounded redirect, method/header, and HTTPS downgrade policy. Export inspects at most 64 effective headers and refuses commands over 512 KiB. Request bodies are deliberate user-authored content and are copied verbatim, so review the command before sharing or running it. The command runs in your shell rather than ProtoPeek's relay, so DNS, network namespace, proxies, trust roots, and implicit cURL headers can differ. cURL import is not included yet.
ProtoPeek is intentionally broader than a gRPC-only brand, but intentionally narrower than a generic cloud API platform. The desktop shell owns navigation, session/context chrome, appearance, and bounded action entry. Each domain workbench owns its target and evidence workflow, while each adapter owns discovery, schema, invocation, cancellation, and its native inspector.
| Adapter | Status | First useful slice |
|---|---|---|
| gRPC | Stable · v0.3.0 | Reflection, temporary browser-folder snapshots, host .proto/protoset sources, unary and streaming calls, canonical Health Check/Watch, metadata, headers, trailers, status, callback-observed handler lifecycle timing, and bounded Unary Repeat |
| HTTP / REST | Stable · v0.6.1 | Standard-library HTTP(S), method, URL, headers, body, timeout, redirect choice, cancellation, status, protocol, timing, bounded text/base64 response bodies, and explicit OpenAPI 3.x or Swagger 2.0 JSON import |
| WebSocket / SSE | Stable · v0.6.1 | Inspect → Event streams: real text/binary WebSocket sends, named SSE events and IDs, headers, subprotocols, verified TLS, bounded timelines, disconnect and navigation cleanup |
| Host port scanner | Stable · v0.6.1 | Up to 1024 chosen TCP ports on one local or remote IP, presets/ranges, open/refused/timeout results, IPv4/IPv6, cancellation, and a protocol-inspection handoff |
| Next-hop route evidence | Shipped · v0.3.0 | Read-only Linux netlink, Darwin routing socket, or Windows GetBestRoute2; one process-perspective route per resolved address, no hop probes |
| Network Path | Shipped · v0.4.0 · Linux | Built-in unprivileged UDP error-queue tracing with separate DNS, route, per-TTL sample, and source-RTT evidence; active probes require explicit consent |
| Windows Network Path | Stable · v0.6.1 | Native IPv4/IPv6 ICMP echo tracing, automatic backend choice, per-hop RTT/status, bounded probes and cancellation without installing traceroute or requesting elevation |
| Private-network discovery | Shipped · v0.4.0 | Authorized RFC 1918 IPv4 /24-or-smaller profiles with exact application-inspection versus TCP-connect-only ports, full-probe duration, cancellation, positive evidence only, and a 64 KiB aggregate verbose-detail budget |
| Network topology | Shipped · v0.4.0 | Inference-labelled logical canvas, complete paged-list fallback, immutable snapshots, manual-field preservation, unsaved-edit/stale-tab guards, bounded browser persistence, canonical JSON, strict disclosed-loss GraphML, and CSV inventory |
| Nmap XML evidence | Shipped · v0.3.0 · optional input | Bounded streaming offline import; Nmap is not required to import a file |
| Installed Nmap | Stable · v0.6.1 | Explicit bounded TCP connect or light service scans, private subnet scope preview, cancellation, paginated evidence, export and Inspect handoff |
| Downloader | Shipped · v0.5.0 | Configured or system aria2c; 1–32 independent jobs, partial-success reporting, per-job destination/headers/User-Agent, job and whole-queue controls, single-job SHA-256 evidence, and one explicit pp download; bundled Windows x64 aria2 fallback |
| Security evidence | Shipped · v0.5.0 | Disclosed crt.name historical candidates plus a separate consented, public-only, non-following one-HEAD observation with pinned DNS/TLS/HTTP evidence and no score |
| This Device | Stable · v0.6.1 | Device-centred identity/interfaces, bounded Linux or native Windows local socket/process evidence and one-shot interface load, eligible fresh TCP-listener drafts, explicit public IPv4/IPv6 and BGP-origin observation, and a route-lazy bounded Cloudflare quality plan; macOS activity/counters remain unsupported, with no background work, privilege, automatic handoff action, or public-port verdict |
| Cloudflare Tunnel | Stable · v0.6.1 · local operations foundation | Manual real-host discovery of cloudflared, canonical service state, effective and competing YAML, ingress routes, redacted credential source, and optional Wrangler/Docker; explicit latest-release comparison and confirmed, stale-guarded canonical-service start/stop/restart; installation/update, route/config mutation, credentials, and account/cloud access remain user-owned or gated |
| Tailscale client | Stable · v0.6.1 | Network → Tailscale reads installed-client peers, accounts and routes; prepared service inspection, reviewed connection/account/exit-node actions, diagnostics and Taildrop. Integrated sign-in/elevation, Headscale administration and NetBird remain open work |
| Cap’n Proto | Stable · v0.6.1 | Source/compiled schema loading, concrete bootstrap RPC, exact integers, verified TLS, cancellation and JSON export; optional external source compiler |
| Packet inspection | Stable · v0.6.1 | PCAP/PCAPNG metadata, packet filtering/details/export; explicit installed dumpcap adapter with native live-capture acceptance still pending |
| Darwin active hop probes | Remaining work | Windows IPv4/IPv6 and Linux UDP are implemented; Darwin needs a verified native backend |
| Bundled Nmap execution | Not planned for the core binary | Existing XML import stays dependency-free; any future opt-in companion needs explicit executable choice, previewed scope, hard budgets, and an auditable command |
| Broader or public range discovery | Not planned for the core flow | Current discovery remains selected TCP ports inside one authorized RFC 1918 IPv4 /24-or-smaller scope |
| SMTP, FTP, and others | Later | Only after protocol-specific security, evidence, and UX are designed |
Bundled Nmap execution is not planned for the core binary. Active path and private-network operations never start on page load and remain distinct from the passive kernel-route lookup and offline Nmap XML import. Wider range expansion remains gated; live capture requires separately installed dumpcap and OS capture support.
See the detailed network workbench guide, This Device evidence and connection-quality boundary, Connected Workbench v0.7 implementation contract, suite product, redesign, and migration strategy, private-network integration plan (TailScout remains standalone), Cloudflare Tunnel workspace guide, Cloudflare Tunnel integration plan, route, path, discovery, and Nmap evidence boundary, protocol roadmap, competitive workflow decisions, transport boundaries, and go-to-market runbook.
Found an installer/runtime defect? Open a GitHub issue. Questions and workflow feedback belong in GitHub Discussions.
bun install --frozen-lockfile # install frontend deps
bun run test # tsgo typecheck + Biome lint + Vitest
bun run build # build console/site and enforce bundle budgets
go test ./... # Go test suite
make install # install protopeek and pp locally
make docker-smoke # build/probe the guarded scratch imagemake docker
docker run --rm -p 127.0.0.1:8080:8080 protopeek:devScratch-compatible image: static Go binary, embedded web app, CA certs, and a non-root user. The
image uses -allow-non-loopback-bind to listen on its container interface while still rejecting
non-loopback browser Hosts and Origins. Keep the host-side port mapped to loopback as shown; the
separate -unsafe-allow-remote mode disables that request-host guard and is only for an
authenticated, TLS-terminated, rate-limited boundary. A browser-folder snapshot is uploaded to this
container and compiled through bounded in-memory buffers; it is never written to a schema staging
directory.
ProtoPeek originated from a fork of fullstorydev/grpcui. The product, docs, branding, and release flow are now ProtoPeek's own.