Skip to main content

Getting started with Responses Proxy

Responses Proxy exposes an OpenAI Responses-compatible endpoint for Codex and other agent clients. Requests still use the Responses API shape, but each create request needs an org-scoped proxy key and a registered model alias such as openai/gpt-mini, kimi/k2, or anthropic/sonnet. Claude Code uses the same registry through the Anthropic Messages-compatible gateway at /v1/messages.

The proxy resolves that alias to a registered provider, injects the provider credential, translates the request when needed, and records durable telemetry for sessions, requests, routing decisions, token usage, and proxy-owned response state.

Useful links:

What this page helps you do​

This guide is written for developers who already have a registered model alias. It will help you:

  • check backend health
  • send a first Responses request
  • label traffic with session metadata
  • configure Codex to use the proxy
  • configure Claude Code to use the proxy
  • inspect telemetry through admin history APIs or the Responses console

If you do not have a model alias yet, start with Provider registration.

Before you start​

Have these ready:

  • Network access to https://agent-responses-proxy.svc.cloud.morph.so
  • A registered model alias, for example openai/gpt-mini
  • A proxy key minted for the same Morph organization as the alias
  • Codex installed if you want to run Codex through the proxy
  • Optional: a Morph org token if you need to query admin history APIs directly

The data plane does not require a provider key such as an OpenAI key. Send your Responses Proxy key as the request bearer token; the proxy injects the selected provider credential after resolving the model alias.

Quickstart​

Set the service URL and alias:

export RESPONSES_PROXY_BASE_URL="https://agent-responses-proxy.svc.cloud.morph.so"
export RESPONSES_PROXY_MODEL="openai/gpt-mini"
export RESPONSES_PROXY_API_KEY="rprx-..."

Check health:

curl -fsS "$RESPONSES_PROXY_BASE_URL/healthz"
curl -fsS "$RESPONSES_PROXY_BASE_URL/readyz"

Send a Responses API request:

curl -sS "$RESPONSES_PROXY_BASE_URL/v1/responses" \
  -H "Authorization: Bearer $RESPONSES_PROXY_API_KEY" \
  -H 'content-type: application/json' \
  -d '{
    "model": "openai/gpt-mini",
    "input": "Reply with exactly: proxy quickstart ok",
    "metadata": {
      "session_id": "quickstart-session-1",
      "session_name": "Responses Proxy quickstart"
    }
  }'

Expected result: the proxy returns canonical Responses JSON. A missing or invalid proxy key returns 401, a missing model returns 400, an unknown alias in the key's org returns 404, and an empty or unroutable registry returns 503.

Session metadata​

Use stable session metadata when requests belong to the same agent session:

{
  "metadata": {
    "session_id": "quickstart-session-1",
    "session_name": "Responses Proxy quickstart"
  }
}

The proxy also accepts session hints from headers:

X-Proxy-Session-ID: quickstart-session-1
X-Proxy-Session-Name: Responses Proxy quickstart

Alias routing pins the provider pool. Incoming pool headers cannot make credentials and model rewriting diverge from the registered alias.

Use Codex through the proxy​

Configure Codex as a Responses provider and set model to the registered alias:

codex \
  -c model_provider='"proxy"' \
  -c model='"openai/gpt-mini"' \
  -c model_providers.proxy.name='"Responses Proxy"' \
  -c model_providers.proxy.base_url='"https://agent-responses-proxy.svc.cloud.morph.so/v1"' \
  -c model_providers.proxy.wire_api='"responses"' \
  -c 'model_providers.proxy.http_headers={"Authorization"="Bearer rprx-...","X-Proxy-Session-ID"="codex-quickstart-1","X-Proxy-Session-Name"="Codex quickstart"}'

For aliases Codex does not know, add the alias to codex-model-catalog.json or pass a custom catalog with MODEL_CATALOG_JSON. Codex uses that metadata for context-window and compaction decisions.

Use Claude Code through the proxy​

Configure Claude Code with the Anthropic Messages-compatible gateway and choose a registered Claude Code-compatible alias:

export RESPONSES_PROXY_KEY="rprx-..."
export ANTHROPIC_BASE_URL="https://agent-responses-proxy.svc.cloud.morph.so/v1"
export ANTHROPIC_CUSTOM_HEADERS="X-Responses-Proxy-Key: $RESPONSES_PROXY_KEY"
export CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1

claude --model "anthropic/sonnet"

Aliases can point at anthropic_messages, responses, or deployment-enabled chat_completions providers. Alias capabilities control media and tool compatibility. For the schema, mapping limits, and Claude Code subscription setup, read Claude Code BYOS.

Inspect history​

Admin history APIs require:

export ADMIN_HEADER="Authorization: Bearer $SEELE_ORG_ADMIN_MORPH_API_KEY"

Query recent state:

curl -H "$ADMIN_HEADER" "$RESPONSES_PROXY_BASE_URL/admin/overview?limit=20"
curl -H "$ADMIN_HEADER" "$RESPONSES_PROXY_BASE_URL/admin/metrics"
curl -H "$ADMIN_HEADER" "$RESPONSES_PROXY_BASE_URL/admin/requests?session_id=quickstart-session-1"
curl -H "$ADMIN_HEADER" "$RESPONSES_PROXY_BASE_URL/admin/decisions?session_id=quickstart-session-1"

Look for:

  • provider_id
  • model_alias
  • selected resource_id
  • routing reason such as weighted_least_connections, session_affinity, or response_affinity
  • status, latency, and token usage when available

For browser workflows, use the Responses page in the Morph Cloud console. The browser talks to the proxy through a same-origin BFF that obtains a Morph service delegation token server-side.

Next steps​