Cloud Provider Setup

Route nexus-agents through AWS Bedrock, Google Vertex AI, Azure OpenAI, or any of LiteLLM’s 2,673 supported models — without nexus-agents shipping any provider-specific adapter code.

Why no native Bedrock/Vertex/Azure adapter? Per the consensus vote on issue #2182 (6-0 unanimous reject), shipping per-cloud provider plugins is a build-vs-buy mistake — the existing OpenAI-compatible gateway pattern already covers every cloud through one of the three paths below. This guide documents what to use instead.

TL;DR — Pick a path

All three paths use existing nexus-agents code. No new adapters, no new provider plugins.

Path A — OpenRouter direct

OpenRouter is a hosted multi-provider gateway. Set one env var, and nexus-agents speaks to OpenRouter, which forwards to whichever underlying model you pick. Bedrock-Claude, Vertex-Gemini, Azure-GPT-4o — all reachable through OpenRouter’s catalog.

Setup

# 1. Get an API key at https://openrouter.ai/keys
export OPENROUTER_API_KEY="sk-or-v1-..."

# 2. Route a task. nexus-agents picks an OpenRouter model that matches the
#    routing decision (free models prioritized; paid via OpenRouter pricing).
nexus-agents orchestrate "Explain the architecture of this codebase"

Pinning a specific model

OpenRouter exposes provider-prefixed model IDs. To pin one explicitly:

# Pin to Claude on AWS Bedrock via OpenRouter
export NEXUS_OPENROUTER_MODEL="anthropic/claude-sonnet-4-6"

# Pin to Gemini on Vertex via OpenRouter
export NEXUS_OPENROUTER_MODEL="google/gemini-3-pro"

# Pin to GPT-4o on Azure via OpenRouter
export NEXUS_OPENROUTER_MODEL="openai/gpt-4o"

See OpenRouter’s model catalog for the full list.

Pros / cons

When NOT to use: regulated environments (HIPAA, FedRAMP, on-prem); workloads that must stay inside a single cloud’s IAM boundary; cost-sensitive high-volume workloads.

Path B — LiteLLM proxy + custom-openai alias

LiteLLM is a self-hosted OpenAI-compatible proxy that speaks to 100+ provider APIs natively (Bedrock IAM, Vertex service-accounts, Azure managed identity, etc.). Run it in a container, point nexus-agents at it with NEXUS_OPENAI_COMPAT_URL and NEXUS_OPENAI_COMPAT_KEY. The custom-openai auto-adapter aliases the shared gateway adapter (#7150).

Setup

# 1. Run LiteLLM proxy. Minimum config: one model.
docker run -d --name litellm \
  -p 4000:4000 \
  -e AWS_ACCESS_KEY_ID="$AWS_ACCESS_KEY_ID" \
  -e AWS_SECRET_ACCESS_KEY="$AWS_SECRET_ACCESS_KEY" \
  -e AWS_REGION_NAME="us-east-1" \
  -v "$(pwd)/litellm-config.yaml:/app/config.yaml" \
  ghcr.io/berriai/litellm:main-stable \
  --config /app/config.yaml --port 4000

litellm-config.yaml:

model_list:
  - model_name: claude-bedrock
    litellm_params:
      model: bedrock/anthropic.claude-sonnet-4-20250514-v1:0
      aws_region_name: us-east-1
  - model_name: gemini-vertex
    litellm_params:
      model: vertex_ai/gemini-1.5-pro
      vertex_project: your-gcp-project-id
      vertex_location: us-central1
  - model_name: gpt4-azure
    litellm_params:
      model: azure/gpt-4o
      api_base: https://your-resource.openai.azure.com/
      api_version: '2024-08-01-preview'
      api_key: ${AZURE_API_KEY}

# 2. Point nexus-agents at the proxy
export NEXUS_OPENAI_COMPAT_URL="http://localhost:4000/v1"
export NEXUS_OPENAI_COMPAT_KEY="anything"   # LiteLLM master key (or 'sk-1234' if no auth)
export NEXUS_CUSTOM_MODEL="claude-bedrock"   # optional catalogue pin
export NEXUS_CUSTOM_API_ALLOW_PRIVATE=1       # trusted localhost proxy

# 3. Run a task — flows through LiteLLM → Bedrock/Vertex/Azure
nexus-agents orchestrate "Explain the architecture of this codebase"

SSRF guard: nexus-agents validates the base URL before making any request. localhost, RFC 1918 private ranges, and link-local addresses are rejected by default. For local dev (LiteLLM at localhost:4000) set NEXUS_CUSTOM_API_ALLOW_PRIVATE=1. See CUSTOM_ENDPOINT_SETUP.md for the full guard rules.

Pros / cons

When NOT to use: trial / proof-of-concept work where Path A’s setup time dominates; environments without container infrastructure.

Path C — Any OpenAI-compatible gateway

If you already run an OpenAI-compatible gateway (Portkey, Helicone, Langfuse Gateway, an internal proxy, etc.), point nexus-agents at it the same way as Path B — but skip the LiteLLM container. Your gateway handles the cloud auth.

Setup

export NEXUS_OPENAI_COMPAT_URL="https://your-gateway.example.com/v1"
export NEXUS_OPENAI_COMPAT_KEY="your-gateway-key"
export NEXUS_CUSTOM_MODEL="claude-sonnet-4-5"   # whatever model id your gateway exposes

NEXUS_CUSTOM_API_BASE_URL and NEXUS_CUSTOM_API_KEY were removed in 10.0 (#7144). They are ignored and reported as unknown variables; rename them to NEXUS_OPENAI_COMPAT_URL and NEXUS_OPENAI_COMPAT_KEY. The canonical pair configures the shared gateway path (model discovery, in-process voters, the api:<endpoint> arm). The custom-openai alias uses its resolved catalogue model with an alias-specific client, retaining api:custom-openai usage attribution. Without a catalogue it sends NEXUS_CUSTOM_MODEL or gpt-5.5, marked unverified after failed discovery. See CONFIGURATION.md.

Gateway calls default to chat completions. Set NEXUS_CUSTOM_API_SURFACE=responses when your gateway serves the Responses API; this applies to the custom-openai alias, including streaming and tool calls. Discovered per-model clients keep chat completions. Corporate auth headers, proxy settings and bounded host guards are shared; see CORPORATE_GATEWAY.md.

Pros / cons

For full setup — including the SSRF guard, model-id mapping, and OpenCode transport variant — see CUSTOM_ENDPOINT_SETUP.md.

Comparison at a glance

Verifying the connection

Whichever path you pick, run:

nexus-agents doctor

The doctor command probes available adapters and reports which paths are configured. A healthy run lists OpenRouter (Path A) or Custom OpenAI (Paths B/C) under “Available adapters.”

To verify end-to-end with a real model call:

nexus-agents orchestrate "Print the string OK"

Look for the configured CLI/adapter in the trace output.

Related

• CUSTOM_ENDPOINT_SETUP.md — full custom-openai env-var reference + SSRF guard rules
• CONFIGURATION.md — all environment variables
• #2182 — the consensus vote that closed the door on per-cloud-provider plugins; this guide is the project’s stated answer to “how do I use Bedrock/Vertex/Azure?”