​

Provider Recipes

​

Start Here

​

Hosted Provider Quick Map

​

Pick The Right Recipe

​

Shared Readback Loop

loong doctor
loong list-models
loong ask --message "Say hello and summarize the active provider setup."

​

Reading Rule

• Use this page to get from provider lane to concrete config quickly.
• Start with Recipe 1 unless you already know you are in a coding-lane, gateway, local, or multi-profile case.
• Use Configuration Patterns when you want the shared active_provider plus providers.<id> shape before the provider-specific walkthroughs.
• Jump to Common Setups when provider choice only makes sense together with the delivery surface.
• Come back to Providers And Models when you need the broader chooser or model-selection contract.

​

Need A Full Rollout Instead?

​

Recipe 1: One Hosted Provider Profile

​

Platform-First Hosted: Volcengine Or BytePlus

active_provider = "volcengine"

[providers.volcengine]
kind = "volcengine"
api_key = { env = "ARK_API_KEY" }
model = "auto"

active_provider = "byteplus"

[providers.byteplus]
kind = "byteplus"
api_key = { env = "BYTEPLUS_API_KEY" }
model = "auto"

• api_key = { env = "ARK_API_KEY" } or api_key = { env = "BYTEPLUS_API_KEY" } means the runtime should read the secret from that env var.
• api_key = "ARK_API_KEY" would mean the literal string ARK_API_KEY is the configured key.

• one hosted provider should own first value cleanly
• you want the runtime to keep model choice visible instead of burying it in a proxy story
• you do not need multiple saved profiles yet

1. Run loong doctor to verify credentials and route health.
2. Run loong list-models once credentials are healthy.
3. Keep model = "auto" during first setup, then pin an explicit model if you want deterministic behavior.

• volcengine and byteplus are the general hosted lanes, not the coding-plan lanes.
• Volcengine defaults to ARK_API_KEY.
• BytePlus defaults to BYTEPLUS_API_KEY and also accepts ARK_API_KEY as an alias.

​

Other Direct Hosted Families

active_provider = "openai"

[providers.openai]
kind = "openai"
api_key = { env = "OPENAI_API_KEY" }
model = "auto"

​

Recipe 2: Dedicated Coding Lane

active_provider = "coding"

[providers.coding]
kind = "volcengine_coding"
api_key = { env = "ARK_API_KEY" }
model = "your-reviewed-coding-model"

active_provider = "coding"

[providers.coding]
kind = "byteplus_coding"
api_key = { env = "BYTEPLUS_API_KEY" }
model = "your-reviewed-coding-model"

• coding quota or billing should stay separate from the normal hosted lane
• your org expects the dedicated /api/coding/v3 route
• you do not want a general hosted profile accidentally drifting into the wrong pricing path

• volcengine and byteplus belong to the general /api/v3 lane.
• volcengine_coding and byteplus_coding belong to /api/coding/v3.
• Do not point a general kind at the coding route, or a coding kind at the general route. Keep the provider kind and route family aligned so runtime validation and quota expectations match.
• Other coding-specialized families such as kimi_coding, step_plan, and bailian_coding follow the same rule: keep a separate profile id, use the matching built-in kind, and pin a reviewed coding model instead of letting the general hosted lane absorb the traffic by accident.

​

Recipe 3: OpenAI-Compatible Gateway Or Managed Proxy

active_provider = "gateway"

[providers.gateway]
kind = "custom"
base_url = "https://codex.example.com/v1"
wire_api = "responses"
models_endpoint = "https://codex.example.com/v1/models"
api_key = { env = "GATEWAY_API_KEY" }
model = "your-reviewed-model-id"

• the team runs a compatibility proxy in front of upstream providers
• you are connecting to a managed gateway instead of a first-party provider
• the provider route is stable, but the model catalog may live on a different endpoint

• If the endpoint already maps to a built-in family such as openrouter, cloudflare_ai_gateway, or vercel_ai_gateway, prefer that built-in kind over custom.
• Keep wire_api = "chat_completions" unless the endpoint really expects the Responses API.
• If you set endpoint or models_endpoint explicitly, later base_url edits will not rewrite those routes for you.
• If chat works but catalog probing fails, pin model explicitly and treat the catalog as optional recovery material rather than a hard requirement.

​

Recipe 4: Local Or Self-Hosted Provider

active_provider = "local"

[providers.local]
kind = "ollama"
base_url = "http://127.0.0.1:11434"
model = "auto"

active_provider = "gpu-lab"

[providers.gpu-lab]
kind = "vllm"
base_url = "http://gpu-box.internal:8000"
model = "your-reviewed-model-id"

• you want local control over model hosting
• one machine or one lab box owns the model runtime
• you are willing to pin model names when catalog discovery is thin or absent

• Start with model = "auto" only if the server exposes enough catalog information to make that useful.
• If the server effectively has one production model, pin model explicitly and skip discovery drama.
• Prefer a stable profile id such as local, gpu-lab, or lmstudio-dev instead of rewriting one profile back and forth.

​

Recipe 5: Keep Multiple Saved Provider Profiles

active_provider = "ark_main"

[providers.ark_main]
kind = "volcengine"
api_key = { env = "ARK_API_KEY" }
model = "auto"

[providers.ark_coding]
kind = "volcengine_coding"
api_key = { env = "ARK_API_KEY" }
model = "your-reviewed-coding-model"

[providers.review_fallback]
kind = "deepseek"
api_key = { env = "DEEPSEEK_API_KEY" }
model = "deepseek-chat"

• general chat, coding work, and fallback review should stay explicit
• some work should stay on one quota or region while other work should not
• the team wants explicit provider choices instead of one profile being overwritten repeatedly

1. Keep profile ids semantic, such as ark_main, ark_coding, review_fallback, or ops_gateway.
2. Change active_provider deliberately when you want to switch lanes.
3. Re-run loong doctor after switching, because the active route and health checks should follow the active profile, not the last one you happened to edit.

​

Recipe 6: Keep Auto Discovery, But Add Explicit Recovery

active_provider = "deepseek"

[providers.deepseek]
kind = "deepseek"
api_key = { env = "DEEPSEEK_API_KEY" }
model = "auto"
preferred_models = ["deepseek-chat", "deepseek-reasoner"]

active_provider = "minimax-global"

[providers.minimax-global]
kind = "minimax"
base_url = "https://api.minimax.io"
api_key = { env = "MINIMAX_API_KEY" }
model = "auto"
preferred_models = ["MiniMax-M2.7", "MiniMax-M2.5"]

• preferred_models is an operator-owned fallback order, not a hidden provider default.
• reviewed onboarding defaults currently exist for DeepSeek (deepseek-chat) and MiniMax (MiniMax-M2.7)
• region-sensitive providers may need an explicit base_url that matches the account region

• MiniMax defaults to the CN endpoint https://api.minimaxi.com
• the global MiniMax endpoint is https://api.minimax.io
• if you later set provider.endpoint or provider.models_endpoint, changing only provider.base_url will no longer move those explicit overrides

​

Troubleshooting Patterns

​

Continue Reading