OpenRouter with DevFlow: setup, scope and limits
OpenRouter is the default provider behind DevFlow agents, and a single key reaches its whole catalog. Each workspace stores its own key, and DevFlow never substitutes one taken from the server. Setup is 5 steps in Workspace Settings → Billing → Model access.
- Kind
- Model provider
- Where to set it up
- Workspace Settings → Billing → Model access
- Plan
- All plans
- Agent roles
- Any OpenCode role set to an openrouter/ model
- Verified
- 1 Oct 2026
Setup steps
- Create an API key. Sign in to your OpenRouter account and create a key for DevFlow.
- Open the Billing tab. As an owner, open the Billing tab and find "Model access". If DevFlow's key is in use, click "Manage keys" under "Your own keys" to show the provider cards.
- Save the key. The OpenRouter card is always listed under "Providers". Paste the key and click "Save"; it is stored under the name
OPENROUTER_API_KEY. - Test the key. Click "Test" to have DevFlow call
/api/v1/auth/keywith it. A key typed into the field but not yet saved is tested in place of the stored one, so a replacement can be checked first. - Choose the models. In Workspace Settings → Execution, set "OpenCode Model", one of the three tiers or a single role to an ID that starts with
openrouter/.
What it does
A workspace that has not chosen a model runs on openrouter/minimax/minimax-m3, so the default setup needs either a stored key or DevFlow's managed key. IDs keep the vendor path after the openrouter/ provider prefix.
Planning and verification always ask for the highest reasoning effort. Other roles get it when the chosen model supports it: DeepSeek and qwen3.7-max models by name, and any model whose catalog entry lists a reasoning parameter. A model that cannot honor the reasoning option ignores it or returns an error, which DevFlow accepts rather than running planning and verification without it.
When a provider answers 429, 529 or 503, the same run is sent again with exponential backoff between 2 and 60 seconds, honoring Retry-After, for at most 4 attempts in all. Every other error fails the run without a retry.
Once saved, the key's card shows the credits left on the account. The DevFlow server fetches that figure, so the key itself never travels to the browser. No other provider card offers such a credits lookup, though every card displays a masked copy of its stored key.
A single run may last up to 90 minutes and is stopped after 45 minutes without output, whichever provider serves it. Long silent stretches are normal for large edits on high-reasoning models, which is why the idle limit is generous. Only the operator can change either limit, through AGENT_TIMEOUT_MINUTES and AGENT_IDLE_TIMEOUT_MINUTES.
On the Pro plan and above, a workspace can switch on DevFlow's key instead: a provisioned sub-key under DevFlow's own account, with its own spending ceiling, for teams that hold no account of their own.
Before the first task, "Check readiness" in the Repositories tab confirms that the default model and every per-role override have a credential, so a missing key shows up there instead of failing mid-task.
A workspace on the managed key that sets no spend cap of its own still gets a default monthly ceiling chosen by the operator, and the provisioned sub-key carries a hard ceiling that no workspace setting can raise.
IDs that start with ollama/ are rejected by the settings validators, so a locally served model cannot stand in for a hosted one.
Requirements
- The owner role: the Billing tab and every key route are limited to workspace owners, and members cannot even list which keys are stored.
- The OpenCode backend, DevFlow's default; the optional Claude Code backend does not read stored keys.
- An OpenRouter account with enough credit for the models the workspace selects.
Limits
- No server fallback: a key placed in the server environment under that same name is never passed to runs, so an operator cannot create a silent shared default by accident. Access comes only from the key stored for that workspace or from a managed sub-key injected per run.
- The optional context-compression proxy has no OpenRouter route, so these runs always bypass it.
- Over its monthly spend cap, a workspace's new tasks fail with a stated reason before any run starts, and the model relay answers further calls with HTTP 402.
FAQ
What happens to DevFlow's managed key when a workspace stores its own OpenRouter key?
The stored OpenRouter key wins: DevFlow runs use it, DevFlow's provisioned sub-key stays idle, and nothing is metered to DevFlow while the workspace key is present.
Can a DevFlow agent read the stored OpenRouter key?
Not when DevFlow's model relay is on, which container mode enforces. Each run then holds a short-lived token, and the relay attaches the real key to the request on its way out.
Can DevFlow compare a task's cost on another OpenRouter model?
Yes. DevFlow can re-price the tokens a task recorded at the rates of another model in the OpenRouter catalog, which the DevFlow server keeps cached for 6 hours.
Sources
Every fact above comes from these files in the DevFlow repository.
internal/relay/providers.gointernal/agent/opencode_backend.gointernal/agent/backend.gointernal/agent/transient_error.gointernal/openrouter/client.gointernal/api/opencode_key_tester.gointernal/api/handlers_opencode_keys.gointernal/api/server.gointernal/api/handlers_readiness.goweb/src/lib/components/ApiKeysManager.svelteweb/src/lib/components/billing/ModelAccess.svelteweb/src/lib/components/WorkspaceSettings.svelteENTITLEMENTS.mdCLAUDE.mdinternal/api/handlers_workspace.go