Skip to main content

Getting started with Responses Proxy

Responses Proxy is a Morph Agent service that exposes OpenAI Responses-compatible routes. It lets Codex and other Responses API clients use a shared Morph-managed upstream pool while preserving session affinity, response affinity, and request telemetry.

Use it when you want a stable Responses API endpoint for agent traffic and a dashboard for routing decisions, recent requests, resource health, and token usage.

Useful links:

What this page helps you do​

This guide is written for developers who want to send a first request through the hosted proxy. It will help you:

  • call the Responses-compatible endpoint directly
  • label traffic with session metadata
  • configure Codex to use the proxy
  • inspect the request in the dashboard and admin history APIs

Before you start​

Have these ready before you begin:

  • Network access to https://agent-responses-proxy.svc.cloud.morph.so
  • A model name supported by the upstream pool, such as gpt-4.1-mini
  • Codex installed if you want to run Codex through the proxy
  • jq installed if you want to inspect JSON output in shell examples

You do not need local Redis, local OpenAI keys, or a local database to use the hosted proxy.

Quickstart​

Set the hosted base URL once:

export RESPONSES_PROXY_BASE_URL="https://agent-responses-proxy.svc.cloud.morph.so"

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 'content-type: application/json' \
  -d '{
    "model": "gpt-4.1-mini",
    "input": "Reply with exactly: proxy quickstart ok",
    "metadata": {
      "session_id": "quickstart-session-1",
      "session_name": "Responses Proxy quickstart",
      "pool_id": "openai-default"
    }
  }' | jq

Expected result: the response is returned from the selected upstream resource, and the session appears in dashboard history.

Session metadata​

Use stable session metadata when you want follow-up requests to stay on the same backend resource:

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

The proxy also accepts session and pool hints from headers:

X-Proxy-Session-ID: quickstart-session-1
X-Proxy-Session-Name: Responses Proxy quickstart
X-Proxy-Pool-ID: openai-default

Use Codex through the proxy​

Configure Codex with the hosted Responses API base URL:

codex \
  -c model_provider='"proxy"' \
  -c model='"gpt-4.1-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={"X-Proxy-Session-ID"="codex-quickstart-1","X-Proxy-Session-Name"="Codex quickstart"}'

Use separate -c values. Inline TOML provider tables are easy to quote incorrectly.

Inspect the request​

Open the dashboard:

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

Or query recent durable history:

curl "$RESPONSES_PROXY_BASE_URL/admin/sessions?limit=20"
curl "$RESPONSES_PROXY_BASE_URL/admin/requests?session_id=quickstart-session-1"
curl "$RESPONSES_PROXY_BASE_URL/admin/decisions?session_id=quickstart-session-1"

Look for:

  • the session name you provided
  • the selected resource id
  • the routing reason, such as weighted_least_connections or session_affinity
  • status code, latency, and token usage when the upstream response includes usage data

When to run locally​

Most users should use the hosted service URL. Run the proxy locally only when you are developing the proxy itself, changing service configuration, or validating deployment behavior.

See Configuration for local development, Docker, persistence, and Morph service deployment.

Next steps​

  • Read Concepts for routing and telemetry vocabulary.
  • Read Dashboard to understand what appears after requests run.
  • Read API reference for route families.
  • Read Security before exposing admin or telemetry endpoints.