proxq

The honey badger of HTTP proxies. Takes your request, throws it in a Redis-backed job queue, and deals with it when it damn well pleases. You get a job ID back instantly, so come back later to pick up the goods.
Think of it as "I'll get back to you" as a service. Every HTTP request becomes an async job. No more hanging connections, no more timeouts, no more "please hold." Fire and forget, poll when ready.
Oh, and it caches too. Because hitting the same endpoint twice is for people who enjoy watching paint dry.
Contents
How it works
Client proxq Redis Upstream
| | | |
|-- POST /foo --> | | |
|<- 202 {jobId} - | | |
| |-- enqueue ----> | |
| (go touch | | |
| grass) | | <- worker --- |
| | | wakes up |
| | | -----------> (request)
| | | <----------- (response)
| | | |
|-- GET /{jobId}->| | |
|<- {status} ---- | | |
| | | |
|-- GET /content->| | |
|<- {response} -- | | |
| | | |
|-- PUT /big ---> | --------- direct proxy ------> |
|<- {response} -- | <----------------------------- |
proxq takes any request (any method, any path, any body), picks the upstream by longest path prefix, stores the whole thing in Redis through asynq and hands you a job ID. A worker fires it at the upstream with your original headers plus X-Forwarded-*, stores the response, and you come back whenever you want to read the status and replay the response, status code, headers and body included.
Large uploads, chunked transfers, WebSocket connections and paths you pick with a filter skip the queue and are proxied straight to the upstream. No buffering, no double transfer, no memory bomb.
Quick start
services:
proxq:
image: psyb0t/proxq
ports:
- "127.0.0.1:8080:8080"
environment:
PROXQ_CONFIG: /etc/proxq/config.yaml
configs:
- source: proxq_config
target: /etc/proxq/config.yaml
depends_on:
- redis
redis:
image: redis:7-alpine
restart: unless-stopped
configs:
proxq_config:
content: |
listenAddress: "0.0.0.0:8080"
redis:
addr: "redis:6379"
upstreams:
- prefix: "/"
url: "http://your-api:3000"
docker compose up -d
JOB_ID=$(curl -s -X POST localhost:8080/reports -d '{}' | jq -r .jobId)
curl -s "localhost:8080/__jobs/$JOB_ID" # queued, running, completed or failed
curl -si "localhost:8080/__jobs/$JOB_ID/content" # the upstream response, replayed
That's it. Your API is now async. You're welcome.
proxq has no built-in authentication, so keep it on loopback or a private network, or put an authenticating reverse proxy in front. The security page has the details.
Documentation
The full documentation is at psyb0t.github.io/docker-proxq.
| Page |
What it covers |
| Configuration |
Every config field with its default, retries, validation, logging |
| Jobs API |
Submit, status, content, cancel, and the X-Proxq-Source header |
| Routing and bypass |
Prefix matching and stripping, direct proxy rules, redirect mode |
| Caching |
Memory and Redis caches, the cache key |
| OpenAI Go client |
The openai-go wrapper |
| Use cases |
Example configs for common setups |
| Agent integrations |
The skill for Claude Code, Codex and OpenClaw |
| Security |
What proxq exposes and what to put in front of it |
| Troubleshooting |
Startup errors and runtime problems |
| Architecture |
Components, request path, job lifecycle |
| Development |
Building, testing and CI |
config.yaml.example lists every config field.
OpenAI Go client
Drop-in replacement for the openai-go constructor. Swap one line and your SDK calls go through proxq:
import proxqopenai "github.com/psyb0t/docker-proxq/pkg/clients/openai"
client := proxqopenai.NewClient(proxqopenai.Config{
ProxqBaseURL: "https://proxq.example.com",
APIKey: "sk-...",
})
Same code, same types, same return values. The client docs cover the proxq config it needs and how streaming behaves.
Agent integrations
The skill lets an AI agent submit requests to a running proxq and collect the results. Claude Code:
claude plugin marketplace add psyb0t/agents
claude plugin install proxq@psyb0t
Codex and OpenClaw are covered in agent integrations. To change this repository, read AGENTS.md.
Development
Docker, Make and Bash are all you need. Go runs in a container.
make lint # go fix -diff and golangci-lint with all the annoying linters enabled
make test # unit + integration tests (race detector on, Redis via testcontainers)
make test-coverage # tests with the 90% coverage threshold
make build # docker build
Details in the development docs.

License
MIT. Do whatever you want. If it breaks, you get to keep both pieces.