Skip to main content

AI Providers

The ai.providers section configures connections to AI model providers. Atmos supports API providers (Anthropic, OpenAI, Gemini, GitHub Models, Grok, OpenRouter, DeepSeek, Z.AI, Ollama, Bedrock, Azure OpenAI) and CLI providers (Claude Code, OpenAI Codex, GitHub Copilot, opencode, Gemini CLI) that reuse your existing subscription.

Experimental

Configuration​

atmos.yaml
ai:
  default_provider: "anthropic"
  providers:
    anthropic:
      model: "claude-sonnet-4-6"
      api_key: !env "ANTHROPIC_API_KEY"
      max_tokens: 4096
    openai:
      model: "gpt-4o"
      api_key: !env "OPENAI_API_KEY"
      max_tokens: 4096

Provider Settings​

Each provider in the providers map supports the following settings:

model
Model identifier to use for this provider. Defaults vary by provider (see below).
api_key
API key for the provider. Use the !env YAML function to read from an environment variable (e.g., api_key: !env "ANTHROPIC_API_KEY"). Not required for Ollama (local) or Bedrock (uses AWS credentials).
max_tokens
Maximum tokens per response (default: 4096). OpenAI reasoning models (o3, o4-mini) use max_completion_tokens internally -- Atmos handles this automatically.
base_url
Custom API endpoint. Required for Grok (https://api.x.ai/v1) and Azure OpenAI (https://<resource>.openai.azure.com). For Bedrock, set to the AWS region (e.g., us-east-1). Ollama defaults to http://localhost:11434/v1.
api_version
API version string. Required for Azure OpenAI (e.g., 2025-04-01-preview).

Supported Providers​

Anthropic (Claude) — claude-sonnet-4-6
API Key authentication. Advanced reasoning, default choice.
OpenAI (GPT) — gpt-4o
API Key authentication. Widely available, strong general capabilities.
Google (Gemini) — gemini-2.5-flash
API Key authentication. Fast responses, larger context window.
GitHub Models — openai/gpt-4o-mini
GitHub token authentication. OpenAI-compatible. Zero-secret option for CI — in GitHub Actions the built-in GITHUB_TOKEN works with permissions: models: read.
xAI (Grok) — grok-4-latest
API Key authentication. OpenAI-compatible, real-time knowledge.
OpenRouter — deepseek/deepseek-chat
API Key authentication (OPENROUTER_API_KEY). OpenAI-compatible router across hundreds of models — set model to a provider-prefixed slug (e.g. anthropic/claude-sonnet-4-5, openai/gpt-4o) to switch models without changing providers.
DeepSeek — deepseek-chat
API Key authentication (DEEPSEEK_API_KEY). OpenAI-compatible. Low-cost; use deepseek-reasoner for the reasoning model.
Z.AI (GLM) — glm-5.3
API Key authentication (ZAI_API_KEY). OpenAI-compatible endpoint for Zhipu GLM models.
Ollama (Local) — llama4
No authentication (local). Privacy, offline use, zero API costs.
AWS Bedrock — anthropic.claude-sonnet-4-6
AWS Credentials authentication. Enterprise security, AWS integration.
Azure OpenAI — gpt-4o
API Key / Azure AD authentication. Enterprise compliance, Azure integration.

CLI Providers​

CLI providers invoke a locally installed AI tool as a subprocess. No API key needed — the CLI tool uses your existing subscription.

Bring your own CLI tool

Atmos assumes you already have one of these CLI tools installed and authenticated — the same assumption it makes about terraform or tofu. Atmos does not install claude, codex, copilot, opencode, or gemini, or drive their login flows, on your behalf.

Claude Code — claude-code
Claude Pro/Max subscription. Full MCP support. Best for interactive development.
OpenAI Codex — codex-cli
ChatGPT Plus/Pro subscription. Full MCP support. Open source (Apache 2.0).
GitHub Copilot — copilot-cli
GitHub Copilot subscription. Full MCP support. Authenticates via copilot /login or COPILOT_GITHUB_TOKEN / GH_TOKEN / GITHUB_TOKEN.
opencode — opencode
Open-source terminal coding agent. Full MCP support. Uses whichever model provider you have configured and authenticated in opencode (opencode auth login).
Gemini CLI — gemini-cli
Google account (free tier: 1K req/day). MCP blocked for personal accounts.

Default Provider​

default_provider is optional. When it's not set (and ai.enabled: true), Atmos looks for a CLI provider's binary on PATH, in this order, and uses the first one it finds:

  1. claude-code (claude)
  2. codex-cli (codex)
  3. copilot-cli (copilot)
  4. opencode (opencode)
  5. gemini-cli (gemini)

If none are found, Atmos falls back to anthropic, which requires an api_key. Setting default_provider explicitly always overrides auto-detection.

Setting default_provider: "auto" does the same thing as leaving it unset, but says so explicitly. Useful for a shared atmos.yaml (checked into git) where teammates use different CLI tools — auto documents that everyone's Atmos picks up whatever they have installed, rather than leaving the field blank and looking like it was never configured.

This means a minimal config works out of the box for anyone with one of these CLI tools already installed and authenticated:

atmos.yaml
ai:
  enabled: true

Auto-detection only looks for the default binary name on PATH. If you point binary at a custom, non-PATH location, also set default_provider explicitly so Atmos doesn't fall through to a different provider.

CLI Provider Settings​

In addition to model, CLI providers support:

binary
Path to the CLI binary. Optional — defaults to finding it on PATH.
max_turns
Maximum agentic turns per invocation (Claude Code only). When Claude reaches this limit before producing an answer, atmos ai ask reports an error with a hint to raise this value.
max_budget_usd
Budget cap per invocation in USD (Claude Code only).
full_auto
Enable automatic tool approval (Codex CLI, Copilot CLI, and opencode). For Codex, this passes --full-auto (or --dangerously-bypass-approvals-and-sandbox when MCP servers are configured). For Copilot, this passes --allow-all-tools (implied automatically when MCP servers are configured). For opencode, this passes --auto, which blanket-approves every permission not explicitly denied; because opencode already allows tool calls by default, this is only enabled when you set full_auto: true (never implicitly from MCP config), so your opencode permission rules are respected.
allowed_tools
List of tools Claude Code is allowed to use without asking (Claude Code only). Tools on this list never trigger an approval prompt, which makes it the way to pre-approve tools for non-interactive runs such as CI, for example ["Read", "Glob", "Grep", "Bash(atmos list stacks)"].

Claude Code Tool Approval​

Claude Code approves some native tools itself and honors allowed_tools before asking Atmos. Those requests do not reach Atmos’s permission checker, so ai.tools.blocked does not override native or provider-side preapprovals. Use Claude Code’s own permission configuration to restrict those tools. ai.tools.enabled, ai.tools.allowed, and --no-tools control Atmos’s registered tool set; they do not disable Claude’s native tools.

With the claude-code provider, atmos ai ask is interactive. When Claude needs to run a tool that is not already allowed, for example atmos list stacks through its Bash tool, Atmos shows its own approval prompt in the terminal while Claude waits. After you answer, Claude continues in the same run. No extra flags are needed and nothing has to be re-run.

The prompt shows the tool and its parameters and offers Allow once, Always allow <scope>, Deny once, and Always deny <scope>. Always-choices are cached in .atmos/ai.settings.local.json. For Bash, the decision applies to the exact command, for example Bash(atmos list stacks). Claude Code file, search, and web tools use the request's file path, notebook path, search path or pattern, or URL, for example Read(/repo/go.mod) and Glob(**/*.go). Requests without a specifier, including MCP tools, use the bare tool name and cover later calls with different arguments. File-scoped decisions cover that path even if its contents change. The option label shows the scope being remembered. Denying lets Claude continue and explain what it could not do. Pressing Ctrl-C at the prompt aborts the run.

Requests Claude delegates to Atmos are checked against the Atmos permission system, so ai.tools.mode, allowed, restricted, and blocked all apply. Set ai.tools.mode: allow or yolo for unattended runs.

atmos ai chat, atmos ai ask, and atmos ai exec enforce these permissions for delegated requests. Chat temporarily hands the terminal to the approval prompt and resumes afterward. When approval is needed and no terminal is available, the command fails with an error that suggests running in a terminal, setting ai.tools.mode: allow or yolo, or adding the tool to ai.providers.claude-code.allowed_tools.

Timeout
The ai.timeout_seconds setting (default 60) counts the time the AI spends working. Time spent waiting for you at an approval prompt does not count. Timeout or cancellation terminates the provider and its child processes.
Progress
The spinner on stderr shows the tool in progress, for example "Running atmos list stacks…", and pauses while a prompt is on screen.
Behavior change with MCP servers

Previously, when mcp.servers were configured, Atmos started Claude Code with --dangerously-skip-permissions, so every tool call was auto-approved, including Claude's built-in Bash and Edit tools. For atmos ai chat, atmos ai ask, and atmos ai exec, Atmos no longer passes that flag. MCP tool calls and built-in tool calls that Claude asks permission for now go through the Atmos permission system and prompt unless they are allowed. Existing unattended runs with no explicit permission policy can now fail when a tool needs approval. Set ai.tools.mode: allow to run without prompting while still honoring blocked tools, or pre-approve specific tools with ai.providers.claude-code.allowed_tools. Use yolo only when you intend to bypass every check. See the automation migration example.

CLI Provider Examples​

atmos.yaml
ai:
  default_provider: "claude-code"
  providers:
    claude-code:
      max_turns: 10
      # max_budget_usd: 1.00
      # allowed_tools: ["Read", "Glob", "Grep"]

    codex-cli:
      model: "gpt-5.4-mini"
      full_auto: true

    copilot-cli:
      model: "claude-sonnet-4.6"
      full_auto: true

    opencode:
      model: "anthropic/claude-sonnet-4-5"  # opencode's provider/model slug
      full_auto: true

    gemini-cli:
      model: "gemini-2.5-flash"

MCP Pass-Through​

When mcp.servers is configured, CLI providers automatically pass MCP servers to the CLI tool:

  • Claude Code: Temp .mcp.json via --mcp-config
  • Codex CLI: Written to ~/.codex/config.toml (backup/restore after exit)
  • Copilot CLI: Merged into ~/.copilot/mcp-config.json (backup/restore after exit; honors COPILOT_HOME)
  • opencode: Written to a temp config passed via OPENCODE_CONFIG (deep-merged by opencode; no user file is modified)
  • Gemini CLI: Written to .gemini/settings.json in cwd (backup/restore, MCP blocked for personal accounts)

Auth-requiring servers are wrapped with atmos auth exec -i <identity>. Toolchain PATH and ATMOS_* env vars are injected automatically.

Provider Comparison​

Setup
Cloud: Easy (API key). Ollama: Medium (install + download model). Enterprise: Complex (cloud config).
Cost
Cloud: Per-token pricing. Ollama: Free. Enterprise: Per-token + cloud costs.
Data Privacy
Cloud: Sent to provider. Ollama: 100% local. Enterprise: Stays in your cloud.
Offline
Cloud: No. Ollama: Yes. Enterprise: No.
Rate Limits
Cloud: Yes. Ollama: No. Enterprise: Yes (configurable).
Compliance
Cloud: Provider-dependent. Ollama: Your control. Enterprise: SOC2, HIPAA, ISO.
Private Network
Cloud: No. Ollama: Yes. Enterprise: Yes (VPC/VNet).

Performance and Cost​

Anthropic (Claude) — 200K token context
$3-$15 per 1M tokens (input/output).
OpenAI (GPT-4o) — 128K token context
$2.50-$10 per 1M tokens (input/output).
Google (Gemini) — up to 2M token context
$0.075-$0.30 per 1M tokens (input/output).
xAI (Grok) — 2M token context
$3-$15 per 1M tokens (input/output).
Ollama — 128K token context
$0 (hardware only).
AWS Bedrock — 200K token context
$3-$15 + AWS costs per 1M tokens.
Azure OpenAI — 128K token context
$2.50-$10 + Azure costs per 1M tokens.
Cost Optimization

For budget-conscious usage, try Gemini (cheapest cloud) or Ollama (free). For balanced cost and quality, Claude Sonnet or GPT-4o work well. Enterprise providers can leverage committed-use discounts.

Privacy and Security​

Anthropic
Data location: US (cloud). Compliance: SOC 2, GDPR.
OpenAI
Data location: US (cloud). Compliance: SOC 2, GDPR.
Gemini
Data location: US (cloud). Compliance: SOC 2, GDPR.
Grok
Data location: US (cloud). Compliance: Standard.
Ollama
Data location: Your machine. Compliance: Your control.
Bedrock
Data location: Your AWS region. Compliance: SOC 2, HIPAA, ISO.
Azure OpenAI
Data location: Your Azure region. Compliance: SOC 2, HIPAA, ISO.

For sensitive infrastructure data, consider Ollama (never leaves your machine) or enterprise providers (stays in your cloud account).

Provider Examples​

atmos.yaml
ai:
  providers:
    anthropic:
      model: "claude-sonnet-4-6"
      api_key: !env "ANTHROPIC_API_KEY"
      max_tokens: 4096

    openai:
      model: "gpt-4o"
      api_key: !env "OPENAI_API_KEY"
      max_tokens: 4096

    gemini:
      model: "gemini-2.5-flash"
      api_key: !env "GEMINI_API_KEY"
      max_tokens: 8192

    github:
      model: "openai/gpt-4o-mini"
      api_key: !env "GITHUB_TOKEN"
      max_tokens: 4096

    grok:
      model: "grok-4-latest"
      api_key: !env "XAI_API_KEY"
      base_url: "https://api.x.ai/v1"
      max_tokens: 4096

    openrouter:
      model: "deepseek/deepseek-chat"  # any provider-prefixed slug, e.g. "anthropic/claude-sonnet-4-5"
      api_key: !env "OPENROUTER_API_KEY"
      max_tokens: 4096

    deepseek:
      model: "deepseek-chat"  # or "deepseek-reasoner"
      api_key: !env "DEEPSEEK_API_KEY"
      max_tokens: 4096

    zai:
      model: "glm-5.3"
      api_key: !env "ZAI_API_KEY"
      max_tokens: 4096

GitHub Models in GitHub Actions (Zero Secrets)​

The github provider talks to GitHub Models, an OpenAI-compatible inference API at https://models.github.ai/inference. Its headline use case is CI: in GitHub Actions the workflow's built-in GITHUB_TOKEN authenticates when you grant the models: read permission — no API keys or secrets to provision. Model names use the publisher/model-name format (e.g., openai/gpt-4o-mini).

atmos.yaml
ai:
  enabled: true
  default_provider: "github"
  providers:
    github:
      model: "openai/gpt-4o-mini"
      api_key: !env "GITHUB_TOKEN"
.github/workflows/ai.yaml
permissions:
  contents: read
  models: read

jobs:
  summarize:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v5

      - uses: cloudposse/github-action-setup-atmos@v2

      - run: atmos ai ask "summarize the stacks in this repo"
        env:
          # provider config: api_key: !env GITHUB_TOKEN
          GITHUB_TOKEN: ${{ github.token }}

Locally, any GitHub token works (e.g., export GITHUB_TOKEN=$(gh auth token)). For GitHub Enterprise, override base_url to your instance's inference endpoint. Non-interactive commands like atmos ai ask require no TTY, so they run cleanly in CI logs.

Token Caching​

Token caching (prompt caching) reduces costs by reusing frequently-sent content like system prompts.

Anthropic — 90% discount
Manual markers. Configuration required (see below).
OpenAI — 50% discount
Automatic. No configuration required.
Gemini — Free (included)
Automatic. No configuration required.
Grok — 75% discount
Automatic. No configuration required.
Bedrock — Up to 90% discount
Automatic. No configuration required.
Azure OpenAI — 50-100% discount
Automatic. No configuration required.
Ollama — N/A
Local processing, caching not applicable.

Most providers implement caching automatically. Only Anthropic requires explicit configuration:

atmos.yaml
ai:
  providers:
    anthropic:
      model: "claude-sonnet-4-6"
      api_key: !env "ANTHROPIC_API_KEY"
      cache:
        enabled: true              # Enable prompt caching (default)
        cache_system_prompt: true  # Cache skill system prompt
        cache_project_instructions: true # Cache ATMOS.md content
cache.enabled
Enable or disable prompt caching (default: true). Cached tokens cost 90% less for Anthropic.
cache.cache_system_prompt
Cache the skill system prompt across messages (default: true).
cache.cache_project_instructions
Cache the ATMOS.md project instructions content (default: true).
Maximize Cache Savings

For Anthropic, keep your ATMOS.md content stable during conversations and use named sessions for extended work on the same topic. For all other providers, caching works transparently with no action required.

Multi-Provider Configuration​

Configure multiple providers and switch between them. Set default_provider for CLI commands, and press Ctrl+P during a chat session to switch mid-conversation.

Provider Isolation​

Each provider maintains its own completely isolated conversation history. When you switch providers, the new provider only sees messages from its own thread. When you switch back, it picks up right where you left off. UI notifications like "Switched to..." are never sent to any provider.

Security Best Practices​

Cloud Providers (Anthropic, OpenAI, Google, xAI)
Use environment variables for API keys (never commit to git), rotate keys regularly, and review each provider's data retention policies.
Local Provider (Ollama)
All processing is local. Keep Ollama updated and use disk encryption for sensitive data.
Enterprise Providers (Bedrock, Azure OpenAI)
Use IAM roles or managed identities instead of API keys, enable audit logging (CloudTrail or Azure Monitor), configure private endpoints, and use customer-managed encryption keys where available.

Related Documentation​