droid exec --model rejects all custom model IDs (BYOK)

[mikez93]

Summary

droid exec --model <custom-model-id> rejects all custom model IDs with "Invalid model" even though they are listed as available in the error output. Only the current session default custom model works via --model. Built-in model IDs route through Factory's API (returning 402 for non-subscribers) instead of the user's BYOK proxy.

Environment

• Droid CLI version: 0.70.0, 0.74.0 (tested both)
• OS: macOS (Darwin 23.6.0, arm64)
• Custom models: Configured in ~/.factory/settings.json with BYOK proxy at localhost

Steps to Reproduce

1. Configure custom models in ~/.factory/settings.json (e.g., Gemini Flash via OpenAI-compatible proxy)
2. Run: droid exec --auto low --model "custom:Gemini-3-Flash-Low-[Proxy]-18" "Say hello"
3. Observe: "Invalid model" error, even though "Gemini 3 Flash Low [Proxy]" is listed under "Available custom models"

Tested formats that all fail:

• custom:Gemini-3-Flash-Low-[Proxy]-18 (the id field from settings.json)
• Gemini 3 Flash Low [Proxy] (the displayName from settings.json)
• custom:Claude-Haiku-4.5-Medium-Thinking-6 (non-default Claude custom model)

The only custom model that works is the one set as sessionDefaultSettings.model — which is effectively a no-op since it's already the default.

Built-in model IDs (e.g., claude-haiku-4-5-20251001) are accepted syntactically but fail with 402 Payment Required because they route through Factory's API instead of the BYOK proxy.

Expected Behavior

--model should accept any custom model ID from ~/.factory/settings.json and route through the configured BYOK endpoint, not just the current session default.

Impact

This blocks headless droid exec workflows that need to select specific models programmatically (e.g., using a cheap model for batch enrichment pipelines while keeping an expensive model as the interactive default).

Workaround

Omit the --model flag entirely and rely on the session default. This means you can't select different models for different use cases without manually changing sessionDefaultSettings.model between runs.

Log Evidence

From ~/.factory/logs/droid-log-single.log:

MetaError: Invalid model: custom:Gemini-3-Flash-Low-[Proxy]-18
    at syR (src/commands/assertValidOptions.ts:83:17)
    at async <anonymous> (src/commands/exec.ts:957:21)

The validation in assertValidOptions.ts lists custom models but fails to match against them.

[mikez93]

Still broken in v0.80.0 (March 2026)

Hi team -- this issue is still present in droid v0.80.0. Filing a follow-up because it's been open since March 13 with no response.

New bug report attached

Bug Report ID: 8a482bf4-2f07-4c78-bb67-afd18a0cb59c

This was filed via /bug and includes full session logs from a fresh reproduction.

Reproduction (unchanged from original report)

# Session default is custom:Claude-Opus-4.6-Max-Thinking-2 -- this works:
echo "Say hi" | droid exec --auto low
# Output: works fine

# Passing the SAME model via --model fails:
echo "Say hi" | droid exec --model "custom:Claude-Opus-4.6-Max-Thinking-2" --auto low
# Error: Invalid model: custom:Claude-Opus-4.6-Max-Thinking-2

Every format is rejected: displayName, exact id field from settings.json, custom: prefix variations -- all fail at the validation step in assertValidOptions.ts. The models are loaded and displayed in the error output but the matching logic doesn't work.

Why this matters

This is a blocker for any BYOK user who needs to programmatically select models in droid exec. Our enrichment pipeline needs to use different models for different tasks (cheap models for batch work, expensive ones for complex analysis), and currently the only option is manually editing sessionDefaultSettings.model between runs. That's not viable for automation.

Would really appreciate this getting some attention. Happy to provide any additional info needed.

Thanks!

[mikez93]

Configuration audit (ruling out user error)

To be clear, we've done a thorough investigation to confirm this is a bug in the droid binary, not a configuration issue. We audited our ~/.factory/settings.json against the official Factory BYOK docs (overview, OpenRouter, droid exec custom models) and everything checks out:

What the docs say	Our config	Match?
Use customModels array in ~/.factory/settings.json	Yes	OK
OpenRouter: provider: "generic-chat-completion-api"	Yes	OK
OpenRouter: baseUrl: "https://openrouter.ai/api/v1"	Yes	OK
Anthropic proxy: provider: "anthropic"	Yes	OK
OpenAI proxy: provider: "openai"	Yes	OK
Reference custom models as custom:Display-Name-Dashed-{index}	Tried this exact format	Rejected

We tested every plausible ID format across v0.70.0, v0.74.0, and v0.80.0:

• "custom:Claude-Haiku-4.5-Medium-Thinking-6" (exact id field from settings.json)
• "Claude Haiku 4.5 Medium Thinking" (exact displayName)
• "custom:Claude Haiku 4.5 Medium Thinking" (custom: prefix + displayName)
• "custom:MiMo-V2-Flash-[OpenRouter]-27" (OpenRouter BYOK model)
• Array-position index vs stored index field -- both rejected

The definitive proof that it's a binary issue: the sessionDefaultSettings.model value is custom:Claude-Opus-4.6-Max-Thinking-2. Droid uses this successfully when --model is omitted. But passing that identical string via --model fails validation. The model loading works; the matching/validation in assertValidOptions.ts:83 does not.

This has been broken across at least 3 major versions now (0.70 through 0.80). We've been working around it by omitting --model entirely, but it limits what we can do with headless automation.

[mikez93]

Workaround Found: Env Var Override (Kimi K2.5 via Code Subscription)

Sharing a working workaround specifically for the Kimi K2.5 use case, in case it helps others hitting this. It also happens to be the officially documented Kimi integration method, so there's a precedent for it.

Context

I'm using Kimi K2.5 via the Kimi Code subscription (api.kimi.com/coding/), not via a generic BYOK proxy. The Kimi endpoint requires User-Agent: claude-code/0.1.0 — which Droid's Anthropic SDK sends automatically, but only when using provider: "anthropic". This is why the env var approach ends up being the right solution for Kimi specifically: it routes through the Anthropic SDK path, which handles the header.

The Workaround

Instead of --model, inject env vars into the subprocess:

ENABLE_TOOL_SEARCH=false \
ANTHROPIC_BASE_URL="https://api.kimi.com/coding/" \
ANTHROPIC_API_KEY="$KIMI_API_KEY" \
  droid exec --auto high --output-format json --file prompt.txt

Do not pass --model — the env vars replace the model entirely.

Python Automation Pattern

For pipelines calling droid exec via subprocess, detect Kimi model names and inject:

import asyncio, os

_KIMI_MODEL_PREFIXES = ("kimi-k2", "kimi-k1")

def is_kimi_model(model: str) -> bool:
    return any(model.lower().startswith(p) for p in _KIMI_MODEL_PREFIXES)

async def execute_droid(cmd: list[str], model: str | None = None) -> tuple[bytes, bytes]:
    env = None
    if model and is_kimi_model(model):
        kimi_key = os.environ.get("KIMIK2_API_KEY")
        env = {
            **os.environ,
            "ANTHROPIC_BASE_URL": "https://api.kimi.com/coding/",
            "ANTHROPIC_API_KEY": kimi_key,
            "ENABLE_TOOL_SEARCH": "false",
        }
        # Don't add --model to cmd
    elif model:
        cmd = [*cmd, "--model", model]

    proc = await asyncio.create_subprocess_exec(
        *cmd,
        stdout=asyncio.subprocess.PIPE,
        stderr=asyncio.subprocess.PIPE,
        env=env,
    )
    return await proc.communicate()

Verified Working

Tested on droid v0.80+, macOS arm64:

• 74 items extracted from a 30-chunk meeting transcript (5 decisions, 9 action items, 12 entities, 7 metrics, 5 tactics)
• thinking_tokens present in response — confirms Kimi endpoint is being hit, not Anthropic

Limitations of This Workaround

• Only applies to Kimi/Anthropic-compatible endpoints. For generic BYOK with generic-chat-completion-api provider type (NVIDIA NIM, etc.), this approach doesn't apply — those need the --model flag to actually work.
• Replaces the model for the entire subprocess invocation, not just a single call.
• Requires knowing which models need the env var path vs the standard path.

This doesn't fix the underlying bug — the custom model ID matching in assertValidOptions.ts still needs to be fixed for the general case. But it does unblock Kimi users in the meantime.

---

Happy to share more details about the Kimi-specific setup if useful. The two-endpoint distinction (Anthropic-compatible at /coding/ vs OpenAI-compatible at /coding/v1/) is the crux of why the Anthropic SDK path is the right one for Kimi, and why this workaround produces better results than trying to force it through generic-chat-completion-api.

[mikez93]

Follow-up: still broken in v0.90.1, related findings from #691 investigation

Status

Confirmed droid exec --model still rejects all custom model IDs as of v0.90.1. The env var override workaround (posted in my previous comment) continues to work.

Connection to #691

While investigating the sub-agent BYOK bug (#691), I discovered that both issues stem from the same root cause: the custom:* ID format is not being resolved correctly in different contexts.

• droid exec --model rejects all custom model IDs (BYOK) #787: droid exec --model passes the custom ID to assertValidOptions.ts which can't match it
• Subagents (Task tool) fail 100% on all BYOK models — "No output received" / "Task failed" #691: Task tool passes the custom ID to the sub-agent spawner which can't resolve it

The resolution paths are different (CLI validator vs sub-agent spawner) but the pattern is identical: custom model IDs are visible in the "Available custom models" list but fail validation/resolution when actually used.

Workarounds by context

Context	Workaround
droid exec (this issue)	Env var override: ANTHROPIC_BASE_URL + ANTHROPIC_API_KEY, omit --model
Sub-agents / Mission Control (#691)	User-created droids with model: custom:<model-field> + SessionStart hook to auto-patch Factory-managed droids

Both workarounds avoid passing custom:* IDs through the broken resolution paths.