docker-proxq

module
v0.11.5 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 10, 2026 License: MIT

README

proxq

CI coverage version license Docker Pulls

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.

Sponsor

Buy Me a Coffee

License

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

Directories

Path Synopsis
internal
app
pkg

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL