Models & Providers

Synth can route different jobs to different models. Start simple: configure one provider, test it, then tune per agent later.

Supported Providers

Start with one of these providers:

• OpenAI
• Claude through Anthropic
• OpenCode
• Amazon Bedrock

Best First Setup

Use Settings -> Providers and Settings -> Models in the web app:

1. Add one provider key in Providers.
2. Select the default provider and model in Models.
3. Save.
4. Use Test Provider in Providers before large ingests or team rollout.

Explore Needs No Model

Explore calls deterministic canonical Project search and exact read directly. Provider and model configuration affects ingestion, linking, and linting—not interactive retrieval.

Environment Variables

Provider key environment variables also work:

export OPENCODE_API_KEY=sk-...
export ANTHROPIC_API_KEY=sk-ant-...
export OPENAI_API_KEY=sk-...

Use Settings, config files, or CaSc for app defaults. Environment variables are best for providing secret values at startup, not for long-term model policy.

Repeatable Defaults

Use CaSc when a deployment should start with the same provider and model defaults every time:

default_provider: openai
default_model: gpt-4o-mini

providers:
  openai:
    api_key: "${OPENAI_API_KEY}"
    default_model: gpt-4o-mini
    enabled: true

LiteLLM And OpenAI-Compatible Gateways

Keep provider: openai when routing through LiteLLM Proxy or another OpenAI-compatible gateway. Configure the OpenAI provider's Base URL, use the gateway virtual key as its credential, and enter route aliases exactly as the gateway defines them.

The provider test verifies a configured alias with a minimal completion even when the virtual key cannot list models. For the complete UI and CaSC setup, container networking rules, failover behavior, cost caveats, and production checklist, see LiteLLM & OpenAI-Compatible Gateways.

Amazon Bedrock Setup

Amazon Bedrock is configured with AWS authentication instead of a normal API key. In Synth, open Global Settings -> Providers -> Amazon Bedrock and pick the auth path that matches where Synth runs.

For a pilot-ready walkthrough with one section per auth method, use Amazon Bedrock Auth.

Auth path	Use it when	What to set in Synth
AWS profile	Local development or a server with ~/.aws/config	AWS Region and AWS Profile Name
Kubernetes IRSA/default chain	Synth runs in Kubernetes, ECS, EC2, or another workload identity environment	AWS Region only; leave Authentication method and AWS Profile Name blank
Bearer token	Your platform issues a Bedrock bearer token	Create a bedrock_aws credential and store the token there
Access keys	Last-resort temporary AWS credentials	Store keys in a credential or secret system, not in CaSC

The same routes work in CaSC. Use profile_name only for local AWS profiles. For IRSA, ECS, or EC2 roles, set region_name and let the AWS default credential chain find the runtime role. For tokens or access keys, reference a saved bedrock_aws credential by credential_id; do not commit the raw secret.

The Bedrock Model Route field is passed to Bedrock exactly as modelId. You can enter a direct model ID, an inference profile ID, or an application inference profile ARN. Manual entry still works when model discovery is denied or unavailable.

AWS profile CaSC:

global_settings:
  default_provider: bedrock
  providers:
    bedrock:
      region_name: us-east-1
      profile_name: default
      default_model: amazon.nova-micro-v1:0
      enabled: true

Kubernetes IRSA/default chain CaSC:

global_settings:
  default_provider: bedrock
  providers:
    bedrock:
      region_name: us-east-1
      default_model: us.anthropic.claude-haiku-4-5-20251001-v1:0
      enabled: true

Bearer token CaSC:

global_settings:
  default_provider: bedrock
  providers:
    bedrock:
      credential_id: bedrock-bearer-token
      region_name: us-east-1
      default_model: amazon.nova-micro-v1:0
      enabled: true

For IRSA, configure the Kubernetes service account role outside Synth. For tokens or access keys, store the secret in the credential store or deployment secret system and reference it by credential_id.

For Anthropic models through Bedrock, make sure the AWS account has model access and any required Marketplace/model-agreement approval before testing. A model can appear in discovery before the account is authorized to invoke it.

Practical Defaults

Agent	Good Default
Extract	accurate model, lower temperature, structured-output friendly
Link	cheap model or same provider as extract
Lint	off by default; enable when you need audits

Explore does not use this table or call any provider.

Provider Health

Use Test Provider in Settings -> Providers before large ingests or team rollouts. A healthy provider can generate a short response through the configured model or route. Model listing is helpful but optional for gateways whose virtual keys allow invocation without discovery.

Cost Tip

Use synth_search first. It gives an agent useful Project evidence without a generated answer.