Skip to content

Agent Zero AI framework

Add oMLX local provider support

Alessandro045009811761
diff --git a/conf/model_providers.yaml b/conf/model_providers.yaml
index 95ca2bf8e..0743a6512 100644
--- a/conf/model_providers.yaml
+++ b/conf/model_providers.yaml
@@ -112,6 +112,15 @@ chat:
default_base: "http://host.docker.internal:11434"
kwargs:
api_base: "http://host.docker.internal:11434"
+ omlx:
+ name: oMLX
+ litellm_provider: hosted_vllm
+ models_list:
+ endpoint_url: "/v1/models"
+ default_base: "http://host.docker.internal:8000"
+ kwargs:
+ api_base: "http://host.docker.internal:8000/v1"
+ api_key: "omlx"
ollama_cloud:
name: Ollama Cloud
litellm_provider: openai
@@ -202,6 +211,12 @@ embedding:
litellm_provider: ollama
kwargs:
api_base: "http://host.docker.internal:11434"
+ omlx:
+ name: oMLX
+ litellm_provider: hosted_vllm
+ kwargs:
+ api_base: "http://host.docker.internal:8000/v1"
+ api_key: "omlx"
openai:
name: OpenAI
litellm_provider: openai
diff --git a/docs/setup/installation.md b/docs/setup/installation.md
index b6688d22f..57c0b76b9 100644
--- a/docs/setup/installation.md
+++ b/docs/setup/installation.md
@@ -438,6 +438,7 @@ Use the naming format required by your selected provider:
| OpenAI | Model name only | `claude-sonnet-4-5` |
| OpenRouter | Provider prefix mostly required | `anthropic/claude-sonnet-4-5` |
| Ollama | Model name only | `gpt-oss:20b` |
+| oMLX | API-visible model name from `/v1/models` | `Qwen3-0.6B-4bit` |
> [!TIP]
> If you see "Invalid model ID," verify the provider and naming format on the provider website, or search the web for "<name-of-ai-model> model naming".
@@ -461,6 +462,48 @@ Use the naming format required by your selected provider:
---
+## Installing and Using oMLX (Apple Silicon Local Models)
+
+oMLX is a local inference server for Apple Silicon Macs. It serves MLX models through an OpenAI-compatible API and supports chat, embeddings, and model listing endpoints.
+
+> [!NOTE]
+> oMLX requires Apple Silicon and macOS 15+. On 16 GB machines, start with small quantized MLX models.
+
+### macOS oMLX Installation
+
+**Using Homebrew:**
+
+```bash
+brew tap jundot/omlx https://github.com/jundot/omlx
+brew install omlx
+omlx start
+```
+
+**Using the macOS App:**
+
+Download the oMLX app from the [official website](https://omlx.ai/) and follow the welcome flow to choose a model directory, start the server, and download or discover models.
+
+By default, oMLX serves its OpenAI-compatible API at `http://localhost:8000/v1`.
+
+To run a foreground server with oMLX's paged SSD cache enabled:
+
+```bash
+omlx serve --model-dir ~/.omlx/models --paged-ssd-cache-dir ~/.omlx/cache
+```
+
+### Configuring oMLX in Agent Zero
+
+1. Start oMLX and make sure at least one model is available in the oMLX dashboard or model directory.
+2. In Agent Zero Settings, choose **oMLX** as the Chat model, Utility model, or Embedding model provider.
+3. Use the model name shown by oMLX's model list or dashboard.
+4. Agent Zero includes Docker-friendly defaults for oMLX on the host at `http://host.docker.internal:8000/v1`. Override the API base URL only if your oMLX server runs somewhere else.
+5. Click `Save` to confirm your settings.
+
+> [!NOTE]
+> If Agent Zero runs in Docker and oMLX runs on the Mac host, ensure port **8000** is reachable from the container. The shipped Docker Compose file maps `host.docker.internal` to the host gateway for Linux Docker. Docker Desktop for macOS provides this hostname automatically.
+
+---
+
## Installing and Using Ollama (Local Models)
Ollama is a powerful tool that allows you to run various large language models locally.
diff --git a/plugins/_browser/helpers/connector_runtime.py b/plugins/_browser/helpers/connector_runtime.py
index 82107aa7b..28c54b5fe 100644
--- a/plugins/_browser/helpers/connector_runtime.py
+++ b/plugins/_browser/helpers/connector_runtime.py
@@ -58,7 +58,7 @@ HOST_BROWSER_PROFILE_MODE_KEY = getattr(
"host_browser_profile_mode",
)
get_browser_config = browser_config.get_browser_config
-_LOCAL_PROVIDERS = {"ollama", "lm_studio"}
+_LOCAL_PROVIDERS = {"ollama", "lm_studio", "omlx"}
_LOCAL_HOSTS = {"localhost", "127.0.0.1", "::1", "host.docker.internal"}
_SENSITIVE_ACTIONS = {"content", "detail", "evaluate", "screenshot", "screenshot_file"}
_KEY_ALIASES = {
diff --git a/plugins/_model_config/api/model_search.py b/plugins/_model_config/api/model_search.py
index 83a7deeda..ec5f50d24 100644
--- a/plugins/_model_config/api/model_search.py
+++ b/plugins/_model_config/api/model_search.py
@@ -179,7 +179,7 @@ class ModelSearch(ApiHandler):
elif provider == "azure":
if has_key:
headers["api-key"] = api_key
- elif provider not in ("ollama", "lm_studio"):
+ elif provider not in ("ollama", "lm_studio", "omlx"):
if has_key:
headers["Authorization"] = f"Bearer {api_key}"
diff --git a/plugins/_model_config/extensions/python/banners/_20_missing_api_key.py b/plugins/_model_config/extensions/python/banners/_20_missing_api_key.py
index 0028a93fc..a3fc48301 100644
--- a/plugins/_model_config/extensions/python/banners/_20_missing_api_key.py
+++ b/plugins/_model_config/extensions/python/banners/_20_missing_api_key.py
@@ -6,7 +6,7 @@ from plugins._model_config.helpers import model_config
class MissingApiKeyCheck(Extension):
"""Check if API keys are configured for selected model providers."""
- LOCAL_PROVIDERS = {"ollama", "lm_studio"}
+ LOCAL_PROVIDERS = {"ollama", "lm_studio", "omlx"}
CONFIGURE_MODEL_SETTINGS_LINK = (
"""<div class="onboarding-banner-btn-container" style="margin-top: 12px;">"""
"""<button class="btn btn-ok" onclick="window.openModal('/plugins/_onboarding/webui/onboarding.html');return false;">"""
diff --git a/plugins/_model_config/helpers/model_config.py b/plugins/_model_config/helpers/model_config.py
index 045e915c8..08b834ce2 100644
--- a/plugins/_model_config/helpers/model_config.py
+++ b/plugins/_model_config/helpers/model_config.py
@@ -32,7 +32,7 @@ IMPLICIT_PRESET_SLOT_DEFAULTS = {
"kwargs": {},
},
}
-LOCAL_PROVIDERS = {"ollama", "lm_studio"}
+LOCAL_PROVIDERS = {"ollama", "lm_studio", "omlx"}
LOCAL_EMBEDDING = {"huggingface"}
_PROVIDER_METADATA_CACHE: dict | None = None
diff --git a/plugins/_model_config/provider_metadata.yaml b/plugins/_model_config/provider_metadata.yaml
index 1fcd1d6f4..d6dc5bfc3 100644
--- a/plugins/_model_config/provider_metadata.yaml
+++ b/plugins/_model_config/provider_metadata.yaml
@@ -3,6 +3,8 @@ chat:
api_key_mode: none
ollama:
api_key_mode: none
+ omlx:
+ api_key_mode: none
other:
api_key_mode: optional
@@ -13,5 +15,7 @@ embedding:
api_key_mode: none
ollama:
api_key_mode: none
+ omlx:
+ api_key_mode: none
other:
api_key_mode: optional
diff --git a/plugins/_onboarding/webui/assets/provider-logos/omlx.svg b/plugins/_onboarding/webui/assets/provider-logos/omlx.svg
new file mode 100644
index 000000000..7bd64b1b0
--- /dev/null
+++ b/plugins/_onboarding/webui/assets/provider-logos/omlx.svg
@@ -0,0 +1,19 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="160" height="160" viewBox="0 0 160 160" role="img" aria-labelledby="omlx-title">
+ <title id="omlx-title">oMLX</title>
+ <!-- Source: oMLX project icon, Apache-2.0. -->
+ <defs>
+ <filter id="omlx-shadow" x="-10%" y="-10%" width="130%" height="130%">
+ <feDropShadow dx="0" dy="2" stdDeviation="6" flood-color="#000" flood-opacity="0.3"/>
+ </filter>
+ <linearGradient id="omlx-bg" x1="0" y1="0" x2="0" y2="1">
+ <stop offset="0%" stop-color="#2d2d2d"/>
+ <stop offset="100%" stop-color="#1a1a1a"/>
+ </linearGradient>
+ </defs>
+ <rect x="10" y="10" width="140" height="140" rx="32" fill="url(#omlx-bg)" filter="url(#omlx-shadow)"/>
+ <g transform="translate(25, 25) scale(0.0221)">
+ <g transform="translate(0,4970) scale(1,-1)" fill="#fff" stroke="none">
+ <path d="M2275 4349c-408-39-769-207-1056-492-196-194-333-428-418-715-47-158-67-281-101-617-66-662-116-944-245-1387-102-352-271-774-420-1051-19-35-35-70-35-76 0-8 50-11 163-11h164l80 168c168 348 303 739 408 1175 73 307 109 532 155 982 52 500 72 627 122 785 162 507 570 860 1096 951 155 26 389 26 544 0 221-38 440-129 620-258 45-32 152-126 237-209 86-82 178-165 204-183 106-72 312-150 495-186l32-7-86-54c-110-69-170-117-267-212-93-91-143-154-191-243-105-191-130-406-75-623 29-115 81-239 217-516 234-480 343-769 411-1091 36-172 48-252 57-381l7-98h158 158l-4 28c-2 15-6 66-9 113-14 218-95 560-201 849-81 220-165 407-363 810-120 245-147 320-161 443-38 338 202 621 766 906 131 65 166 126 106 183-33 31-86 47-288 88-177 36-274 61-370 97-140 52-190 88-377 270-140 137-202 189-300 254-378 250-782 351-1233 308zM3050 3391c-57-11-122-53-154-99-41-57-49-158-18-218 29-56 66-92 120-117 153-69 323 37 325 203 1 147-131 259-273 231zM1985 1391c-68-31-70-40-66-271 1-114-2-243-9-290-40-307-124-555-255-754-25-38-45-71-45-72 0-2 79-4 176-4h175l54 113c117 247 182 512 201 812 7 126-9 319-32 374-26 63-86 111-136 111-13 0-41-9-63-19z"/>
+ </g>
+ </g>
+</svg>
diff --git a/plugins/_onboarding/webui/onboarding-providers.js b/plugins/_onboarding/webui/onboarding-providers.js
index 55e45090a..7680db5f2 100644
--- a/plugins/_onboarding/webui/onboarding-providers.js
+++ b/plugins/_onboarding/webui/onboarding-providers.js
@@ -25,7 +25,7 @@ export const MORE_CLOUD_PROVIDER_IDS = [
"other",
];
-export const LOCAL_PROVIDER_IDS = ["ollama", "lm_studio", "other"];
+export const LOCAL_PROVIDER_IDS = ["ollama", "lm_studio", "omlx", "other"];
export const ONBOARDING_PROVIDER_OVERRIDES = {
a0_venice: {
@@ -172,6 +172,15 @@ export const ONBOARDING_PROVIDER_OVERRIDES = {
model_list_autoload: true,
short_description: "Ollama cloud models through a hosted endpoint.",
},
+ omlx: {
+ logo: "/plugins/_onboarding/webui/assets/provider-logos/omlx.svg",
+ setup_url: "https://omlx.ai/",
+ docs_url: "https://github.com/jundot/omlx#readme",
+ default_api_base: "http://host.docker.internal:8000/v1",
+ api_key_mode: "none",
+ model_list_autoload: true,
+ short_description: "Apple Silicon local inference with MLX.",
+ },
openai: {
logo: "https://openai.com/favicon.ico",
setup_url: "https://platform.openai.com/",
diff --git a/tests/test_model_config_api_keys.py b/tests/test_model_config_api_keys.py
index fa212a54b..0ec597de8 100644
--- a/tests/test_model_config_api_keys.py
+++ b/tests/test_model_config_api_keys.py
@@ -274,8 +274,10 @@ def test_provider_key_modes_for_local_and_ollama_cloud():
assert model_config.provider_requires_api_key("ollama") is False
assert model_config.provider_requires_api_key("lm_studio") is False
+ assert model_config.provider_requires_api_key("omlx") is False
assert model_config.provider_requires_api_key("other") is False
assert model_config.provider_requires_api_key("ollama_cloud") is True
+ assert "omlx" in missing_key_banner.MissingApiKeyCheck.LOCAL_PROVIDERS
def test_local_provider_defaults_are_docker_friendly():
@@ -297,6 +299,15 @@ def test_local_provider_defaults_are_docker_friendly():
assert provider_config["chat"]["ollama"]["models_list"]["default_base"] == (
"http://host.docker.internal:11434"
)
+ assert provider_config["chat"]["omlx"]["litellm_provider"] == "hosted_vllm"
+ assert provider_config["chat"]["omlx"]["kwargs"]["api_base"] == (
+ "http://host.docker.internal:8000/v1"
+ )
+ assert provider_config["chat"]["omlx"]["kwargs"]["api_key"] == "omlx"
+ assert provider_config["chat"]["omlx"]["models_list"]["default_base"] == (
+ "http://host.docker.internal:8000"
+ )
+ assert provider_config["chat"]["omlx"]["models_list"]["endpoint_url"] == "/v1/models"
assert provider_config["embedding"]["lm_studio"]["kwargs"]["api_base"] == (
"http://host.docker.internal:1234/v1"
)
@@ -304,6 +315,11 @@ def test_local_provider_defaults_are_docker_friendly():
assert provider_config["embedding"]["ollama"]["kwargs"]["api_base"] == (
"http://host.docker.internal:11434"
)
+ assert provider_config["embedding"]["omlx"]["litellm_provider"] == "hosted_vllm"
+ assert provider_config["embedding"]["omlx"]["kwargs"]["api_base"] == (
+ "http://host.docker.internal:8000/v1"
+ )
+ assert provider_config["embedding"]["omlx"]["kwargs"]["api_key"] == "omlx"
def test_local_provider_runtime_defaults_and_overrides(monkeypatch):
@@ -333,6 +349,25 @@ def test_local_provider_runtime_defaults_and_overrides(monkeypatch):
assert ollama_embedding.kwargs["api_base"] == "http://host.docker.internal:11434"
assert "api_key" not in ollama_embedding.kwargs
+ omlx_chat = models.get_chat_model("omlx", "local-chat-model")
+ assert omlx_chat.model_name == "hosted_vllm/local-chat-model"
+ assert omlx_chat.kwargs["api_base"] == "http://host.docker.internal:8000/v1"
+ assert omlx_chat.kwargs["api_key"] == "omlx"
+
+ omlx_embedding = models.get_embedding_model("omlx", "local-embedding-model")
+ assert omlx_embedding.model_name == "hosted_vllm/local-embedding-model"
+ assert omlx_embedding.kwargs["api_base"] == "http://host.docker.internal:8000/v1"
+ assert omlx_embedding.kwargs["api_key"] == "omlx"
+
+ custom_omlx_chat = models.get_chat_model(
+ "omlx",
+ "local-chat-model",
+ api_base="http://127.0.0.1:8000/v1",
+ api_key="real-local-key",
+ )
+ assert custom_omlx_chat.kwargs["api_base"] == "http://127.0.0.1:8000/v1"
+ assert custom_omlx_chat.kwargs["api_key"] == "real-local-key"
+
def test_docker_compose_maps_host_docker_internal_for_local_models():
import yaml
diff --git a/tests/test_model_search.py b/tests/test_model_search.py
index 7540b7342..a90c12ce5 100644
--- a/tests/test_model_search.py
+++ b/tests/test_model_search.py
@@ -66,6 +66,12 @@ def test_model_search_resolves_v1_base_without_duplicate_v1():
assert fmt == "openai"
+def test_model_search_omits_auth_header_for_omlx_placeholder_key():
+ handler = _handler()
+
+ assert handler._build_headers("omlx", "omlx", {}) == {}
+
+
def test_model_search_filters_non_chat_models():
handler = _handler()
diff --git a/tests/test_onboarding_static.py b/tests/test_onboarding_static.py
index dab37a691..41abe7341 100644
--- a/tests/test_onboarding_static.py
+++ b/tests/test_onboarding_static.py
@@ -65,11 +65,16 @@ def test_onboarding_provider_grid_names_are_present_in_metadata():
assert 'docs_url: "https://docs.venice.ai/guides/getting-started/generating-api-key"' in provider_ui
assert 'docs_url: "https://docs.tokenfactory.nebius.com/api-reference/introduction"' in provider_ui
assert 'docs_url: "https://lmstudio.ai/docs/developer/core/authentication"' in provider_ui
+ assert 'logo: "/plugins/_onboarding/webui/assets/provider-logos/omlx.svg"' in provider_ui
+ assert 'docs_url: "https://github.com/jundot/omlx#readme"' in provider_ui
+ assert 'default_api_base: "http://host.docker.internal:8000/v1"' in provider_ui
assert 'docs_url: ""' in provider_ui
assert "api_key_mode: none" in model_metadata
assert "api_key_mode: optional" in model_metadata
assert "Ollama Cloud" in provider_yaml
assert "https://ollama.com/v1" in provider_yaml
+ assert "oMLX" in provider_yaml
+ assert "http://host.docker.internal:8000/v1" in provider_yaml
assert "Nebius Token Factory" in provider_yaml
assert "https://api.tokenfactory.nebius.com/v1" in provider_yaml
assert not (PROJECT_ROOT / "plugins/_model_config/conf/model_providers.yaml").exists()
@@ -87,6 +92,7 @@ def test_onboarding_provider_grid_names_are_present_in_metadata():
"Z.AI",
"Mistral AI",
"Azure OpenAI",
+ "oMLX",
]:
assert name in provider_yaml + provider_ui
@@ -117,9 +123,12 @@ def test_onboarding_provider_grid_names_are_present_in_metadata():
"cometapi.ico",
"github-copilot.svg",
"zai-logo.svg",
+ "omlx.svg",
]:
assert logo in provider_ui
+ assert (PROJECT_ROOT / "plugins/_onboarding/webui/assets/provider-logos/omlx.svg").exists()
+
def test_nebius_provider_config_uses_openai_compatible_token_factory_endpoint():
provider_path = PROJECT_ROOT / "conf/model_providers.yaml"