Custom Providers

Extensions can register custom model providers via pi.registerProvider(). This enables:

• Proxies - Route requests through corporate proxies or API gateways
• Custom endpoints - Use self-hosted or private model deployments
• OAuth/SSO - Add authentication flows for enterprise providers
• Custom APIs - Implement streaming for non-standard LLM APIs

Where to go next

This page gets you to a first working provider extension. Each part of the job has its own page:

• Override an existing provider — change a provider Atomic already ships.
• Register a provider — register and unregister a provider, and the API types it implements.
• Provider OAuth — login callbacks, credential storage, and dynamic catalog refresh.
• Provider streaming API — events, content blocks, tool calls, stop reasons, and usage.
• Provider API reference — provider config and model definition contracts.

If you only need to add a model for an API Atomic already speaks, use Custom models instead.

Example Extensions

See these complete provider examples:

• examples/extensions/custom-provider-anthropic/
• examples/extensions/custom-provider-gitlab-duo/

Table of Contents

• Example Extensions
• Quick Reference
• Override Existing Provider
• Register New Provider
• Unregister Provider
• OAuth Support
• Custom Streaming API
• Testing Your Implementation
• Config Reference
• Model Definition Reference

Quick Reference

import type { ExtensionAPI } from "@bastani/atomic";

export default function (pi: ExtensionAPI) {
  // Override baseUrl for existing provider
  pi.registerProvider("anthropic", {
    baseUrl: "https://proxy.example.com"
  });

  // Register new provider with models
  pi.registerProvider("my-provider", {
    name: "My Provider",
    baseUrl: "https://api.example.com",
    apiKey: "$MY_API_KEY",
    api: "openai-completions",
    models: [
      {
        id: "my-model",
        name: "My Model",
        reasoning: false,
        input: ["text", "image"],
        cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
        contextWindow: 128000,
        maxTokens: 4096
      }
    ]
  });
}

The extension factory can also be async. For dynamic model discovery, fetch and register models in the factory instead of session_start. Atomic waits for the factory before startup continues, so the provider is available during interactive startup and to atomic --list-models.

Override Existing Provider

Moved to Override an existing provider.

Register New Provider

Moved to Register a provider.

Unregister Provider

Moved to Register a provider.

API Types

Moved to Register a provider.

Auth Header

Moved to Register a provider.

OAuth Support

Moved to Provider OAuth.

Dynamic model catalog refresh

Moved to Provider OAuth.

OAuthLoginCallbacks

Moved to Provider OAuth.

OAuthCredentials

Moved to Provider OAuth.

Custom Streaming API

Moved to Provider streaming API.

Stream Pattern

Moved to Provider streaming API.

Event Types

Moved to Provider streaming API.

Stop Reasons

Moved to Provider streaming API.

Content Blocks

Moved to Provider streaming API.

Tool Calls

Moved to Provider streaming API.

Usage and Cost

Moved to Provider streaming API.

Registration

Moved to Provider streaming API.

Testing Your Implementation

Test your provider/model pairs against these behaviors. The filenames below are suggested test names, not a required test suite:

Test	Purpose
stream.test.ts	Basic streaming, text output
tokens.test.ts	Token counting and usage
abort.test.ts	AbortSignal handling
empty.test.ts	Empty/minimal responses
context-overflow.test.ts	Context window limits
image-limits.test.ts	Image input handling
unicode-surrogate.test.ts	Unicode edge cases
tool-call-without-result.test.ts	Tool call edge cases
image-tool-result.test.ts	Images in tool results
total-tokens.test.ts	Total token calculation
cross-provider-handoff.test.ts	Context handoff between providers

Run tests with your provider/model pairs to verify compatibility.

Config Reference

Moved to Provider API reference.

Model Definition Reference

Moved to Provider API reference.