Local OpenAI LLM (Custom Integration for Home Assistant)

Allows use of generic OpenAI-compatible LLM services, such as (but not limited to):

• DeepSeek
• Google (Gemini)
• llama.cpp
• LM Studio
• LocalAI
• Ollama
• OpenRouter
• Requesty
• Scaleway
• vLLM

This integration has been forked from Home Assistants OpenRouter integration, with the following changes:

• Added server URL to the initial server configuration
• Made the API Key optional during initial server configuration: can be left blank if your local server does not require one
• Uses streamed LLM responses
• Conversation Agents support TTS streaming
• Automatically strips <think> tags from responses
• Added support for image inputs for AI Task entities
• Added support for reconfiguring Conversation Agents
• Added option to trim conversation history to help stay within your context window
• Added temperature control (conversation agent + ai task)
• Added option to strip emojis from responses
• Added support for parallel tool calling
• Added experimental Retrieval Augmented Generation capability
• Added chat template arguments support
• Added image generation support for AI Task entities
• Added tools support for Generate Data actions for AI Task entities
• Emits a local_openai_llm_generation_complete event for all LLM completion requests, with usage/timings data if available

Installation

Install via HACS (recommended)

Have HACS installed, this will allow you to update easily.

Adding Tools for Assist to HACS can be using this button:

[!NOTE] If the button above doesn't work, add https://github.com/skye-harris/hass_local_openai_llm as a custom repository of type Integration in HACS.

• Click install on the Local OpenAI LLM integration.
• Restart Home Assistant.

• Copy the local_openai folder from latest release to the custom_components folder in your config directory.
• Restart the Home Assistant.

Integration Configuration

After installation, configure the integration through Home Assistant's UI:

1. Go to Settings → Devices & Services.
2. Click Add Integration.
3. Search for Local OpenAI LLM.
4. Follow the setup wizard to configure your desired services.

Configuration Notes

• The Server URL must be a fully qualified URL pointing to an OpenAI-compatible API.
  • This typically ends with /v1 but may differ depending on your server configuration.
• A Server Type configuration can be set to expose some additional options for different inference servers and providers, where they have been implemented.
• Assist requires a fairly lengthy context for tooling and entity definitions.
  • It is strongly recommended to use at least 10k context size and to limit history length and exposed entities to avoid context overflow issues.
  • This is not configurable through OpenAI-compatible APIs, and needs to be configured with the inference server directly.
• Tool calling must be enabled in your inference engine, eg:
  • vLLM: https://docs.vllm.ai/en/latest/features/tool_calling/
  • llama.cpp: https://github.com/ggml-org/llama.cpp/blob/master/docs/function-calling.md
• Parallel tool calling requires support from both your model and inference server.
  • In some cases, control of this is handled by the server directly, in which case toggling this will not have any result.
• Chat Template Arguments allow you to provide custom arguments to your model
  • Arguments are supplied as key/value pairs and provided to the chat_template_kwargs request parameter
  • Values support Jinja2 templates, in order to provide non-string and more complex data structures
  • Arguments differ per model, and not all models make use of user-provided arguments
  • See your models documentation for what arguments are available to be used
• Request Body Parameters allow you to provide additional top-level parameters to the chat completion request body
  • Parameters are supplied as key/value pairs and merged into the request body
  • Values support Jinja2 templates, in order to provide non-string and more complex data structures
  • Internally managed parameters, and parameters with dedicated configuration options, cannot be configured here
  • Provider support differs; see your provider and model documentation for available parameters
• AI Task entities can be configured for Text and/or Image generation capabilities
  • This capability uses the Images API spec and requires support from your chosen image generation server
  • Support has been developed and tested with StableDiffusion.cpp
• Always continue conversation — When a voice agent finishes speaking, passes the active voice turn back to the user in order to naturally continue the conversation
  • If the user speaks, the assistant continues the conversation naturally
  • If the user stays silent, the assistant stops following up after a timeout
  • If the user says a stop keyword (e.g. "STOP") while the agent is actively speaking, the follow-up is canceled immediately (default HomeAssistant behaviour)
  • The agent is provided a stop talking tool to end the conversation via natural language request to the agent itself (while the assist satellite is listening, not speaking)
  • When disabled (default), only assistant responses ending in a question will pass the active voice turn back to the user

All Server Types

Custom HTTP Headers

Add custom HTTP headers as key-value pairs to all LLM API requests. Useful for passing custom metadata or provider-specific headers:

• Values support Jinja2 templates and have access to all default Home Assistant template variables and functions (e.g. entity states).
• The current Conversation ID is available in the conversation_id variable.
• All header values are coerced to strings after rendering.

DeepSeek Cloud Configuration

Reasoning Effort

When the server type is set to DeepSeek Cloud, both conversation and AI task agents show a new DeepSeek Configuration section with a Reasoning Effort option. This controls the depth of reasoning when thinking is enabled.

• High (default) — standard reasoning effort.
• Max — maximum reasoning effort.

When enabled, thinking content returned by the model is also fed back into the conversation as reasoning content on supported Home Assistant versions (2026.4+).

Thinking Mode

Controls when reasoning is enabled. Leave the option unset to disable thinking.

• Always on — thinking remains enabled for every iteration.
• First loop iteration only — thinking is disabled on iterations after the first (e.g., during tool-call rounds).

llama.cpp Configuration

When the server type is set to llama.cpp, both conversation and AI task agents show a llama.cpp Configuration section with the following options.

Thinking Mode

Controls when reasoning is enabled. Leave the option unset to disable thinking.

• Always on — reasoning is enabled for every iteration of the agent loop.
• First loop iteration only — thinking is disabled on iterations after the first (e.g., during tool-call rounds).

Note: This option completely overrides any existing enable_thinking option in your Chat Template Arguments.

Include prior thinking

Controls whether thinking/reasoning content from prior conversation turns is sent back in new completion requests.

Some reasoning models require this enabled, and others require it disabled. Check the documentation for your model if unsure.

• Enabled (default) — prior-turn thinking_content is passed as reasoning_content in the next request, allowing the model to see its own prior reasoning.
• Disabled — prior thinking context is stripped before sending. Use for models that reject prior reasoning context (e.g., Gemma 4).

Slot ID

Pins requests to a specific llama.cpp server slot for prompt-cache reuse. Leave empty to allow any slot to be used.

Use loaded model

When enabled, the integration prioritizes using models already resident in memory to minimize latency.

It follows these rules:

• Primary: Uses the configured model if it is currently loaded.
• Fallback: If the configured model is not loaded, it selects the first loaded model that supports the required modality (e.g., image inputs). If no compatible loaded models exist, it defaults back to the configured model.

This is ideal for users with diverse model setups who want to route tasks to whatever is currently available in memory rather than waiting for a specific model to load.

Sampling Parameters

These options control how llama.cpp selects tokens during text generation. Please refer to the llama.cpp documentation for further information and usage.