BYOK

BYOK

Bring your own key: Refact is local-first and uses provider credentials and runtimes that you configure on your own machine.

Refact is designed around BYOK rather than bundled cloud accounts. The engine reads provider YAML from ~/.config/refact/providers.d/*.yaml, and the GUI’s Provider Setup page is the normal way to create and edit those configs. The local engine then loads those YAML files, resolves the configured models, and exposes them to chat, agent, completion, reasoning, and embedding workflows. See Providers, Supported Models, and Installation.

What BYOK means in Refact

• You choose the provider, endpoint, and credentials.
• Refact does not ship a single mandatory cloud backend.
• Provider credentials and model selection live in your local config directories.
• The engine can talk to hosted APIs, OAuth-backed providers, or local model runtimes.

The repo’s documentation and default provider configs show these provider families: OpenAI, OpenAI Responses, OpenAI Codex, Anthropic, Claude Code, OpenRouter, Groq, DeepSeek, Google Gemini, LM Studio, Ollama, vLLM, xAI, Qwen, Kimi, Zhipu, MiniMax, Doubao, GitHub Copilot, and custom OpenAI-compatible endpoints.

Configuring a provider in the GUI

The Providers screen is the GUI entry point for setup and updates. In the code, the Providers page loads configured providers, lets the UI update a provider, and tracks per-provider update state while requests are in flight.

Typical flow:

1. Open the Providers page in the GUI.
2. Add or edit a provider.
3. Set the provider base, endpoint(s), API key or OAuth-backed login, and model selections.
4. Save the provider config.
5. The engine reads the YAML under ~/.config/refact/providers.d/*.yaml and refreshes available models.

The GUI names shown to users come from the provider registry mapping in gui/src/features/Providers/constants.ts and the provider card/update flow in Providers.tsx, ProviderUpdateContext.tsx, and useUpdateProvider.ts.

Where configs live

Refact’s engine docs list these local paths:

• ~/.config/refact/ — user configuration, provider YAML files, privacy settings, and customization
• ~/.config/refact/providers.d/*.yaml — BYOK/local provider configs loaded by the provider registry
• ~/.cache/refact/ — logs, caches, shadow repositories, and integration state
• .refact/ in a workspace — project trajectories, knowledge, tasks, integrations, and overrides

The default provider templates are stored in refact-agent/engine/src/yaml_configs/default_providers/ and are used as starting points for local configs.

Provider types you can configure

Hosted providers with API keys

Many providers are configured with a standard API key plus an HTTP endpoint. Examples from the default configs include:

• OpenAI and OpenAI Responses
• Anthropic
• DeepSeek
• Groq
• Google Gemini
• xAI
• OpenRouter
• Kimi
• Qwen
• MiniMax
• Doubao
• GitHub Copilot

Some of these use OpenAI-compatible chat or responses endpoints; others use provider-specific wire formats such as anthropic_messages or openai_responses.

OAuth-capable providers

Refact also supports OAuth-backed provider experiences for:

• Codex
• Claude Code

The engine includes OAuth refresh handling for those instances, and the provider codebase contains dedicated modules for Codex and Claude Code OAuth flows.

Custom OpenAI-compatible endpoints

For self-hosted or vendor-neutral setups, you can point Refact at an OpenAI-compatible API. The default configs include a custom provider and local-runtime templates that use OpenAI-style chat/completions or embeddings endpoints.

This is the path to use for custom gateways, reverse proxies, and compatibility layers that speak the OpenAI request format.

Local runtimes

Refact ships templates for local runtimes including:

• Ollama
• LM Studio
• vLLM

Those templates show localhost endpoints and placeholder API keys, which matches the local-first / BYOK model. In the default configs, Ollama also includes an explicit completion model template for FIM-style code completion.

Choosing default models

The provider config supports separate defaults for different roles. In the caps model config, the relevant fields are:

• completion_default_model for code completion / FIM
• chat_default_model for ordinary chat
• chat_model_2 for an alternate chat model slot
• task_planner_agent_model for planner/agent workflows
• reasoning_default_model for reasoning-oriented use
• embedding_model for embeddings

These defaults are stored per provider and can be overridden in YAML. The engine qualifies defaults against the provider name when needed, so a provider can define a local default model selection without inventing a global model ID.

Practical setup notes

• Hosted providers usually need a valid API key.
• Local runtimes often use placeholder keys like any-will-work because authentication is not enforced locally.
• For some providers, the model list is dynamic and comes from the provider API rather than a static hard-coded list.
• Embedding support is separate from chat/completion support and depends on the provider’s embedding endpoint configuration.

Related pages

• Providers
• Supported Models
• Caps and Models
• Installation