Skip to main content
Use a custom LLM provider when an agent should call your own OpenAI-compatible gateway instead of Tracecat’s managed LiteLLM gateway. Custom providers are managed as custom sources in organization agent settings.

​
Routing model

Each agent uses its own model configuration to decide where its LLM requests go.
Agent model configurationRequest route
passthrough: trueDirect to that agent’s configured base_url
passthrough: false or unsetTracecat’s managed LiteLLM gateway
Root agents and subagents follow the same rule. A root agent can use a custom passthrough gateway while a subagent uses managed LiteLLM, or a subagent can use its own passthrough gateway while the root agent uses managed LiteLLM. Tracecat strips the trailing version segment from the base URL before forwarding sandbox requests because SDK clients append paths such as /v1/messages. This prevents doubled paths such as /v1/v1/messages.

​
Root agents

For a root agent, Tracecat keys direct passthrough routing by the model string the root agent sends. 
model_name: customer-alias
model_provider: custom-model-provider
base_url: https://customer-litellm.example/v1
passthrough: true
Requests with model: customer-alias go directly to https://customer-litellm.example.

​
Subagents

For a subagent, Tracecat keys direct passthrough routing by the subagent’s scoped model route. This lets Tracecat route each preset agent independently, even when several agents share the same sandbox process. 
model_name: child-alias
model_provider: custom-model-provider
base_url: https://child-litellm.example/v1
passthrough: true
Requests for that subagent go directly to https://child-litellm.example. Requests for other subagents fall back to managed LiteLLM unless those subagents also enable passthrough.

​
Credentials

Tracecat resolves passthrough credentials from the custom provider selected by the agent’s model configuration. If a root agent and subagent use different passthrough providers, each route uses its own provider credentials. Managed LiteLLM requests keep the sandbox’s managed gateway token.

​
Add a custom source

Go to Organization settings, open Agent, then go to Custom sources and click Add custom source.
Add custom source dialog
Set the source fields:
  • Name: A readable label, such as Local gateway.
  • Base URL: The OpenAI-compatible API base URL, e.g. https://gateway.example/v1.
  • Auth header: Leave blank to use Authorization.
  • Auth value: The provider credential. If Auth header is blank, Tracecat sends Authorization: Bearer <value>.
  • Passthrough mode: Enable this to route agent requests directly to this gateway instead of Tracecat’s managed LiteLLM. Required for bring-your-own gateways such as LiteLLM, vLLM, and Ollama-compatible endpoints.
Use Advanced > Additional headers only for static non-auth headers. The value must be a JSON object with string keys and string values. 
{
  "X-Custom-Header": "value"
}
Click Test connection to verify the source before saving it, then click Add source.

​
Discover and enable models

After you save the source, click Refresh. Tracecat calls the source’s /models endpoint and adds the returned models to the organization catalog.
Custom source model list
Enable the models you want available to agent presets and organization defaults. If your organization does not have agent add-ons enabled, Tracecat enables discovered custom source models automatically after refresh.

​
Use the provider

Choose the enabled custom source model anywhere Tracecat lets you select an agent model, such as the default model selector or a preset agent configuration. Refresh the source again after you add or remove models from the upstream gateway. Edit the source when you rotate credentials, change the base URL, or update static headers.