Custom providers

Custom providers (BYOK — Bring Your Own Key) let you connect to an OpenAI-compatible API endpoint with your own API key. Local providers such as Ollama are also supported.

ProviderConfig

The ProviderConfig class has the following properties.

Property	Type	Description
`baseUrl`	`string`	Required. The API endpoint URL.
`type`	`string\|null`	Provider type. `openai` (default), `azure`, or `anthropic`.
`wireApi`	`string\|null`	API format (openai/azure only). `completions` (default) or `responses`.
`apiKey`	`string\|null`	API key. Not required for local providers such as Ollama.
`apiKeyCommand`	`string\|null`	Command the Copilot runtime runs before each provider request to fetch a fresh API key. If the command fails, the turn fails before the model request is sent. Not run when `bearerTokenProvider` is set.
`bearerToken`	`string\|null`	Bearer Token authentication. Takes precedence over `apiKey`.
`bearerTokenProvider`	`callable\|null`	Callback that returns a bearer token for each provider request. Not serialized.
`azure`	`array\|null`	Azure-specific options, such as `['apiVersion' => '2024-10-21']`.

Basic usage

When using a custom provider, the model parameter is required.

use Revolution\Copilot\Facades\Copilot;
use Revolution\Copilot\Types\ProviderConfig;
use Revolution\Copilot\Types\SessionConfig;

$response = Copilot::run(
    prompt: 'Hello!',
    config: new SessionConfig(
        model: 'gpt-4', // Required when using a custom provider
        provider: new ProviderConfig(
            baseUrl: 'https://my-api.example.com/v1',
            apiKey: config('services.openai.key'),
        ),
    ),
);

You can also specify it as an array.

$response = Copilot::run(
    prompt: 'Hello!',
    config: [
        'model' => 'gpt-4',
        'provider' => [
            'baseUrl' => 'https://my-api.example.com/v1',
            'apiKey' => config('services.openai.key'),
        ],
    ],
);

Ollama (local provider)

Local providers like Ollama don’t need an apiKey.

use Revolution\Copilot\Facades\Copilot;
use Revolution\Copilot\Types\ProviderConfig;
use Revolution\Copilot\Types\SessionConfig;

$response = Copilot::run(
    prompt: 'Hello!',
    config: new SessionConfig(
        model: 'deepseek-coder-v2:16b',
        provider: new ProviderConfig(
            type: 'openai',
            baseUrl: 'http://localhost:11434/v1',
        ),
    ),
);

Azure OpenAI

For Azure OpenAI, keep the following in mind.

Set type to azure (not openai).
Set baseUrl to the host only (do not include paths like /openai/v1).

use Revolution\Copilot\Facades\Copilot;
use Revolution\Copilot\Types\ProviderConfig;
use Revolution\Copilot\Types\SessionConfig;

$response = Copilot::run(
    prompt: 'Hello!',
    config: new SessionConfig(
        model: 'gpt-4',
        provider: new ProviderConfig(
            type: 'azure', // Always use 'azure' for Azure endpoints
            baseUrl: 'https://my-resource.openai.azure.com', // Host only
            apiKey: config('services.azure.openai_key'),
            azure: [
                'apiVersion' => '2024-10-21',
            ],
        ),
    ),
);

Azure Managed Identity

Use bearerTokenProvider when your provider uses short-lived tokens, such as Azure Managed Identity. The runtime calls the callback on every provider request. The callback receives an array containing providerName and sessionId, and must return the bearer token as a string. The following example calls a token service in your application.

use Revolution\Copilot\Facades\Copilot;
use Revolution\Copilot\Types\ProviderConfig;
use Revolution\Copilot\Types\SessionConfig;

$response = Copilot::run(
    prompt: 'Hello!',
    config: new SessionConfig(
        model: 'gpt-4',
        provider: new ProviderConfig(
            type: 'azure',
            baseUrl: 'https://my-resource.openai.azure.com',
            azure: ['apiVersion' => '2024-10-21'],
            bearerTokenProvider: fn (array $args): string => app(AzureManagedIdentityTokenProvider::class)->getToken(),
        ),
    ),
);

Handle token acquisition, caching, and refresh inside your callback.

API key command

If you use rotating API keys, use apiKeyCommand to run a command before each provider request and fetch the latest key. The command is run by the Copilot runtime, not by this package.

use Revolution\Copilot\Facades\Copilot;
use Revolution\Copilot\Types\ProviderConfig;
use Revolution\Copilot\Types\SessionConfig;

$response = Copilot::run(
    prompt: 'Hello!',
    config: new SessionConfig(
        model: 'gpt-4',
        provider: new ProviderConfig(
            baseUrl: 'https://my-api.example.com/v1',
            apiKeyCommand: config('services.my_api.key_command'),
        ),
    ),
);

apiKeyCommand must be null or a non-blank string. An empty or whitespace-only string throws an InvalidArgumentException before the request is sent. A non-string value in array form also throws an InvalidArgumentException. Passing a non-string value to the ProviderConfig constructor throws a TypeError from PHP’s type checking. Exception messages never include the command.
The runtime treats a command failure as a turn failure, and no request is sent to the model.
When bearerTokenProvider is set, it takes precedence and apiKeyCommand is not run.
Treat the command string as sensitive, like a credential, and don’t write it to logs or exception messages. This package doesn’t log the command or its output either.
apiKeyCommand is available only on ProviderConfig (not supported on NamedProviderConfig).

Important notes

The model parameter is required when using a custom provider. Without it, the call errors out.

Always use type: 'azure' for Azure endpoints (*.openai.azure.com).
Specify baseUrl as the host only. The SDK builds the path automatically.

The onListModels handler

When using a custom provider in BYOK mode, you can configure client->listModels() to invoke a custom handler instead of the CLI server. Configure it with the listModelsUsing() method. Since the client is prone to being initialized before listModels() is called, always set listModelsUsing() before listModels().

use Revolution\Copilot\Facades\Copilot;
use Revolution\Copilot\Types\ModelInfo;

$models = Copilot::client()->listModelsUsing(function (): array {
    // Return the models available on the custom provider
    return [
        ['id' => 'my-model-1', 'name' => 'My Model 1', 'version' => '1.0'],
        ['id' => 'my-model-2', 'name' => 'My Model 2', 'version' => '2.0'],
    ];
})->listModels();

Passing null clears the handler and restores the default CLI server behavior.

// Clear the handler and revert to default behavior (asking the CLI server)
$models = Copilot::client()->listModelsUsing(null)->listModels();

When listModelsUsing() is configured, listModels() does not need to connect to the CLI server and does not use a cache either.

For the latest updates, see the GitHub repository.

GitHub Copilot

SDK

AI SDK

VOICEVOX

Starter Kits

Feeds and RSS

Middleware

Custom providers