MiniLiteLLM

A minimal, dependency-free Go reverse proxy that exposes the Helmcode API (OpenAI-compatible) under your own domain, hiding your real Helmcode API key behind a single key you control.

Why not just use LiteLLM?

LiteLLM is a full-featured proxy with multi-user auth, a database, budgets, routing across many providers, etc. MiniLiteLLM is the opposite: one upstream (Helmcode), one inbound key, no database, no per-user management. If you just need to hide one API key behind one API key for your own apps, this is a much smaller thing to run and reason about.

How it works

Every request under /v1/* is forwarded as-is to HELMCODE_BASE_URL, with the Authorization header rewritten from your PROXY_API_KEY to your real HELMCODE_API_KEY. There is no per-endpoint logic beyond that, except:

• SSE streaming (stream:true) is flushed chunk by chunk instead of buffered.
• /v2/rerank is accepted as an alias of /v1/rerank.

Supported endpoints

Method	Path	Notes
GET	/v1/models	List available models
POST	/v1/chat/completions	Supports stream:true (SSE)
POST	/v1/completions	Legacy completions, supports stream:true
POST	/v1/embeddings
POST	/v1/rerank (/v2/rerank)	/v2/rerank is an alias
POST	/v1/audio/speech	Binary audio response
POST	/v1/audio/transcriptions	multipart/form-data
POST	/v1/responses	No incremental streaming
POST	/v1/images/generations
POST	/v1/images/edits	multipart/form-data
GET	/health	Unauthenticated healthcheck
GET	/docs	Swagger UI (unauthenticated)

Full request/response shapes match Helmcode exactly — see openapi.yaml, served interactively at /docs, and the upstream source of truth: https://nan.builders/docs/api.

Usage

curl https://your-domain.example.com/v1/chat/completions \
  -H "Authorization: Bearer $PROXY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "your-model",
    "messages": [{"role": "user", "content": "Hello!"}]
  }'

Environment variables

See .env.example:

Variable	Required	Default
PROXY_API_KEY	yes	—
HELMCODE_API_KEY	yes	—
HELMCODE_BASE_URL	no	https://api.helmcode.com/v1
PORT	no	8080
LOG_COLOR	no	auto (colour only on a terminal)
LOG_HEALTH	no	false (health probes not logged)

Deploying

Self-hosted (Docker Compose behind Nginx Proxy Manager)

See DEPLOY.md for a full walkthrough covering Portainer, Nginx Proxy Manager, the mandatory SSE buffering fix, and Cloudflare.

Railway

1. Create a new Railway project from this GitHub repo (Railway detects the Dockerfile and builds from it automatically).
2. In the project's Variables tab, set PROXY_API_KEY, HELMCODE_API_KEY, and optionally HELMCODE_BASE_URL. Do not set PORT — Railway injects it automatically and the app reads it.
3. Every push to main triggers a new deploy.
4. Under Settings → Networking, add a custom domain (e.g. llm.yourdomain.com) and copy the CNAME target Railway gives you.

Cloudflare (custom domain)

1. In Cloudflare DNS, add a CNAME record: llm → the Railway target from above, with the proxy (orange cloud) enabled.
2. In SSL/TLS → Overview, set the encryption mode to Full (Railway terminates TLS with a valid certificate, so Full — or Full (strict) — works; avoid Flexible, which would leave the Cloudflare↔Railway hop unencrypted).
3. Wait for DNS propagation, then verify: curl https://llm.yourdomain.com/health.

Local development

cp .env.example .env
export $(grep -v '^#' .env | xargs)
go run .

See CONTRIBUTING.md for the full contributor workflow, commit conventions, and pre-PR checklist.

License

MIT