Skip to content

Choose your model provider

IronClaw runs your agent behind a sealed sandbox and talks to whatever model you point it at. You pick the backend per agent group — the rest of the system does not change. This page helps you choose one, then links you straight to setup.

The one invariant, whatever you choose

Every provider credential is held host-side and injected by the host model-proxy on the way out. No key ever enters a sandbox. The agent sees a model reply, never the secret that paid for it. That is true for a static API key, an OAuth bearer, or AWS SigV4 credentials alike — the difference between providers is where the credential comes from, not whether it stays host-side. See Security and isolation.

Pick in 15 seconds

  • Local / offline / zero credential

    No cloud, no key, nothing leaves the box.

    → mock for a demo or CI, ollama for a real model on your own hardware with zero setup, local for any other OpenAI-compatible server (LM Studio / vLLM).

  • Hosted, fastest to first token

    You have an API key and want the strongest model now.

    → anthropic (default), openai, openrouter, or gemini.

  • Enterprise / governed cloud

    Billing, IAM, and data boundary must live in your cloud account.

    → azure (Azure OpenAI), bedrock (AWS), or vertex (Google Cloud).

  • Reuse an existing subscription

    You already pay for ChatGPT or a gateway-fronted credential.

    → codex (ChatGPT/Codex OAuth) via a local credential gateway.

Set up in three steps

Pick a backend below. You get the exact host-side config, the agent create command, and a one-line isolation check, each ready to copy. Every provider follows the same shape: set one credential, point a group at it, verify the seal.

Local / offline

Hosted (API key)

Enterprise cloud (your billing / IAM)

Reuse a subscription

Mock (offline, zero credential)

Deterministic canned replies. No key, no network — the fastest way to see the full sandbox path.

Set the credential (host-side)
# no credential — the mock provider is fully offline

Export in the control-plane's environment and restart it. This value stays host-side and never enters the sandbox.

Create the agent
./bin/ironctl agent create --name "Mock Bot" --provider mock --model mock-1 --yes
Verify the isolation
./bin/ironctl doctor

Read-only preflight: confirms the gVisor sandbox and network=none egress before the first run. Then message the group in the console for a live reply.

Local model (Ollama, LM Studio, vLLM)

Run a real model on your own hardware. Nothing leaves the box; most local servers need no key.

Set the credential (host-side)
export IRONCLAW_LOCAL_MODEL_URL=http://localhost:11434/v1   # Ollama's OpenAI-compatible endpoint

Export in the control-plane's environment and restart it. This value stays host-side and never enters the sandbox.

Create the agent
./bin/ironctl agent create --name "Local Bot" --provider local --model llama3.2 --yes
Verify the isolation
./bin/ironctl doctor

Read-only preflight: confirms the gVisor sandbox and network=none egress before the first run. Then message the group in the console for a live reply.

Anthropic (default)

The strongest default backend, with first-class tool use. One key and a restart.

Set the credential (host-side)
export ANTHROPIC_API_KEY=sk-ant-...

Export in the control-plane's environment and restart it. This value stays host-side and never enters the sandbox.

Create the agent
./bin/ironctl agent create --name "Research Bot" --provider anthropic --model claude-sonnet-4-5 --yes
Verify the isolation
./bin/ironctl doctor

Read-only preflight: confirms the gVisor sandbox and network=none egress before the first run. Then message the group in the console for a live reply.

OpenAI

GPT-class models over the OpenAI API.

Set the credential (host-side)
export OPENAI_API_KEY=sk-...

Export in the control-plane's environment and restart it. This value stays host-side and never enters the sandbox.

Create the agent
./bin/ironctl agent create --name "GPT Bot" --provider openai --model gpt-4o --yes
Verify the isolation
./bin/ironctl doctor

Read-only preflight: confirms the gVisor sandbox and network=none egress before the first run. Then message the group in the console for a live reply.

OpenRouter

One key, many models — route to any model OpenRouter fronts.

Set the credential (host-side)
export OPENROUTER_API_KEY=sk-or-...

Export in the control-plane's environment and restart it. This value stays host-side and never enters the sandbox.

Create the agent
./bin/ironctl agent create --name "Router Bot" --provider openrouter --model anthropic/claude-3.5-sonnet --yes
Verify the isolation
./bin/ironctl doctor

Read-only preflight: confirms the gVisor sandbox and network=none egress before the first run. Then message the group in the console for a live reply.

Google Gemini (AI Studio)

Hosted Google models with a generous free tier.

Set the credential (host-side)
export GOOGLE_API_KEY=...   # GEMINI_API_KEY is honored as a fallback

Export in the control-plane's environment and restart it. This value stays host-side and never enters the sandbox.

Create the agent
./bin/ironctl agent create --name "Gemini Bot" --provider gemini --model gemini-1.5-pro --yes
Verify the isolation
./bin/ironctl doctor

Read-only preflight: confirms the gVisor sandbox and network=none egress before the first run. Then message the group in the console for a live reply.

Azure OpenAI

GPT-class models under your Azure billing and identity. Model = your deployment name.

Set the credential (host-side)
export AZURE_OPENAI_ENDPOINT=https://my-resource.openai.azure.com
export AZURE_OPENAI_API_KEY=...   # or AZURE_OPENAI_ACCESS_TOKEN for Entra

Export in the control-plane's environment and restart it. This value stays host-side and never enters the sandbox.

Create the agent
./bin/ironctl agent create --name "Azure Bot" --provider azure --model gpt-4o --yes
Verify the isolation
./bin/ironctl doctor

Read-only preflight: confirms the gVisor sandbox and network=none egress before the first run. Then message the group in the console for a live reply.

AWS Bedrock

Claude and others under your AWS billing and IAM, via host-side SigV4.

Set the credential (host-side)
export AWS_ACCESS_KEY_ID=AKIA...
export AWS_SECRET_ACCESS_KEY=...
export AWS_REGION=us-east-1   # selects the bedrock-runtime.{region} host

Export in the control-plane's environment and restart it. This value stays host-side and never enters the sandbox.

Create the agent
./bin/ironctl agent create --name "Bedrock Bot" --provider bedrock --model anthropic.claude-3-5-sonnet-20240620-v1:0 --yes
Verify the isolation
./bin/ironctl doctor

Read-only preflight: confirms the gVisor sandbox and network=none egress before the first run. Then message the group in the console for a live reply.

Google Vertex AI

Gemini under your GCP project, billing, and IAM. A project is required; region defaults when unset.

Set the credential (host-side)
export GOOGLE_VERTEX_PROJECT=my-gcp-project   # or GOOGLE_CLOUD_PROJECT
export GOOGLE_VERTEX_USE_GCLOUD=1   # use gcloud Application Default Credentials

Export in the control-plane's environment and restart it. This value stays host-side and never enters the sandbox.

Create the agent
./bin/ironctl agent create --name "Vertex Bot" --provider vertex --model gemini-1.5-pro --yes
Verify the isolation
./bin/ironctl doctor

Read-only preflight: confirms the gVisor sandbox and network=none egress before the first run. Then message the group in the console for a live reply.

ChatGPT / Codex (via credential gateway)

Reuse a ChatGPT/Codex OAuth subscription fronted by a local gateway (e.g. OneCLI). The control-plane holds no model credential at all.

Set the credential (host-side)
export IRONCLAW_MODEL_GATEWAY_URL=http://127.0.0.1:10255
export IRONCLAW_MODEL_GATEWAY_HOSTS=chatgpt.com

Export in the control-plane's environment and restart it. This value stays host-side and never enters the sandbox.

Create the agent
./bin/ironctl agent create --name "Codex Bot" --provider codex --model gpt-4o --yes
Verify the isolation
./bin/ironctl doctor

Read-only preflight: confirms the gVisor sandbox and network=none egress before the first run. Then message the group in the console for a live reply.

Prefer the console?

You can also set a group's provider in the web console (Agents → edit a group → Provider), then approve the change through the human gateway so it lands on the audit log. The commands above are the CLI equivalent.

Capability matrix

Provider Kind Auth method Credential source (host-side) Streaming Best for Setup
Mock mock none none — offline, deterministic n/a Demos, e2e tests, first run Quickstart
Ollama ollama none (optional key) none — OLLAMA_API_KEY only for an auth-gateway'd Ollama yes (SSE) Zero-credential local model, easiest quickstart Ollama provider
Local / self-hosted local none (optional key) IRONCLAW_LOCAL_MODEL_KEY only if your server requires one server-dependent Any OpenAI-compatible server (LM Studio, vLLM, llama.cpp) Ollama tutorial
Anthropic (default) anthropic API key ANTHROPIC_API_KEY yes (SSE) Strongest default, tool use Quickstart
OpenAI openai API key OPENAI_API_KEY yes (SSE) GPT-class models Setup
OpenRouter openrouter API key OPENROUTER_API_KEY yes (SSE) One key, many models Setup
Google Gemini gemini API key GOOGLE_API_KEY (or GEMINI_API_KEY) yes (SSE) Hosted Google models, generous free tier Setup
Google Vertex AI vertex OAuth2 bearer gcloud ADC (GOOGLE_VERTEX_USE_GCLOUD=1) or GOOGLE_VERTEX_ACCESS_TOKEN; GOOGLE_VERTEX_PROJECT required yes (SSE) Gemini under GCP billing / IAM Setup
AWS Bedrock bedrock AWS SigV4 AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY (+ AWS_SESSION_TOKEN), AWS_REGION no (InvokeModel) Claude/others under AWS billing / IAM Setup
ChatGPT / Codex codex OAuth via gateway credential gateway (IRONCLAW_MODEL_GATEWAY_URL, e.g. OneCLI) yes (SSE) Reuse a ChatGPT/Codex subscription Setup
Azure OpenAI azure api-key or Entra token AZURE_OPENAI_API_KEY (or AZURE_OPENAI_ACCESS_TOKEN) + AZURE_OPENAI_ENDPOINT yes (SSE) GPT-class models under Azure billing / IAM Azure OpenAI

Streaming, and what it means here

Where a provider streams, IronClaw consumes the upstream token stream and accumulates the full reply before it returns — streaming is a transport detail on the host side, not a partial-render feature in the console. Bedrock uses the non-stream InvokeModel call today. Either way you get one complete, audited reply.

Decision guide

  • Just want to see it work? Start with mock — no key, no network. The Quickstart zero-credential demo replies in seconds.
  • Privacy or air-gap is the constraint? Run a model on your own box — nothing leaves the machine and no cloud credential is required. Use ollama for the zero-config path (--provider ollama works with nothing else set; see the Ollama provider), or local for any other OpenAI-compatible server (LM Studio, vLLM, llama.cpp; see the local model tutorial).
  • You have an API key and want the best answer now? Use anthropic (the default), openai, openrouter, or gemini. One environment variable and a restart.
  • Procurement, billing, and IAM must stay in your cloud? Use azure (Azure OpenAI), bedrock (AWS), or vertex (Google Cloud). Credentials come from your existing cloud identity — an Azure api-key or Entra token, AWS SigV4, or gcloud ADC — and stay host-side.
  • Already paying for ChatGPT? Front a codex OAuth credential with a local credential gateway and reuse it.

Setup by provider

Set one credential in the control-plane's environment and restart it. Every value below lives host-side only.

Anthropic, OpenAI, OpenRouter

export ANTHROPIC_API_KEY=sk-ant-…       # default provider
# or
export OPENAI_API_KEY=sk-…
# or
export OPENROUTER_API_KEY=sk-or-…

Gemini (Google AI Studio)

export GOOGLE_API_KEY=…                  # GEMINI_API_KEY is honored as a fallback

Vertex AI (Google Cloud)

Vertex speaks the same wire format as Gemini but authenticates with a short-lived OAuth bearer that IronClaw refreshes host-side. A project is required; the region defaults when unset.

export GOOGLE_VERTEX_PROJECT=my-gcp-project   # or GOOGLE_CLOUD_PROJECT
export GOOGLE_VERTEX_LOCATION=us-central1     # optional; provider default otherwise
export GOOGLE_VERTEX_USE_GCLOUD=1             # use gcloud Application Default Credentials
# or supply a token you refresh out of band:
# export GOOGLE_VERTEX_ACCESS_TOKEN=ya29.…

AWS Bedrock

For orgs that consume models only through Bedrock. Credentials come from the standard AWS environment; the region selects the regional bedrock-runtime.{region}.amazonaws.com host.

export AWS_ACCESS_KEY_ID=AKIA…
export AWS_SECRET_ACCESS_KEY=…
export AWS_SESSION_TOKEN=…                # optional, for temporary credentials
export AWS_REGION=us-east-1               # or AWS_DEFAULT_REGION

How Bedrock auth works

Host-side SigV4 signing is validated against AWS's reference vectors; requests use the non-stream InvokeModel API. The signature is region-bound, so AWS_REGION is required and no static credential ever enters the sandbox.

Codex (ChatGPT) via a credential gateway

The Codex path routes model egress through a local, operator-vetted credential gateway (such as OneCLI) that injects a ChatGPT/Codex OAuth token. The control-plane and sandbox then hold no model credential at all.

export IRONCLAW_MODEL_GATEWAY_URL=http://127.0.0.1:10255
export IRONCLAW_MODEL_GATEWAY_HOSTS=chatgpt.com

Azure OpenAI

For orgs that consume models only through Azure. Azure routes by deployment name in the URL and authenticates with an api-key header or a Microsoft Entra bearer token. See the full Azure OpenAI guide.

export AZURE_OPENAI_ENDPOINT=https://my-resource.openai.azure.com
export AZURE_OPENAI_API_KEY=…                 # or AZURE_OPENAI_ACCESS_TOKEN for Entra
export AZURE_OPENAI_API_VERSION=2024-10-21    # optional; provider default otherwise

Point an agent group at a provider

A provider credential being present does not force any group to use it — you opt a group in explicitly. Two surfaces:

  • Web console → Agents → edit a group → Provider field (leave blank for the default Anthropic backend; set openai, gemini, vertex, bedrock, local, etc. to route that group elsewhere). The group's provider and model show on its card and in the first-run Setup checklist.
  • CLI — submit a model/persona change with ironctl and approve it through the human gateway, so the switch lands on the audit log like any other change. See the Quickstart.

Leaving the field blank keeps the sealed, single-provider default posture: only groups that opt in reach another backend.

Task-focused guides

Prefer to start from what you want to run? These pages lead with the job and give you the exact setup:

See also