postiz-proxy

A Codex-backed OpenAI-compatible HTTP proxy for Postiz agents.

It was built so apps that require an OpenAI-compatible endpoint, like Postiz agents, can use a machine that is already authenticated with Codex CLI instead of a raw OpenAI API key.

What it supports

• GET /healthz
• GET /v1/models
• POST /v1/chat/completions
• POST /v1/responses
  • streaming Server-Sent Events
  • basic message output
  • basic function/tool-call output

What it does not support

• Image generation (/v1/images/generations returns 501)
• Embeddings, audio, files, batches, fine tuning, realtime, or full Responses API parity
• High-throughput serving. Each request launches a non-interactive codex exec run.

This is intentionally boring glue code, not a general LLM gateway.

Security model

This service can access whatever the mounted Codex CLI auth can access. Treat it as sensitive infrastructure.

Recommended defaults:

• Bind it only on a private Docker network or localhost.
• Set CODEX_PROXY_API_KEY and only share it with trusted internal services.
• Do not expose this proxy directly to the public internet.
• Keep CODEX_PROXY_MAX_CONCURRENCY=1 unless you know your Codex account and host can handle more.
• Use a read-only CODEX_HOME mount when running in Docker.

Quick start

1. Authenticate Codex on the host

codex login

Confirm this created a Codex auth file:

test -s ~/.codex/auth.json && echo ok

2. Run with Docker Compose

cp .env.example .env
# edit CODEX_PROXY_API_KEY in .env
docker compose -f docker-compose.example.yml up -d --build

3. Point your app at the proxy

For OpenAI-compatible clients:

OPENAI_BASE_URL=http://postiz-proxy:4017/v1
OPENAI_API_KEY=<same value as CODEX_PROXY_API_KEY>

4. Smoke test

curl http://127.0.0.1:4017/healthz

curl http://127.0.0.1:4017/v1/chat/completions \
  -H "authorization: Bearer $CODEX_PROXY_API_KEY" \
  -H 'content-type: application/json' \
  -d '{"model":"gpt-4.1","messages":[{"role":"user","content":"Reply with exactly: proxy-ok"}]}'

Postiz notes

Postiz has multiple OpenAI call paths. Some features use Chat Completions; newer agent chat paths use the OpenAI Responses API through Mastra / AI SDK.

This proxy implements both enough for basic Postiz text-agent flows:

• /v1/chat/completions for simple text/structured-output helpers
• /v1/responses for streamed Copilot/agent messages

Image generation still needs a real image provider.

Environment variables

Name	Default	Purpose
PORT	4017	HTTP server port
CODEX_PROXY_API_KEY	empty	Optional bearer token required by clients
CODEX_BIN	codex	Codex CLI executable
CODEX_MODEL	empty	Optional Codex model override
CODEX_PROXY_TIMEOUT_MS	180000	Per-request Codex timeout
CODEX_PROXY_MAX_BODY_BYTES	2097152	Maximum request body size
CODEX_PROXY_MAX_CONCURRENCY	1	Number of concurrent Codex runs
CODEX_PROXY_WORKDIR	/tmp/codex-work	Working directory for codex exec

Development

npm run check
node server.js

The implementation has no npm runtime dependencies. It uses Node's built-in HTTP server and child_process.spawn.

License

MIT