payloadbox

README

Lightweight, self-hosted HTTP Request Inspector with a built-in web interface. Capture any HTTP request, inspect headers and bodies live in your browser, and stream new captures over Server-Sent Events - all from a single static binary.

Features

• Captures arbitrary HTTP requests while reserving /, /index.html, and /assets/* for the built-in web UI
• Built-in web interface for browsing captures, inspecting headers/body/query data, and copying replayable cURL commands
• JSON API for listing, fetching, streaming, and clearing captured requests
• Server-Sent Events stream with a 30-second heartbeat for long-lived connections
• Bounded in-memory ring buffer; oldest records evicted when full
• Per-request body-size limit with graceful 413 (still recorded)
• Published as Distroless Static and Alpine Linux container images

Usage

Start the server and send it a request:

~ payloadbox
{"time":"2026-04-23T19:00:00Z","level":"INFO","msg":"starting server","address":":8080"}

~ curl -X POST http://localhost:8080/webhooks/test \
    -H 'Content-Type: application/json' -d '{"event":"ping"}'
Request logged POST /webhooks/test

~ curl -s http://localhost:8080/api/v1/history | jq -r '.[-1].request.path'
/webhooks/test

Watch captures arrive live:

~ curl -N http://localhost:8080/api/v1/events
event: record
data: {"created_at":"2026-04-23T19:00:01Z",...}

Open the built-in web interface:

~ open http://localhost:8080

The UI is embedded in the binary, so there is no separate frontend server to run.

Container Image

docker run --rm -p 8080:8080 ghcr.io/bytefork/payloadbox:latest

Configuration

Environment variables only.

Variable	Default	Description
LISTEN_ADDRESS	:8080	Host and port to bind
MAX_BODY_SIZE_BYTES	5120	Per-request body limit; over-limit returns 413 but is still recorded
MAX_RECORDS_TO_STORE	200	Ring-buffer capacity
LOG_HTTP_REQUESTS	true	Log each capture to stdout
LOG_LEVEL	info	One of debug, info, warn, error

API

Method	Path	Purpose
ANY	/*	Capture endpoint, except UI assets and built-in API routes
GET	/	Embedded web UI
GET	/api/v1/history	List records (gzip when accepted)
GET	/api/v1/history/{id}	Get one record by ID (gzip when accepted)
DELETE	/api/v1/history	Clear records
GET	/api/v1/events	SSE stream of new records
GET	/api/v1/settings	Current effective config
GET	/version	Build metadata
GET	/healthz	Liveness probe

Installation

Install script

curl -fsSL https://install.bytefork.io/payloadbox | sh

Installs the latest release to /usr/local/bin. The script detects your OS and architecture, downloads the matching release asset, and verifies SHA-256 against the release's checksums.txt.

To pin a specific version:

curl -fsSL https://install.bytefork.io/payloadbox | sh -s -- --version v0.0.1

Pass --help for other options.

Alternative methods

Download a binary directly from Releases, or install from source:

go install github.com/ByteFork/payloadbox@latest

Development

See CONTRIBUTING.md.

License

This repository is MIT licensed.