Custom Models

Add custom providers and models such as Ollama, vLLM, LM Studio, and proxies through models.json. Atomic reads one file from the active agent directory, normally ~/.atomic/agent/models.json. Set ATOMIC_CODING_AGENT_DIR/PI_CODING_AGENT_DIR to use another directory. Atomic does not read project-scoped .atomic/models.json, fall back to ~/.pi/agent/models.json, or merge .pi and .atomic model configuration files. The legacy .pi fallback applies only to configuration that explicitly uses layered paths, such as auth.json. The interactive /model selector and /scoped-models show the current authenticated snapshot immediately. They refresh network-backed catalogs in the background for up to 15 seconds. A direct /model <model_name> first checks for an exact cached match. Only a miss waits for the bounded refresh, then falls back to the cache if refresh stalls or fails. Closing either selector cancels its refresh. If refresh times out or fails, the selector reports that it is using cached models. You do not need to reset auth.json or ~/.atomic for a slow catalog. Login and logout remain effective even if an older refresh finishes later. A complete defaultProvider/defaultModel pair in settings.json is resolved after built-in, configured, and extension providers register. If the provider remains unsupported, interactive mode reports a generic saved-configuration warning and leaves model selection open instead of routing the session to a different provider. Print and JSON modes write that diagnostic to stderr and exit nonzero before prompting, keeping JSON stdout JSONL-clean. RPC rejects prompt with the same correlated diagnostic until an explicit successful set_model selects an available model or an explicit model cycle returns a different available model. A null or unchanged cycle result does not clear the condition. If the provider is supported but the model is unknown or lacks authentication, normal automatic selection of an available authenticated model continues. Valid custom- and extension-provider defaults resolve once their provider registration is available. See Settings. For editor completion and validation of providers, models, and compat fields, add "$schema": "https://raw.githubusercontent.com/bastani-inc/atomic/main/packages/coding-agent/schemas/models.schema.json" to models.json.

Where to go next

This page shows minimal and full models.json examples you can copy. Models Configuration lists every provider, model, override, and compatibility field directly from the schema. For extended examples, derived variants, and API behavior, see the Model configuration guide. For choosing which model to use rather than how to declare one, see Model selection.

Use classifier models

Classifier models answer typed questions about JSON state instead of chatting. They do not appear in /model. Enable codemode, list them with models.getAvailableOfType("classifier"), and call models.classify(model, { state, questions }). See Codemode for question and answer shapes. OpenAI’s GPT-6 Luna Decisions classifier is openai-decisions/gpt-6-luna. It uses the Decisions API, which needs an OpenAI API key. It has no /login entry of its own and reuses the first key it finds, in this order: a key saved for openai-api, a key saved for openai, then OPENAI_API_KEY. ChatGPT sign-in on openai does not work with it and is skipped, so with only a ChatGPT sign-in the classifier stays unavailable until you save an API key with /login openai-api or set OPENAI_API_KEY. openai/gpt-6-luna always means the chat model. GPT-6 Luna accepts up to 128 image blocks through images, alongside the JSON state. Other classifiers reject images unless their catalog input and API support them. Refused answers produce an error result. The endpoint rejects inputs above 922K tokens; very large inputs, currently above roughly 600K tokens, can hit its gateway time limit. These 504 responses are not retried, so reduce the input before trying again. TypeSafe Jev and Cloudflare Clef classifiers are also available through their providers. The direct TypeSafe classifiers, typesafe/jev-latest and typesafe/jev-1.14.0, accept up to 262K tokens and PNG or JPEG images through images; see TypeSafe Jev. Local llama.cpp models support native decision models and a next-token-probability fallback for chat models.

Minimal Example

For local models (Ollama, LM Studio, vLLM), only id is required per model:

{
  "providers": {
    "ollama": {
      "baseUrl": "http://localhost:11434/v1",
      "api": "openai-completions",
      "apiKey": "ollama",
      "models": [
        { "id": "llama3.1:8b" },
        { "id": "qwen2.5-coder:7b" }
      ]
    }
  }
}

The apiKey is required but Ollama ignores it, so any value works. To route a built-in provider through a proxy, set only its baseUrl. Its models and authentication stay unchanged:

{
  "providers": {
    "anthropic": { "baseUrl": "https://proxy.example.com/v1" }
  }
}

Some OpenAI-compatible servers do not understand the developer role used for reasoning-capable models. For those providers, set compat.supportsDeveloperRole to false so Atomic sends the system prompt as a system message instead. If the server also does not support reasoning_effort, set compat.supportsReasoningEffort to false too. You can set compat at the provider level to apply to all models, or at the model level to override a specific model. This commonly applies to Ollama, vLLM, SGLang, and similar OpenAI-compatible servers.

{
  "providers": {
    "ollama": {
      "baseUrl": "http://localhost:11434/v1",
      "api": "openai-completions",
      "apiKey": "ollama",
      "compat": {
        "supportsDeveloperRole": false,
        "supportsReasoningEffort": false
      },
      "models": [
        {
          "id": "gpt-oss:20b",
          "reasoning": true
        }
      ]
    }
  }
}

Full Example

Override defaults when you need specific values:

{
  "providers": {
    "ollama": {
      "baseUrl": "http://localhost:11434/v1",
      "api": "openai-completions",
      "apiKey": "ollama",
      "models": [
        {
          "id": "llama3.1:8b",
          "name": "Llama 3.1 8B (Local)",
          "reasoning": false,
          "input": ["text"],
          "contextWindow": 128000,
          "maxTokens": 32000,
          "cost": { "input": 0, "output": 0, "cacheRead": 0, "cacheWrite": 0 }
        }
      ]
    }
  }
}

Open /model after editing the active agent directory’s models.json to apply changes without restarting. Invalid edits report an error.

Google AI Studio Example

Use google-generative-ai with a baseUrl to add models from Google AI Studio, including custom Gemma 4 entries:

{
  "providers": {
    "my-google": {
      "baseUrl": "https://generativelanguage.googleapis.com/v1beta",
      "api": "google-generative-ai",
      "apiKey": "$GEMINI_API_KEY",
      "models": [
        {
          "id": "gemma-4-31b-it",
          "name": "Gemma 4 31B",
          "input": ["text", "image"],
          "contextWindow": 262144,
          "reasoning": true
        }
      ]
    }
  }
}

The baseUrl is required when adding custom models to the google-generative-ai API type.

​Custom Models

​Where to go next

​Use classifier models

​Table of Contents

​Minimal Example

​Full Example

​Google AI Studio Example

​Supported APIs

​Provider Configuration

​Value Resolution

​Custom Headers

​Model Configuration

​Sampling Parameters

​Sampling by Thinking Level

​Request-wide Cost Tiers

​Thinking Level Map

​Context Window

​Overriding Built-in Providers

​Per-model Overrides

​Derived Fast Model Variants

​Anthropic Messages Compatibility

​Forced tool use on Claude Fable 5.1

​Preserved thinking and model switches

​OpenAI Compatibility

​Constrained tool sampling

​Catalog freshness and precedence

​GPT-6-Astra Built-in Models

Custom Models

Where to go next

Use classifier models

Table of Contents

Minimal Example

Full Example

Google AI Studio Example

Supported APIs

Provider Configuration

Value Resolution

Custom Headers

Model Configuration

Sampling Parameters

Sampling by Thinking Level

Request-wide Cost Tiers

Thinking Level Map

Context Window

Overriding Built-in Providers

Per-model Overrides

Derived Fast Model Variants

Anthropic Messages Compatibility

Forced tool use on Claude Fable 5.1

Preserved thinking and model switches

OpenAI Compatibility

Constrained tool sampling

Catalog freshness and precedence

GPT-6-Astra Built-in Models