Managed Responses Proxy setup

The organization-private morphcloud proxy plugin configures the shared Responses Proxy without copying proxy keys or OAuth bundles into shell configuration. It reconciles organization-scoped providers, pools, aliases, and a member proxy key, then launches Codex or Claude with the minimum credentials required by that child process.

The plugin is distributed through Morph's organization-private package and plugin records. Use your organization's normal private-plugin installation flow. There is no public package installer.

Before you start

You need:

• a Morph profile authenticated as a verified member of the target organization
• the private proxy plugin enabled for that organization
• Codex and/or Claude Code already signed in on the workstation
• a supported operating-system keyring for normal workstation setup

Use --organization to assert the organization selected by the authenticated profile. The command fails instead of silently configuring a different organization.

Preview the setup

Inspect the reconciliation request without changing server or local credential state:

morphcloud proxy --profile example \
  --organization organization_example \
  setup all --dry-run --json

The preview reports the managed aliases, subscription credential imports, activation pools, and any API-key prompts that would be used.

Configure and activate routing

Run one command to reconcile both agent surfaces, import eligible local OAuth credentials, issue or reuse the member proxy key, and atomically promote the selected pools to tiered routing:

morphcloud proxy --profile example \
  --organization organization_example \
  setup all --activate

The default managed aliases are:

Surface	Alias	Wire API
Codex	managed-codex	OpenAI Responses
Claude Code	managed-claude	Anthropic Messages

--activate requires the server response to confirm that every selected pool is enabled, has at least one member, and is running in tiered mode. Activation is rejected as a unit when those invariants do not hold.

Without --activate, setup reconciles the managed structure and credentials but does not promote the pools to authoritative tiered routing.

Add paid fallback capacity

Add --api-keys when you want the setup command to securely prompt for missing OpenAI or Anthropic API keys and add paid spillover capacity:

morphcloud proxy --profile example \
  --organization organization_example \
  setup all --activate --api-keys

--api-keys requires --activate. The plugin prompts only for provider keys that are still missing. Secret values are sent through the authenticated HTTPS admin API and encrypted before SQL storage; they are not placed in command-line arguments.

Omit --api-keys for subscription-only routing. Setup can still activate successfully, but it returns an api_key_spillover_not_configured:<pool> warning for each tiered pool without paid fallback capacity.

OAuth import behavior

Setup imports an OAuth bundle only when the corresponding subscription provider does not already have an enabled, runtime-eligible OAuth credential.

• Codex setup reads the protected local OpenAI OAuth file.
• Claude setup reads ~/.claude/.credentials.json when present on macOS; otherwise it reads the Claude Code-credentials Keychain item directly into memory.
• OAuth documents are validated but never printed by the plugin.
• Stored OAuth material is encrypted server-side.

If an OAuth credential expires or requires reauthentication, use the credential refresh workflow rather than replacing unrelated routing state. Run morphcloud proxy credentials refresh <credential-id> to begin the managed refresh flow.

Launch Codex and Claude

After setup, launch the tools through the plugin:

morphcloud proxy codex -- --help
morphcloud proxy claude -- --help

The launchers select managed-codex and managed-claude unless you pass an explicit model override before the child command's -- separator.

Codex receives the member proxy key only as OPENAI_API_KEY in the child process. Claude receives the key only through the proxy header returned by /admin/managed-proxy/endpoint, which defaults to X-Responses-Proxy-Key. The Claude launcher removes ANTHROPIC_AUTH_TOKEN, ANTHROPIC_API_KEY, and CLAUDE_CODE_OAUTH_TOKEN from the child environment so the member proxy key is not mistaken for a provider credential.

Verify the result

Read managed state and run non-billable diagnostics:

morphcloud proxy --profile example \
  --organization organization_example status --json

morphcloud proxy --profile example \
  --organization organization_example doctor --json

status reports the organization, actor, managed aliases, pool modes, member counts, and credential readiness. doctor verifies local identity and keyring state, service health, managed endpoint discovery, routing state, and credential availability. It exits nonzero when local or remote checks fail.

If the local member key is missing while the server-side managed structure already exists, rerun setup with --rotate-key to issue and store a replacement:

morphcloud proxy --profile example \
  --organization organization_example \
  setup all --rotate-key

Endpoint overrides and managed devboxes

--base-url or MORPH_PROXY_BASE_URL overrides the managed service endpoint. Non-loopback overrides must use HTTPS.

Normal workstations use the operating-system keyring. Managed launcher devboxes can receive a temporary MORPH_PROXY_API_KEY through their prewarm boundary with MORPH_MANAGED_DEVBOX=1; credential-refresh devboxes do not receive the member key and instead use a one-time setup-token capability.

Do not copy workstation OAuth files, provider API keys, or member proxy keys into devbox images, repository files, or shell history.