kulala-echo

A httpbun.com-compatible HTTP testing service built with Bun and Hono.

Kulala Echo aims for httpbun parity (excluding /run and /llm/*), plus WebSocket, gRPC, and OIDC extensions used by kulala.nvim.

Usage

bun install --frozen-lockfile
bun run dev

Open http://localhost:3002/ for Swagger UI.

Service	Default
HTTP / WebSocket	PORT (default 3002)
gRPC Echo	GRPC_PORT (default 50051)

Scripts

bun run dev         # hot-reload server
bun test            # unit + route tests
bun run typecheck   # tsc --noEmit
bun run lint        # biome lint
bun run format      # biome format --write
bun run check       # biome check
bun run build       # bundle to dist/

Extensions (beyond httpbun)

• WebSocket - ws://host/ws echoes messages; optional ?delay= seconds; idle connections close after 60s (?idle= to override, max 120)
• gRPC - Echo service (proto/echo.proto): unary + streaming RPCs on GRPC_PORT, with server reflection (grpcurl -plaintext localhost:50051 list)
• OIDC - /.well-known/openid-configuration, /oidc/jwks, id_token + refresh_token when OAuth2 scope includes openid (token refresh via grant_type=refresh_token)
• Images - /image serves the mistweaverco logo

Docker

Pull

docker run -d --restart=always \
  --name kulala-echo \
  -e PORT=3002 \
  -e GRPC_PORT=50051 \
  -p 3002:3002 \
  -p 50051:50051 \
  ghcr.io/mistweaverco/kulala-echo:latest

Build

docker buildx build --push \
  -t ghcr.io/mistweaverco/kulala-echo:latest \
  -f Dockerfile .