Custom LLMs
Junie CLI supports custom models defined via JSON profiles. This feature allows you to integrate with local providers (e.g., Ollama), enterprise proxies, or any LLM endpoint that follows the supported API formats.
Choosing a capable model
Junie is an agentic tool: it drives a task by calling tools, following multi-step instructions, and reasoning over a large context (your prompt, file contents, tool output, and the running plan). This places much higher demands on a model than a plain chat completion.
Smaller or heavily quantized models often cannot keep up. With a weak model you may see Junie:
ignore or partially follow instructions, or drift away from the task;
emit malformed or incomplete tool calls, so edits and commands fail;
loop, repeat itself, or stop before the task is finished;
lose track of earlier steps once the context grows.
Configuration
Location and discovery
By default, custom models are discovered from JSON files located in:
User-scope:
$JUNIE_HOME/models/*.json.Project-scope:
.junie/models/*.json.
The filename (without the .json extension) is used as the profile identifier.
You can control where Junie searches for custom models using the following command-line options:
Option | Default | Description |
|---|---|---|
|
| Enable or disable adding custom models from default locations (per user / per project). |
| — | Additional folders where custom models should be found. Can be specified multiple times. |
You can also set these values in the config.json file. For details, see Junie CLI configuration files.
Profile structure
A custom model profile consists of a top-level configuration and two optional model roles:
Top-level properties: Serve as the default configuration (base URL, API key, API type, and extra headers) for the models in the profile.
primaryModel: The model used for main reasoning and code generation tasks.fasterModel: The model used for internal helper tasks like summarizing context or classifying tasks.
If primaryModel or fasterModel is not explicitly defined, they inherit the top-level properties.
Top-level parameters
These parameters appear at the root of the JSON profile and define the defaults shared by both model roles.
Parameter | Type | Required | Description |
|---|---|---|---|
| String | Yes | The model identifier as expected by the API endpoint (for example, |
| String | Yes | The full URL of the LLM API endpoint (for example, |
| String | No | A human-friendly name shown for this profile in the model selection list. Defaults to the profile identifier (the filename). |
| String | No | A provider label shown next to this profile's model name, for example in the prompt toolbar. It does not group models in the model selection list. |
| String | Yes | The API format to use when communicating with the endpoint. See Supported API types for the list of accepted values. |
| String | No | The API key for authenticating with the endpoint. If omitted, requests are sent without an |
| Object | No | A key-value map of additional HTTP headers to include in every request to the endpoint. Values support environment variable references. |
| Object | No | A JSON object merged into the body of every request to the endpoint. See Extra body. |
| Number | No | The sampling temperature to use for requests. If omitted, the provider's default temperature is used. See Temperature. |
| Integer | No | The maximum context length supported by the model, in tokens. |
| Array of strings | No | Supported reasoning efforts, including custom names such as |
| String | No | Default reasoning effort. It must match an entry in the resolved |
| Object | No | Role-specific overrides for the primary model. See Role-specific parameters. |
| Object | No | Role-specific overrides for the faster model. See Role-specific parameters. |
Role-specific parameters
primaryModel and fasterModel accept the same set of parameters. Any parameter specified here overrides the corresponding top-level value for that model role. Omitted parameters fall back to the top-level defaults.
Parameter | Type | Description |
|---|---|---|
| String | Override for the model identifier used for this role. |
| String | Override for the API endpoint URL used for this role. |
| String | Override for the API format used for this role. |
| String | Override for the API key used for this role. |
| Object | Additional headers for this role. Merged with (not replaced by) the top-level |
| Object | Additional request body fields for this role. Merged with (not replaced by) the top-level |
| Number | Override for the sampling temperature used for this role. |
| Integer | Override for the maximum context length supported by this role, in tokens. |
| Array of strings | Replaces the supported reasoning efforts for this role. |
| String | Overrides the default reasoning effort for this role. When omitted, the top-level default still applies. |
Merging logic
Overrides in primaryModel or fasterModel are merged with the top-level defaults:
Simple fields (
id,baseUrl,apiKey,apiType,temperature,maxContextLength,efforts,defaultEffort) are replaced by the override value when present. When omitted, each role inherits the top-level value.Headers (
extraHeaders) are merged: headers defined in the override are added to the top-level headers. If the same header key appears in both, the role-level value takes precedence.Body fields (
extraBody) are merged recursively: entries defined in the override are added to the top-levelextraBody. If the same key appears in both and both values are nested objects, those objects are merged recursively (rather than the override replacing the whole subtree). For any other conflicting value, the role-level value takes precedence.
When a top-level defaultEffort is set, a role-specific efforts list must contain it unless that role overrides defaultEffort. Otherwise, the profile fails validation.
Environment variables
Custom model profiles are often committed to a project repository and shared with a team (for example, to share a custom baseUrl or model routing). To avoid leaking secrets, you can reference environment variables inside the apiKey field and inside extraHeaders values instead of hardcoding them.
Use the ${VAR_NAME} syntax. Junie resolves each reference against the corresponding environment variable when it loads the profile:
A reference must match ${NAME}, where NAME starts with a letter or underscore and contains only letters, digits, and underscores. Values without any ${...} reference are used as-is, so existing literal keys keep working unchanged.
If a referenced environment variable is not set, the profile fails to load and Junie reports an error identifying the missing variable. Set the variable before starting Junie (or replace the reference with a literal value) to resolve it.
Supported API types
The apiType field controls which request format Junie uses when calling the endpoint.
Value | Description |
|---|---|
| OpenAI Chat Completions API ( |
| OpenAI Responses API ( |
| Google Gemini API format. Use this for Google AI Studio or Vertex AI endpoints. |
| Anthropic Messages API format. Use this for Anthropic Claude endpoints. |
Extra body
Some providers and proxies accept additional, non-standard fields in the request body — for example, routing metadata or tags. Use the extraBody parameter to merge a JSON object into the body of every request Junie sends to the endpoint.
You can set extraBody at the top level (shared by both model roles) or override it per role. A common use case is tagging requests for a proxy such as LiteLLM:
The extraBody entries are merged into the top level of the request JSON. If a key conflicts with a field Junie already sets (for example, model or messages), the extraBody value takes precedence, so use it with care.
Temperature
By default, Junie does not send a temperature value for custom models, allowing the provider to use its own default. You can set a specific temperature at the top level (shared by both model roles) or override it per role.
Recommended temperature values vary by model. For example:
Model | Recommended temperature |
|---|---|
DeepSeek | 0 |
Gemini | 1 |
Kimi | 0.6–1 |
GLM | 0.7 |
Qwen | 0.6 |
MiMo | 0.3 |
Reasoning effort
Use efforts and defaultEffort to configure reasoning effort support for a custom model profile. You can set them at the top level to share defaults across roles, or override them inside primaryModel and fasterModel.
Effort names and defaults
effortsaccepts any non-empty list of non-blank strings. You can use standard values (none,minimal,low,medium,high,xhigh,max) or endpoint-specific names such asturboordeep. Names are trimmed. Matching ignores case. Requests preserve custom names and use lowercase standard names.defaultEffortsets the default level when no effort override is active. When set, it must match an entry in that role's resolvedeffortslist, or the profile fails validation on load. A role that replaceseffortsstill inherits the top-leveldefaultEffort, so override both when necessary.If
effortsis defined anddefaultEffortis omitted, Junie selects a default from the configuredeffortslist.Profiles without
effortsuse the known model's effort choices when the model ID matches. Otherwise, they expose onlynoneand omit reasoning fields. Declareeffortsexplicitly to enable custom reasoning levels.
Select declared effort names with --effort, for example junie --model custom:my-profile --effort turbo. The TUI and ACP effort pickers also use the profile's declared efforts and default.
Wire format mapping
When a declared effort is selected on an OpenAI-compatible custom endpoint, Junie sends the configured effort string in the API request:
For efforts other than none, Junie omits temperature and top_p.
| Request JSON field | Behavior when effort is |
|---|---|---|
|
| Sends |
|
| Sends |
For active efforts other than none, both temperature and top_p are omitted so reasoning endpoints do not reject sampling parameters.
Examples
The profile below sets custom efforts for the primary model and disables reasoning for fasterModel:
When turbo is selected for OpenAICompletion, Junie sends reasoning_effort in the chat completions body:
For OpenAIResponses, configure the /v1/responses endpoint with apiType set to OpenAIResponses:
When xhigh is selected, Junie sends the effort inside the reasoning object:
Example profiles
Basic profile
Below is an example of a profile named local-ollama.json:
In this example, the primary model will be qwen3-coder:latest, and the faster model will be qwen2.5-coder:1.5b. Both will use the same base URL, API type, and extra headers.
Profile with temperature
Below is an example that sets a default temperature and overrides it for the primary model:
In this example, the primary model uses temperature 0.3 (overridden), while the faster model inherits the top-level temperature 0.6.
Using custom models
Once a profile is created, you can select it using the /model command or the --model flag. Custom models are identified by a custom: prefix followed by the profile ID:
In the interactive TUI, custom models appear in the Custom tab of the model selection list, after the tabs of the built-in providers.
Provider guides
For common local and proxy providers, you can connect interactively (no JSON profile required) and let Junie discover the available models. The following guides cover both the interactive setup and a manual profile:
To run a model locally without setting anything up by hand, see Junie Local — the JetBrains inference engine for macOS on Apple Silicon and Windows on NVIDIA RTX, whose installer writes the model profile for you.