index.md

layout	home
hero	name text tagline actions proxykit Composable Go proxy foundation Build reverse, forward, CONNECT, WebSocket, and runtime-aware proxy workflows without dragging product-specific REST contracts into your core. theme text link brand Get Started /guide/getting-started theme text link alt Open Cookbook /guide/cookbook theme text link alt Compare with Alternatives /guide/comparisons
features	title details Transport-first Separate packages for reverse HTTP, forward HTTP, CONNECT tunneling, WebSocket proxying, cookie rewriting, and runtime listener lifecycle. title details App-agnostic No UI DTOs, no monitor room protocol, no REST route assumptions, and no storage model hidden inside the public surface. title details Hook-driven Mutation and observation hooks let you add persistence, metrics, capture, replay, or app-specific policy without forking the transport engine. title details Small packages Pull in only what you need. Use reverse plus cookies, forward plus connect, or wsproxy plus observe without importing a monolith. title details Practical, not academic The packages already power a real debugger/proxy product, but the public API stays narrower than the product backend. title details Built for Go ergonomics http.Handler composition, explicit options structs, concrete types, and standard-library-first integration.

Why proxykit exists

Most Go proxy projects fall into one of two buckets:

• a powerful but monolithic programmable proxy
• a full platform or gateway product that is hard to embed into your own application

proxykit aims for a third shape:

• reusable transport engines
• explicit observation contracts
• your own app remains responsible for persistence, routes, policy, and UI-facing API design

That means the repo is intentionally smaller than a full proxy product backend. It contains the proxy foundation, not your entire application stack.

Why not goproxy, oxy, or Martian?

• choose goproxy when you want a long-standing all-in-one programmable HTTP/HTTPS proxy
• choose oxy when your center of gravity is reverse-proxy middleware composition
• choose Martian when your main need is deep modifier-driven HTTP testing and mutation

Choose proxykit when your application needs one embeddable foundation for reverse HTTP, forward HTTP, CONNECT, and WebSocket, without pushing storage, routes, admin APIs, or UI DTOs into the transport layer.

What you get

• reverse for mounted reverse proxy handlers
• forward for absolute-URI HTTP forward proxying
• connect for plain CONNECT tunneling
• wsproxy for bidirectional WebSocket proxying
• proxyruntime for forward and SOCKS listener lifecycle
• observe for transport-neutral hooks and event structs
• cookies, proxyhttp, socketio, and mitm as focused supporting packages

Capability map

Need	Package
mounted reverse proxy route	reverse
absolute-URI forward proxy	forward
plain CONNECT tunneling	connect
bidirectional WebSocket proxy	wsproxy
transport-neutral hooks	observe
listener lifecycle	proxyruntime
cookie rewriting helpers	cookies
focused transport helpers	proxyhttp, socketio, mitm

Real-world example

proxykit is not just a greenfield library extraction. It already powers a real application:

• flutter_network_debugger - a Flutter + Go network debugging app that uses proxykit as its reusable proxy foundation

That app keeps its own REST routes, storage model, realtime delivery, and UI contracts outside the public proxykit surface.

flowchart LR
    A["proxykit core"] --> B["application adapters"]
    B --> C["flutter_network_debugger"]

Loading

Start here by scenario

• Building a mounted in-app proxy route: read Getting Started and Cookbook
• Choosing the right package set: read Use Cases and Package Matrix
• Adopting proxykit in an existing codebase: read Migration
• Comparing it with older Go proxy libraries: open Comparisons

What stays outside

The following concerns are deliberately not part of proxykit:

• product-specific REST routes such as /httpproxy or /_api/v1/proxy/config
• admin auth and loopback security policy
• session query language, pagination, or UI projections
• storage, spool lifecycle, capture visibility, or replay workflows
• monitor rooms, frontend protocols, and product-specific event names

If you need those, build them in your adapter layer on top of the transport packages.