Junie Help

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

--model-default-locations

true

Enable or disable adding custom models from default locations (per user / per project).

--model-location <path>

—

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:

  1. Top-level properties: Serve as the default configuration (base URL, API key, API type, and extra headers) for the models in the profile.

  2. primaryModel: The model used for main reasoning and code generation tasks.

  3. 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

id

String

Yes

The model identifier as expected by the API endpoint (for example, gpt-6-luna or qwen3-coder:latest).

baseUrl

String

Yes

The full URL of the LLM API endpoint (for example, http://localhost:11434/v1/responses).

displayName

String

No

A human-friendly name shown for this profile in the model selection list. Defaults to the profile identifier (the filename).

providerName

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.

apiType

String

Yes

The API format to use when communicating with the endpoint. See Supported API types for the list of accepted values.

apiKey

String

No

The API key for authenticating with the endpoint. If omitted, requests are sent without an Authorization header. Supports environment variable references.

extraHeaders

Object

No

A key-value map of additional HTTP headers to include in every request to the endpoint. Values support environment variable references.

extraBody

Object

No

A JSON object merged into the body of every request to the endpoint. See Extra body.

temperature

Number

No

The sampling temperature to use for requests. If omitted, the provider's default temperature is used. See Temperature.

maxContextLength

Integer

No

The maximum context length supported by the model, in tokens.

efforts

Array of strings

No

Supported reasoning efforts, including custom names such as turbo or deep. The list must be non-empty and contain no blank names.

defaultEffort

String

No

Default reasoning effort. It must match an entry in the resolved efforts list for each model role.

primaryModel

Object

No

Role-specific overrides for the primary model. See Role-specific parameters.

fasterModel

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

id

String

Override for the model identifier used for this role.

baseUrl

String

Override for the API endpoint URL used for this role.

apiType

String

Override for the API format used for this role.

apiKey

String

Override for the API key used for this role.

extraHeaders

Object

Additional headers for this role. Merged with (not replaced by) the top-level extraHeaders.

extraBody

Object

Additional request body fields for this role. Merged with (not replaced by) the top-level extraBody.

temperature

Number

Override for the sampling temperature used for this role.

maxContextLength

Integer

Override for the maximum context length supported by this role, in tokens.

efforts

Array of strings

Replaces the supported reasoning efforts for this role.

defaultEffort

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-level extraBody. 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:

{ "baseUrl": "https://openrouter.ai/api/v1/chat/completions", "id": "your-model", "apiType": "OpenAICompletion", "apiKey": "${OPENROUTER_API_KEY}", "extraHeaders": { "X-Custom-Auth": "${CUSTOM_AUTH_TOKEN}" } }

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

OpenAICompletion

OpenAI Chat Completions API (/v1/chat/completions). Compatible with most self-hosted and third-party OpenAI-compatible endpoints.

OpenAIResponses

OpenAI Responses API (/v1/responses). Use this for endpoints that implement the newer Responses API format.

Google

Google Gemini API format. Use this for Google AI Studio or Vertex AI endpoints.

Anthropic

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:

{ "baseUrl": "http://localhost:4000/v1/chat/completions", "id": "my-proxy-model", "apiType": "OpenAICompletion", "extraBody": { "tags": ["user:alice", "department:engineering"] } }

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

  • efforts accepts 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 as turbo or deep. Names are trimmed. Matching ignores case. Requests preserve custom names and use lowercase standard names.

  • defaultEffort sets the default level when no effort override is active. When set, it must match an entry in that role's resolved efforts list, or the profile fails validation on load. A role that replaces efforts still inherits the top-level defaultEffort, so override both when necessary.

  • If efforts is defined and defaultEffort is omitted, Junie selects a default from the configured efforts list.

  • Profiles without efforts use the known model's effort choices when the model ID matches. Otherwise, they expose only none and omit reasoning fields. Declare efforts explicitly 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.

apiType

Request JSON field

Behavior when effort is none

OpenAICompletion

reasoning_effort

Sends "none" when declared in efforts; sampling parameters are kept.

OpenAIResponses

reasoning.effort

Sends "none" when declared in efforts; sampling parameters are kept.

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:

{ "baseUrl": "https://api.example.com/v1/chat/completions", "id": "reasoning-pro", "apiType": "OpenAICompletion", "apiKey": "${CUSTOM_API_KEY}", "efforts": ["low", "high", "turbo"], "defaultEffort": "high", "fasterModel": { "id": "fast-helper", "efforts": ["none", "low"], "defaultEffort": "none" } }

When turbo is selected for OpenAICompletion, Junie sends reasoning_effort in the chat completions body:

{ "model": "reasoning-pro", "reasoning_effort": "turbo" }

For OpenAIResponses, configure the /v1/responses endpoint with apiType set to OpenAIResponses:

{ "baseUrl": "https://api.example.com/v1/responses", "id": "gpt-custom-reasoning", "apiType": "OpenAIResponses", "apiKey": "${CUSTOM_API_KEY}", "efforts": ["low", "medium", "high", "xhigh"], "defaultEffort": "medium" }

When xhigh is selected, Junie sends the effort inside the reasoning object:

{ "model": "gpt-custom-reasoning", "reasoning": { "effort": "xhigh" } }

Example profiles

Basic profile

Below is an example of a profile named local-ollama.json:

{ "baseUrl": "http://localhost:11434/v1/chat/completions", "id": "qwen3-coder:latest", "apiType": "OpenAICompletion", "extraHeaders": { "X-Custom-Source": "Junie" }, "fasterModel": { "id": "qwen2.5-coder:1.5b" } }

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:

{ "baseUrl": "http://localhost:11434/v1/chat/completions", "id": "qwen3-coder:latest", "apiType": "OpenAICompletion", "temperature": 0.6, "primaryModel": { "id": "qwen3-coder:latest", "temperature": 0.3 }, "fasterModel": { "id": "qwen2.5-coder:1.5b" } }

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:

junie --model custom:local-ollama

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.

19 November 2026