Upstreams
An upstream is the model service Lumoswitch calls. The upstream page stores provider API keys, maintains base URLs and credential pools, and runs connection tests.
Built-in presets
The console provides 33 cloud, local, and custom upstream presets and shows entries available for the current deployment edition and region. See the Upstream support matrix for names, protocols, and default URLs. Presets fill the suggested base URL and model-discovery rules.
Add an upstream
- Open Upstreams and choose Add upstream key.
- Select a provider preset.
- Enter a recognizable name such as “DeepSeek production.”
- Paste the provider API key.
- Verify the base URL. Lumoswitch fetches the available models after saving.
- Save and run a connection test.
Secrets are encrypted at rest. Lists show connection metadata and health, never plaintext keys.
Base URL rules
- Keep the preset URL unless you have a specific reason to change it.
- OpenAI-compatible services commonly require a
/v1suffix. - Ollama and LM Studio can use private addresses, but the current Lumoswitch instance may block them by policy.
- Never enter the Lumoswitch downstream URL as an upstream, which can create a request loop.
Connection tests
Test one upstream
A single test verifies a specific key, URL, and basic permission.
Test all upstreams
Test all checks the primary key for every stored upstream in parallel and summarizes success and failure. Tests send a lightweight provider request and may consume a small amount of provider quota.
Credential pools
One upstream can hold several provider keys. Set credential priority, enable or disable entries, and remove expired credentials. Keep at least one enabled, working credential before changing the pool.
Full provider keys are not shown again. Use names that identify account or purpose without embedding secret material. See Credential pools for selection and rotation behavior.
Chat and Responses tests
After the connection test, run a chat test against the intended model. When a client will use the Responses API, also verify Responses compatibility. These tests exercise more of the request path than model listing and can consume provider quota.
Common failures
| Error | Check |
|---|---|
| 401 | Key integrity and whether it belongs to this base URL |
| 403 | Account, region, organization, and model permissions |
| 429 | Provider rate limit, concurrency, quota, or balance |
| Model not found | Whether the model-list endpoint is compatible and the account has model access |
| Timeout | URL, network, proxy, and provider status |
| Local model unreachable | Whether the current instance permits private upstream addresses |
Before deletion
Before deleting an upstream, remove or replace its resources in every API configuration, verify that another resource can carry traffic, and rediscover models. Deletion can immediately break clients whose configuration still depends on the upstream.