Skip to main content

Responses Proxy configuration

Use this page when you operate or deploy Responses Proxy. If you only need to send requests through the hosted service, start with Getting started.

The hosted service is:

https://agent-responses-proxy.svc.cloud.morph.so/

Client SDKs and Codex should use the Responses API base URL:

https://agent-responses-proxy.svc.cloud.morph.so/v1

Self-hosted deployments read PROXY_ environment variables for service settings and unprefixed OPENAI_* variables for runtime OpenAI resources.

Core variables​

VariableDefaultPurpose
PROXY_REDIS_URLredis://127.0.0.1:6379/0Redis state and telemetry stream.
PROXY_DATABASE_URLunsetPreferred durable SQL URL. Use Postgres or Neon in production.
SERVICE_DATABASE_URLunsetFallback SQL URL.
DATABASE_URLunsetFallback SQL URL.
PROXY_SQLITE_URLsqlite:///./data/proxy.sqlite3Local fallback when no Postgres URL is set.
PROXY_UPSTREAM_BASE_URLhttps://api.openai.com/v1Upstream OpenAI-compatible base URL.
PROXY_REQUEST_TIMEOUT_SECONDS600.0Upstream request timeout.
PROXY_MAX_CAPTURE_BYTES2000000Maximum captured request or response body bytes.
PROXY_IN_PROCESS_WORKERfalseRun worker inside the API process when true.
PROXY_ADMIN_TOKENunsetOptional bearer token for registry endpoints.
PROXY_SECRET_ENCRYPTION_KEYunsetRequired for inline provider API key registration.

Runtime resources​

Runtime resources are the upstream OpenAI keys used by the live router. Configure one or more keys:

OPENAI_API_KEY_1=sk-...
OPENAI_API_KEY_2=sk-...
OPENAI_API_KEY_3=sk-...
OPENAI_API_KEY_4=sk-...
OPENAI_RESOURCE_WEIGHTS=1,1,1,1
OPENAI_RESOURCE_POOL_ID=openai-default

For multiple pools:

OPENAI_RESOURCE_POOL_IDS=interactive,batch,batch,evals
OPENAI_RESOURCE_WEIGHTS=2,1,1,1

Weights and pool ids are matched by position against the parsed keys.

Current limit: providers registered through /admin/providers do not feed the live router yet. Use OPENAI_API_KEY_* variables for traffic routing.

Health checks​

VariableDefaultPurpose
PROXY_HEALTH_CHECK_ENABLEDtrueStart periodic resource health checks.
PROXY_HEALTH_CHECK_INTERVAL_SECONDS30.0Periodic check interval.
PROXY_HEALTH_CHECK_TIMEOUT_SECONDS10.0Per-resource timeout.
PROXY_HEALTH_CHECK_PATHmodelsRelative path under the upstream base URL.
PROXY_RESOURCE_COOLDOWN_SECONDS30Degraded resource cooldown after failures.

Telemetry worker​

VariableDefaultPurpose
PROXY_TELEMETRY_STREAMtelemetry:eventsRedis stream name.
PROXY_TELEMETRY_GROUPresponses-proxy-workersRedis consumer group.
PROXY_TELEMETRY_CONSUMERworker-1Worker consumer prefix.

Run the worker separately in development:

uv run responses-proxy-worker

Local development​

Run local development when you are changing the proxy service itself:

docker compose up -d redis
uv run uvicorn responses_proxy.app:create_app --factory --reload --host 127.0.0.1 --port 8000
uv run responses-proxy-worker

Local SQLite is created under data/ when no SQL database URL is configured.

Docker service​

Build and run the service container:

docker build -t agent-responses-proxy .
docker run --rm --env-file .env.service.local -p 8000:8000 agent-responses-proxy

The service container starts Redis, the worker, and the FastAPI app.

Morph service deployment​

Production deploys should supply:

  • MORPH_API_KEY_PROD
  • MORPH_API_KEY_STAGE for stage
  • MORPH_BUILDER_SNAPSHOT_ID or MORPH_BASE_IMAGE_ID
  • PROXY_DATABASE_URL
  • OPENAI_API_KEY_1 through OPENAI_API_KEY_4

Registry-related secrets:

  • PROXY_ADMIN_TOKEN
  • PROXY_SECRET_ENCRYPTION_KEY

Validate deploy configuration without contacting Morph:

MORPH_API_KEY=... \
MORPH_BUILDER_SNAPSHOT_ID=... \
OPENAI_API_KEY_1=... \
PROXY_DATABASE_URL=... \
uv run --extra deploy python scripts/deploy_service.py --dry-run

Persistence​

Use Postgres or Neon for production:

PROXY_DATABASE_URL=postgresql://user:password@host/database?sslmode=require

Persists in SQL:

  • telemetry events
  • sessions
  • requests
  • load-balancer decisions
  • registered providers
  • registered model or agent aliases

Resets with Redis or container lifecycle:

  • live counters
  • affinity mappings
  • health state
  • telemetry stream queue

The Docker service intentionally runs Redis without persistence because durable telemetry belongs in SQL.