ODS V3 Pre-Release: Public testing and refinement ahead of the official V3 launch. Turn your PC, Mac, or Linux box into a private AI server.
Python ai-agentsamdcomfyuidockerllama-cppllmlocal-ain8nnvidiaopen-webuiragself-hostedspeech-to-textstrix-halotext-to-speechworkflow-automation
"""Shared configuration and manifest loading for ODS Dashboard API."""
import json
import logging
import os
import re
from pathlib import Path
from typing import Any, Mapping
from urllib.parse import urlparse
import yaml
from env_values import parse_env_value
logger = logging.getLogger(__name__)
# --- Paths ---
INSTALL_DIR = os.environ.get("ODS_INSTALL_DIR", os.path.expanduser("~/ods"))
DATA_DIR = os.environ.get("ODS_DATA_DIR", os.path.expanduser("~/.ods"))
EXTENSIONS_DIR = Path(
os.environ.get(
"ODS_EXTENSIONS_DIR",
str(Path(INSTALL_DIR) / "extensions" / "services")
)
)
DEFAULT_SERVICE_HOST = os.environ.get("SERVICE_HOST", "host.docker.internal")
GPU_BACKEND = os.environ.get("GPU_BACKEND", "nvidia")
ODS_MODES = frozenset({"local", "cloud", "hybrid"})
LOCAL_MODEL_MODES = frozenset({"local", "hybrid"})
# Readable for one release: managed AMD installs written before round F name
# the retired Lemonade mode until the installer migrates their .env.
LEGACY_ODS_MODES = {"lemonade": "local"}
LLM_CONTRACT_ROUTES = frozenset({"gateway", "direct"})
LLM_CONTRACT_PINNING = frozenset({"none", "dynamic"})
def normalize_ods_mode(value: Any) -> str:
"""Return a supported ODS mode or ``unknown`` for missing/invalid input."""
mode = str(value or "").strip().lower()
mode = LEGACY_ODS_MODES.get(mode, mode)
return mode if mode in ODS_MODES else "unknown"
def normalize_llm_backend(value: Any) -> str:
"""Every managed runtime is llama-server; ``lemonade`` reads as it for one release."""
backend = str(value or "").strip().lower()
return "llama-server" if backend == "lemonade" else backend
def normalize_llm_contract(value: Any) -> dict[str, Any] | None:
"""Normalize a manifest ``llm`` contract for API and harness consumers."""
if not isinstance(value, dict):
return None
consumes = bool(value.get("consumes", False))
route = str(value.get("route") or "").strip().lower()
pinning = str(value.get("pinning") or "").strip().lower()
if route not in LLM_CONTRACT_ROUTES:
route = "direct" if consumes else ""
if pinning not in LLM_CONTRACT_PINNING:
pinning = "none"
normalized: dict[str, Any] = {
"consumes": consumes,
"route": route,
"pinning": pinning,
}
min_context = value.get("min_context")
if min_context is not None:
try:
normalized["min_context"] = max(0, int(min_context))
except (TypeError, ValueError):
logger.warning("Ignoring invalid llm.min_context value: %r", min_context)
probe = value.get("probe")
if isinstance(probe, dict):
normalized["probe"] = probe.copy()
swap_safe = bool(consumes and (route == "gateway" or pinning == "dynamic"))
normalized["swap_safe"] = swap_safe
# camelCase alias: the fleet model-ui harness gates required probes on llm.swapSafe
normalized["swapSafe"] = swap_safe
normalized["badge"] = "swap-safe" if swap_safe else "not-swap-safe"
if not consumes:
normalized["swap_safe_reason"] = "This service does not declare LLM inference consumption."
elif route == "gateway":
normalized["swap_safe_reason"] = "Routes through the ODS gateway alias and follows model swaps automatically."
elif pinning == "dynamic":
normalized["swap_safe_reason"] = "Declares a dynamic model refresh path and is re-probed after swaps."
else:
normalized["swap_safe_reason"] = "Direct model route without a declared refresh path; swaps may require reconciliation."
return normalized
# This is the mode of the running dashboard-api container. Unlike the mounted
# .env file, the process environment is fixed until the service is recreated.
ODS_MODE_EFFECTIVE = normalize_ods_mode(os.environ.get("ODS_MODE"))
_ENV_FILE_PERMISSION_ERROR: str | None = None
_ENV_FILE_PERMISSION_ERROR_LOGGED: bool = False
def get_env_file_read_error() -> str | None:
"""Return the last permission error encountered when reading .env, if any."""
return _ENV_FILE_PERMISSION_ERROR
def _reset_env_permission_state() -> None:
global _ENV_FILE_PERMISSION_ERROR, _ENV_FILE_PERMISSION_ERROR_LOGGED
_ENV_FILE_PERMISSION_ERROR = None
_ENV_FILE_PERMISSION_ERROR_LOGGED = False
def _handle_env_permission_error(
env_path: Path, key_or_keys: Any, exc: PermissionError
) -> None:
global _ENV_FILE_PERMISSION_ERROR, _ENV_FILE_PERMISSION_ERROR_LOGGED
_ENV_FILE_PERMISSION_ERROR = (
f"Permission denied reading {env_path}; live settings may be unavailable"
)
if not _ENV_FILE_PERMISSION_ERROR_LOGGED:
logger.warning(
"Permission denied reading environment file %s for %s: %s",
env_path,
key_or_keys,
exc,
)
_ENV_FILE_PERMISSION_ERROR_LOGGED = True
def _handle_env_read_success(env_path: Path) -> None:
global _ENV_FILE_PERMISSION_ERROR, _ENV_FILE_PERMISSION_ERROR_LOGGED
if _ENV_FILE_PERMISSION_ERROR_LOGGED or _ENV_FILE_PERMISSION_ERROR is not None:
logger.info(
"Successfully read environment file %s; cleared previous permission error",
env_path,
)
_ENV_FILE_PERMISSION_ERROR = None
_ENV_FILE_PERMISSION_ERROR_LOGGED = False
def _find_env_file_value(key: str) -> tuple[bool, str]:
"""Return the last persisted value and distinguish missing from empty."""
env_path = Path(INSTALL_DIR) / ".env"
found = False
value = ""
try:
lines = env_path.read_text(encoding="utf-8").splitlines()
_handle_env_read_success(env_path)
for line in lines:
if line.startswith(f"{key}="):
found = True
value = parse_env_value(line.split("=", 1)[1])
except PermissionError as exc:
_handle_env_permission_error(env_path, f"key {key}", exc)
except FileNotFoundError:
_reset_env_permission_state()
except (OSError, UnicodeError):
pass
return found, value
def _read_env_from_file(key: str) -> str:
"""Read a variable from the persisted .env file."""
return _find_env_file_value(key)[1]
def read_live_env_value(key: str, default: str = "") -> str:
"""Read mutable ODS state from the mounted .env before process startup env."""
found, value = _find_env_file_value(key)
if found:
return value
return os.environ.get(key, "") or default
def read_live_env_values(keys: tuple[str, ...]) -> dict[str, str]:
"""Read one persisted snapshot so a route and its credential cannot diverge."""
values = {key: os.environ.get(key, "") for key in keys}
env_path = Path(INSTALL_DIR) / ".env"
try:
text = env_path.read_text(encoding="utf-8")
_handle_env_read_success(env_path)
except PermissionError as exc:
_handle_env_permission_error(env_path, f"keys {keys}", exc)
return values
except FileNotFoundError:
_reset_env_permission_state()
return values
except (OSError, UnicodeError):
return values
for line in text.splitlines():
key, separator, raw = line.partition("=")
if separator and key in values:
values[key] = parse_env_value(raw)
return values
def _apply_host_native_llm_service_override(
services: dict[str, dict[str, Any]],
gpu_backend: str,
environment: Mapping[str, str] | None = None,
) -> None:
"""Route probes to native inference rather than the container's default port."""
env = environment if environment is not None else os.environ
if str(gpu_backend).lower() == "apple":
service = services.get("llama-server")
if not service or str(env.get("LLM_BACKEND", "")).lower() == "external":
return
# The macOS overlay supplies the Docker-reachable native endpoint.
# Do not substitute a general model-router/LiteLLM URL here.
configured_url = env.get("OLLAMA_URL", "")
if not configured_url:
return
try:
parsed = urlparse(configured_url)
port = parsed.port if parsed.port is not None else 80
if (parsed.scheme != "http" or not parsed.hostname
or parsed.username is not None or parsed.password is not None
or parsed.query or parsed.fragment or not 1 <= port <= 65535):
return
except ValueError:
return
service["host"] = parsed.hostname
service["port"] = port
return
# A llama-server.exe on the Windows host: the legacy native flow (AMD), or
# the WSL Portal (whose WSL side may see no GPU) through host.docker.internal.
if str(gpu_backend).lower() not in {"amd", "cpu"}:
return
if str(env.get("AMD_INFERENCE_LOCATION", "")).strip().lower() != "host":
return
if str(env.get("LLM_BACKEND", "")).strip().lower() == "external":
return
service = services.get("llama-server")
if not service:
return
# The generic LLM URL can be LiteLLM. Its model aliases do not identify
# the served model; probe the server's own container-visible origin.
# LEMONADE_CONTAINER_BASE_URL is that origin's one-release legacy name.
generic_url = str(env.get("LLM_API_URL") or "")
configured_url = (
env.get("NATIVE_LLM_CONTAINER_BASE_URL")
or env.get("LEMONADE_CONTAINER_BASE_URL")
or env.get("OLLAMA_URL")
or env.get("LLM_URL")
or (generic_url if "litellm" not in generic_url.lower() else "")
or f"http://host.docker.internal:{env.get('AMD_INFERENCE_PORT', '8080')}"
)
parsed = urlparse(str(configured_url).strip())
if not parsed.hostname:
logger.warning("Ignoring invalid host-native LLM URL: %s", configured_url)
return
try:
port = parsed.port or int(env.get("AMD_INFERENCE_PORT", "8080"))
except ValueError:
logger.warning("Ignoring invalid host-native LLM port in URL: %s", configured_url)
return
service["host"] = parsed.hostname
service["port"] = port
# The in-stack container is off on this route; its sidebar link (OLLAMA_PORT, 11434) opened an error page.
service["external_link"] = False
logger.info("Host-native llama-server detected; routing LLM probes to %s:%d", parsed.hostname, port)
def _apply_external_llm_service_override(
services: dict[str, dict[str, Any]],
environment: Mapping[str, str] | None = None,
) -> None:
"""Route dashboard LLM probes to a validated external Ollama/LM Studio endpoint."""
env = environment if environment is not None else os.environ
if str(env.get("LLM_BACKEND", "")).strip().lower() != "external":
return
service = services.get("llama-server")
if not service:
return
configured_url = (
env.get("EXTERNAL_LLM_CONTAINER_URL")
or env.get("LLM_API_URL")
or ""
)
parsed = urlparse(str(configured_url).strip())
if parsed.scheme not in {"http", "https"} or not parsed.hostname:
logger.warning("Ignoring invalid external LLM URL: %s", configured_url)
return
try:
port = parsed.port or (443 if parsed.scheme == "https" else 80)
except ValueError:
logger.warning("Ignoring invalid external LLM port in URL: %s", configured_url)
return
provider = str(env.get("EXTERNAL_LLM_PROVIDER", "")).strip().lower()
health_paths = {
"ollama": "/api/tags",
"lmstudio": "/v1/models",
}
service["host"] = parsed.hostname
service["port"] = port
# The health probe reaches the API with its own scheme and Host header;
# an HTTPS API answered the old http://host:443 probe with an error.
service["scheme"] = parsed.scheme
service["external_api"] = True
service["health"] = health_paths.get(provider, "/v1/models")
service["name"] = {
"ollama": "Ollama (External LLM)",
"lmstudio": "LM Studio (External LLM)",
}.get(provider, "External LLM")
logger.info(
"External %s inference detected; routing LLM probes to %s:%d%s",
provider or "OpenAI-compatible",
parsed.hostname,
port,
service["health"],
)
VLLM_SERVICE_HOST = "vllm-server"
VLLM_SERVICE_PORT = 8000
VLLM_CONTAINER = "ods-vllm-server"
def _apply_vllm_service_override(
services: dict[str, dict[str, Any]],
environment: Mapping[str, str] | None = None,
) -> None:
"""Route the LLM row's probes to the vLLM engine (LLM_BACKEND=vllm).
docker-compose.vllm.yml profiles the in-stack llama-server out and runs
vllm-server on the ODS network: /health answers 200 with an empty body once
the model is loaded, /v1/models lists the served id. As for a host-native
or external route, the row keeps the llama-server id that chat, readiness
and features key on; its container is ods-vllm-server, which the host
agent's Docker health snapshot reports (a cold start reads as starting),
and it publishes no host port to link to.
"""
env = environment if environment is not None else os.environ
if str(env.get("LLM_BACKEND", "")).strip().lower() != "vllm":
return
service = services.get("llama-server")
if not service:
return
service["host"] = VLLM_SERVICE_HOST
service["port"] = VLLM_SERVICE_PORT
service["health"] = "/health"
service["container_name"] = VLLM_CONTAINER
service["name"] = "vLLM (LLM Inference)"
service["external_link"] = False
logger.info("vLLM engine selected; routing LLM probes to %s:%d", VLLM_SERVICE_HOST, VLLM_SERVICE_PORT)
def _read_env_value(key: str) -> str:
return (os.environ.get(key) or _read_env_from_file(key)).strip()
def _service_public_url_key(service_id: str) -> str:
return re.sub(r"[^A-Za-z0-9]+", "_", service_id).strip("_").upper()
def _valid_public_url(value: str) -> str:
candidate = value.strip().rstrip("/")
if not candidate:
return ""
parsed = urlparse(candidate)
if parsed.scheme not in {"http", "https"} or not parsed.netloc:
logger.warning("Ignoring invalid public service URL: %s", value)
return ""
return candidate
def _read_service_public_url_map() -> dict[str, str]:
raw = _read_env_value("ODS_SERVICE_PUBLIC_URLS")
if not raw:
return {}
try:
data = json.loads(raw)
except json.JSONDecodeError:
logger.warning("Ignoring invalid ODS_SERVICE_PUBLIC_URLS JSON")
return {}
if not isinstance(data, dict):
logger.warning("Ignoring ODS_SERVICE_PUBLIC_URLS because it is not a JSON object")
return {}
return {
str(key): _valid_public_url(str(value))
for key, value in data.items()
if str(value).strip()
}
def _candidate_public_url_env_names(
service_id: str,
service: dict[str, Any],
ext_port_env: str | None,
) -> list[str]:
service_key = _service_public_url_key(service_id)
names = [
service.get("public_url_env", ""),
f"{service_key}_PUBLIC_URL",
f"ODS_{service_key}_PUBLIC_URL",
]
if ext_port_env:
if ext_port_env.endswith("_EXTERNAL_PORT"):
names.append(f"{ext_port_env.removesuffix('_EXTERNAL_PORT')}_PUBLIC_URL")
if ext_port_env.endswith("_PORT"):
names.append(f"{ext_port_env.removesuffix('_PORT')}_PUBLIC_URL")
names.append(f"{ext_port_env}_PUBLIC_URL")
return [name for index, name in enumerate(names) if name and name not in names[:index]]
def _resolve_public_service_url(
service_id: str,
service: dict[str, Any],
ext_port_env: str | None,
public_url_map: dict[str, str],
) -> str:
service_key = _service_public_url_key(service_id)
for map_key in (service_id, service_key, service_key.lower()):
url = public_url_map.get(map_key)
if url:
return url
for env_name in _candidate_public_url_env_names(service_id, service, ext_port_env):
url = _valid_public_url(_read_env_value(env_name))
if url:
return url
return ""
# --- Manifest Loading ---
MAX_MANIFEST_DEPTH = 32
MAX_MANIFEST_NODES = 10_000
MAX_MANIFEST_BYTES = 1_048_576
class _ManifestLoader(yaml.SafeLoader):
"""Bound composition before recursive parsing or YAML merge expansion."""
def __init__(self, stream):
super().__init__(stream)
self.manifest_depth = -1
self.manifest_nodes = 0
def compose_node(self, parent, index):
self.manifest_depth += 1
self.manifest_nodes += 1
try:
if self.manifest_depth > MAX_MANIFEST_DEPTH:
raise ValueError(f"Manifest nesting exceeds {MAX_MANIFEST_DEPTH} levels")
if self.manifest_nodes > MAX_MANIFEST_NODES:
raise ValueError("Manifest structure exceeds node limit")
return super().compose_node(parent, index)
finally:
self.manifest_depth -= 1
def _validate_yaml_graph(root) -> None:
# Memoize subtree size and height, counting each alias occurrence toward
# expanded size without actually expanding it. Validate before constructors
# flatten merge keys, which can otherwise allocate exponentially many pairs.
memo = {}
active = set()
def visit(node):
marker = id(node)
if marker in active:
raise ValueError("Manifest contains a cyclic structure")
if marker in memo:
return memo[marker]
active.add(marker)
if isinstance(node, yaml.MappingNode):
children = (child for pair in node.value for child in pair)
elif isinstance(node, yaml.SequenceNode):
children = iter(node.value)
else:
children = iter(())
size, height = 1, 0
for child in children:
child_size, child_height = visit(child)
size += child_size
height = max(height, child_height + 1)
if size > MAX_MANIFEST_NODES:
raise ValueError("Manifest alias expansion exceeds node limit")
if height > MAX_MANIFEST_DEPTH:
raise ValueError(f"Manifest nesting exceeds {MAX_MANIFEST_DEPTH} levels")
active.remove(marker)
memo[marker] = size, height
return size, height
visit(root)
def _validate_manifest_depth(value: Any, *, depth: int = 0, active: set[int] | None = None) -> None:
"""Reject pathological nested or cyclic YAML/JSON structures early."""
if depth > MAX_MANIFEST_DEPTH:
raise ValueError(f"Manifest nesting exceeds {MAX_MANIFEST_DEPTH} levels")
if not isinstance(value, (dict, list)):
return
active = active if active is not None else set()
marker = id(value)
if marker in active:
raise ValueError("Manifest contains a cyclic structure")
active.add(marker)
try:
if isinstance(value, dict):
for key, item in value.items():
_validate_manifest_depth(key, depth=depth + 1, active=active)
_validate_manifest_depth(item, depth=depth + 1, active=active)
else:
for item in value:
_validate_manifest_depth(item, depth=depth + 1, active=active)
finally:
active.remove(marker)
def _read_manifest_file(path: Path) -> dict[str, Any]:
"""Load a JSON or YAML extension manifest file."""
with path.open("rb") as stream:
raw = stream.read(MAX_MANIFEST_BYTES + 1)
if len(raw) > MAX_MANIFEST_BYTES:
raise ValueError("Manifest exceeds size limit")
text = raw.decode("utf-8")
try:
if path.suffix.lower() == ".json":
data = json.loads(text)
else:
loader = _ManifestLoader(text)
try:
node = loader.get_single_node()
_validate_yaml_graph(node)
data = loader.construct_document(node) if node is not None else None
finally:
loader.dispose()
except RecursionError as exc:
raise ValueError(f"Manifest nesting exceeds {MAX_MANIFEST_DEPTH} levels") from exc
_validate_manifest_depth(data)
if not isinstance(data, dict):
raise ValueError("Manifest root must be an object")
return data
def load_extension_manifests(
manifest_dir: Path, gpu_backend: str,
*, only_service_ids: frozenset[str] | None = None,
) -> tuple[dict[str, dict[str, Any]], list[dict[str, Any]], list[dict[str, str]]]:
"""Load service and feature definitions from extension manifests.
Returns a 3-tuple: (services, features, errors) where *errors* is a list
of ``{"file": ..., "error": ...}`` dicts for manifests that failed to load.
"""
services: dict[str, dict[str, Any]] = {}
features: list[dict[str, Any]] = []
errors: list[dict[str, str]] = []
loaded = 0
if not manifest_dir.exists():
logger.info("Extension manifest directory not found: %s", manifest_dir)
return services, features, errors
public_url_map = _read_service_public_url_map()
manifest_files: list[Path] = []
for item in sorted(manifest_dir.iterdir()):
if only_service_ids is not None and item.name not in only_service_ids:
continue
if item.is_dir():
for name in ("manifest.yaml", "manifest.yml", "manifest.json"):
candidate = item / name
if candidate.exists():
manifest_files.append(candidate)
break
elif item.suffix.lower() in (".yaml", ".yml", ".json"):
manifest_files.append(item)
for path in manifest_files:
try:
# Skip disabled extensions (compose.yaml.disabled convention)
ext_dir = path.parent
if (ext_dir / "compose.yaml.disabled").exists() or (ext_dir / "compose.yml.disabled").exists():
logger.debug("Skipping disabled extension: %s", ext_dir.name)
continue
manifest = _read_manifest_file(path)
if manifest.get("schema_version") != "ods.services.v1":
logger.warning("Skipping manifest with unsupported schema_version: %s", path)
errors.append({"file": str(path), "error": "Unsupported schema_version"})
continue
service = manifest.get("service")
if isinstance(service, dict):
service_id = service.get("id")
if not service_id:
raise ValueError("service.id is required")
compose_file = str(service.get("compose_file") or "").strip()
if service.get("type") == "docker" and compose_file:
compose_path = ext_dir / compose_file
if not compose_path.exists():
logger.debug(
"Skipping docker service %s because %s is not installed",
service_id,
compose_path,
)
continue
supported = service.get("gpu_backends", ["amd", "nvidia", "apple"])
if gpu_backend == "apple":
if (
service.get("type") == "host-systemd"
and not service.get("macos_host_supported", False)
):
continue # Linux-only service, not available on macOS
# All docker services run on macOS regardless of gpu_backends declaration
elif gpu_backend not in supported and "all" not in supported:
continue
host_env = service.get("host_env")
default_host = service.get("default_host", "localhost")
host = os.environ.get(host_env, default_host) if host_env else default_host
ext_port_env = service.get("external_port_env")
ext_port_default = service.get("external_port_default", service.get("port", 0))
if ext_port_env:
val = os.environ.get(ext_port_env) or _read_env_from_file(ext_port_env)
external_port = int(val) if val else int(ext_port_default)
else:
external_port = int(ext_port_default)
public_url = _resolve_public_service_url(service_id, service, ext_port_env, public_url_map)
service_config = {
"host": host,
"port": int(service.get("port", 0)),
"external_port": external_port,
"health": service.get("health", "/health"),
"name": service.get("name", service_id),
"ui_path": service.get("ui_path", "/"),
"public_url": public_url,
"external_link": bool(service.get("external_link", True)),
"macos_host_supported": bool(service.get("macos_host_supported", False)),
"container_name": service.get("container_name", f"ods-{service_id}"),
"depends_on": service.get("depends_on", []),
"category": service.get("category", "optional"),
"host_network": bool(service.get("host_network", False)),
"socket_only": bool(service.get("socket_only", False)),
"setup_hook": service.get("setup_hook", ""),
"hooks": service.get("hooks", {}),
"gpu_backends": service.get("gpu_backends", []),
**({"type": service["type"]} if "type" in service else {}),
**({"health_port": int(service["health_port"])} if "health_port" in service else {}),
}
llm_contract = normalize_llm_contract(service.get("llm"))
if llm_contract is not None:
service_config["llm"] = llm_contract
services[service_id] = service_config
manifest_features = manifest.get("features", [])
if isinstance(manifest_features, list):
for feature in manifest_features:
if not isinstance(feature, dict):
continue
supported = feature.get("gpu_backends", ["amd", "nvidia", "apple"])
if gpu_backend != "apple" and gpu_backend not in supported and "all" not in supported:
continue
if feature.get("id") and feature.get("name"):
missing = [f for f in ("description", "icon", "category", "setup_time", "priority") if f not in feature]
if missing:
logger.warning("Feature '%s' in %s missing optional fields: %s", feature["id"], path, ", ".join(missing))
features.append(feature)
loaded += 1
except (yaml.YAMLError, json.JSONDecodeError, OSError, KeyError, TypeError, ValueError) as e:
logger.warning("Failed loading manifest %s: %s", path, e)
errors.append({"file": str(path), "error": str(e)})
logger.info("Loaded %d extension manifests (%d services, %d features)", loaded, len(services), len(features))
return services, features, errors
# --- Service Registry ---
MANIFEST_SERVICES, MANIFEST_FEATURES, MANIFEST_ERRORS = load_extension_manifests(EXTENSIONS_DIR, GPU_BACKEND)
SERVICES = MANIFEST_SERVICES
if not SERVICES:
logger.error("No services loaded from manifests in %s — dashboard will have no services", EXTENSIONS_DIR)
LLM_BACKEND = normalize_llm_backend(os.environ.get("LLM_BACKEND", ""))
_apply_host_native_llm_service_override(SERVICES, GPU_BACKEND)
_apply_external_llm_service_override(SERVICES)
_apply_vllm_service_override(SERVICES)
# --- Features ---
FEATURES = MANIFEST_FEATURES
if not FEATURES:
logger.warning("No features loaded from manifests — check %s", EXTENSIONS_DIR)
# --- Workflow Config ---
def resolve_workflow_dir() -> Path:
"""Resolve canonical workflow directory with legacy fallback."""
env_dir = os.environ.get("WORKFLOW_DIR")
if env_dir:
return Path(env_dir)
canonical = Path(INSTALL_DIR) / "config" / "n8n"
try:
if canonical.exists():
return canonical
except PermissionError:
# Optional host configuration may belong to a different UID. Keep
# the canonical path so the workflow endpoint can report unavailable
# access, rather than crashing startup or selecting an empty fallback.
return canonical
return Path(INSTALL_DIR) / "workflows"
WORKFLOW_DIR = resolve_workflow_dir()
WORKFLOW_CATALOG_FILE = WORKFLOW_DIR / "catalog.json"
DEFAULT_WORKFLOW_CATALOG = {"workflows": [], "categories": {}}
def _default_n8n_url() -> str:
cfg = SERVICES.get("n8n", {})
host = cfg.get("host", "n8n")
port = cfg.get("port", 5678)
return f"http://{host}:{port}"
N8N_URL = os.environ.get("N8N_URL", _default_n8n_url())
# --- Setup / Personas ---
SETUP_CONFIG_DIR = Path(DATA_DIR) / "config"
PERSONAS = {
"general": {
"name": "General Helper",
"system_prompt": "You are a friendly and helpful AI assistant. You're knowledgeable, patient, and aim to be genuinely useful. Keep responses clear and conversational.",
"icon": "\U0001f4ac"
},
"coding": {
"name": "Coding Buddy",
"system_prompt": "You are a skilled programmer and technical assistant. You write clean, well-documented code and explain technical concepts clearly. You're precise, thorough, and love solving problems.",
"icon": "\U0001f4bb"
},
"creative": {
"name": "Creative Writer",
"system_prompt": "You are an imaginative creative writer and storyteller. You craft vivid descriptions, engaging narratives, and think outside the box. You're expressive and enjoy wordplay.",
"icon": "\U0001f3a8"
}
}
# --- Sidebar Icons ---
SIDEBAR_ICONS = {
"open-webui": "MessageSquare",
"n8n": "Network",
"hermes": "Bot",
"hermes-proxy": "Shield",
"opencode": "Code",
"perplexica": "Search",
"comfyui": "Image",
"token-spy": "Terminal",
"langfuse": "BarChart2",
}
# --- Extensions Portal ---
CATALOG_PATH = Path(os.environ.get(
"ODS_EXTENSIONS_CATALOG",
str(Path(INSTALL_DIR) / "config" / "extensions-catalog.json")
))
EXTENSIONS_LIBRARY_DIR = Path(os.environ.get(
"ODS_EXTENSIONS_LIBRARY_DIR",
str(Path(DATA_DIR) / "extensions-library")
))
USER_EXTENSIONS_DIR = Path(os.environ.get(
"ODS_USER_EXTENSIONS_DIR",
str(Path(DATA_DIR) / "user-extensions")
))
def _load_core_service_ids() -> frozenset:
core_ids_path = Path(INSTALL_DIR) / "config" / "core-service-ids.json"
if core_ids_path.exists():
try:
return frozenset(json.loads(core_ids_path.read_text(encoding="utf-8")))
except (json.JSONDecodeError, OSError):
pass
# Fallback to hardcoded list
return frozenset({
"dashboard-api", "dashboard", "llama-server", "model-router", "open-webui",
"litellm", "langfuse", "hermes", "hermes-proxy", "n8n", "opencode",
"perplexica", "searxng", "qdrant", "remote-provider-egress",
"remote-provider-ssh-tunnel", "tts", "whisper",
"embeddings", "token-spy", "comfyui", "ape", "privacy-shield",
})
CORE_SERVICE_IDS = _load_core_service_ids()
# Always-on services defined in docker-compose.base.yml — never manageable via API.
# Distinct from CORE_SERVICE_IDS (the full built-in service allowlist).
ALWAYS_ON_SERVICES: frozenset = frozenset({
"llama-server", "model-router", "remote-provider-egress",
"remote-provider-ssh-tunnel", "open-webui", "dashboard", "dashboard-api",
})
# Built-ins qualified for Dashboard Library Add/Disable. The live health poll
# must refresh this same set after a fragment changes without an API restart.
# A lean install adds the original stack back from here, one click each; every
# entry was enabled live from a lean fleet install and proved working. Token
# Spy and APE build app source locally and wait for a reviewed source recipe.
LIBRARY_MANAGEABLE_BUILTINS: frozenset = frozenset({
"n8n", "perplexica", "searxng",
"hermes", "hermes-proxy", "qdrant", "embeddings", "tts", "whisper",
"comfyui", "langfuse",
})
_CATALOG_ID_RE = re.compile(r"[a-z0-9][a-z0-9_-]*")
def load_extension_catalog() -> list[dict]:
"""Load the static extensions catalog JSON. Returns empty list on failure."""
if not CATALOG_PATH.exists():
logger.info("Extensions catalog not found at %s", CATALOG_PATH)
return []
try:
data = json.loads(CATALOG_PATH.read_text(encoding="utf-8"))
except (json.JSONDecodeError, OSError) as e:
logger.warning("Failed to load extensions catalog: %s", e)
return []
# Catalog ids name folders (progress files, library receipts, installed
# trees), so an entry whose id is not a plain extension id is dropped.
entries = []
for entry in data.get("extensions", []):
identifier = entry.get("id") if isinstance(entry, dict) else None
if isinstance(identifier, str) and _CATALOG_ID_RE.fullmatch(identifier):
entries.append(entry)
else:
logger.warning("Ignoring extensions catalog entry with invalid id %r", identifier)
return entries
EXTENSION_CATALOG = load_extension_catalog()
# --- Host Agent ---
def _running_inside_container() -> bool:
"""Best-effort check for Docker/Podman/containerd runtime context."""
if Path("/.dockerenv").exists():
return True
try:
cgroup = Path("/proc/1/cgroup").read_text(encoding="utf-8").lower()
except OSError:
return False
return any(marker in cgroup for marker in ("docker", "containerd", "kubepods", "podman"))
def _running_under_wsl(release_path: str = "/proc/sys/kernel/osrelease") -> bool:
"""Return whether the dashboard container shares a WSL Linux kernel."""
try:
release = Path(release_path).read_text(encoding="utf-8")
except OSError:
return False
return "microsoft" in release.casefold()
def _detect_container_default_gateway(route_path: str = "/proc/net/route") -> str:
"""Return this container's default-gateway IP, or empty on failure.
Reads /proc/net/route directly so the container image doesn't need
iproute2 installed. The default route line has destination 00000000 and
a little-endian-hex gateway in the 3rd field.
Why this matters: dashboard-api runs on `ods-network` (a custom bridge,
e.g. 172.18.0.0/16). On Linux, the ods-host-agent binds to that network's
host-side gateway when it can, so targeting this container's default gateway
is routable without depending on `host.docker.internal:host-gateway`, which
Docker often resolves to the default bridge gateway (172.17.0.1). That
default bridge address is unreachable from custom networks under Docker's
default DOCKER-ISOLATION-STAGE-2 iptables rules.
"""
try:
with open(route_path, "r", encoding="utf-8") as f:
for line in f.readlines()[1:]:
fields = line.strip().split()
# destination == 0.0.0.0 AND flags has RTF_GATEWAY (0x2)
if len(fields) < 4 or fields[1] != "00000000":
continue
gw_hex = fields[2]
try:
flags = int(fields[3], 16)
gateway_raw = int(gw_hex, 16)
except ValueError:
continue
if not (flags & 0x2) or gateway_raw == 0 or len(gw_hex) != 8:
continue
# Little-endian: 0100A8C0 -> 192.168.0.1
return ".".join(
str(int(gw_hex[i:i + 2], 16)) for i in (6, 4, 2, 0)
)
except OSError:
pass
return ""
def _resolve_agent_host() -> str:
"""Pick the host name/IP to use for the ods-host-agent.
Priority:
1. ODS_AGENT_HOST env (explicit operator override)
2. host.docker.internal under WSL/Docker Desktop, whose compose gateway
belongs to Docker Desktop and is not an address the WSL host can bind
3. The container's own default-gateway IP on native Linux
4. host.docker.internal (legacy fallback — broken on custom networks
under default Docker iptables, but kept so explicit operator setups
relying on it don't silently change)
"""
explicit = os.environ.get("ODS_AGENT_HOST", "").strip()
if explicit:
return explicit
if _running_inside_container():
if _running_under_wsl():
logger.info("Resolved ODS_AGENT_HOST=host.docker.internal for WSL")
return "host.docker.internal"
gw = _detect_container_default_gateway()
if gw:
logger.info("Resolved ODS_AGENT_HOST=%s via /proc/net/route", gw)
return gw
logger.warning(
"Could not detect container default gateway; falling back to "
"host.docker.internal. If host-agent calls time out, set "
"ODS_AGENT_HOST=<host-ip> in dashboard-api's environment."
)
return "host.docker.internal"
AGENT_HOST = _resolve_agent_host()
AGENT_PORT = int(os.environ.get("ODS_AGENT_PORT", "7710"))
AGENT_URL = f"http://{AGENT_HOST}:{AGENT_PORT}"
DASHBOARD_API_KEY = os.environ.get("DASHBOARD_API_KEY", "")
# Prefer dedicated ODS_AGENT_KEY; fall back to DASHBOARD_API_KEY for
# existing installs that haven't generated a separate key yet.
ODS_AGENT_KEY = os.environ.get("ODS_AGENT_KEY", "") or DASHBOARD_API_KEY
# --- Templates ---
TEMPLATES_DIR = Path(
os.environ.get(
"ODS_TEMPLATES_DIR",
str(Path(INSTALL_DIR) / "templates")
)
)
_TEMPLATE_SCHEMA = None
try:
import jsonschema as _jsonschema_mod
_schema_path = Path(__file__).parent.parent.parent / "schema" / "service-template.v1.json"
if _schema_path.exists():
_TEMPLATE_SCHEMA = json.loads(_schema_path.read_text(encoding="utf-8"))
except ImportError:
_jsonschema_mod = None
def load_templates() -> list[dict]:
"""Load service templates from YAML files. Returns empty list on failure."""
if not TEMPLATES_DIR.exists():
logger.info("Templates directory not found at %s", TEMPLATES_DIR)
return []
templates = []
for path in sorted(TEMPLATES_DIR.iterdir()):
if path.suffix.lower() not in (".yaml", ".yml"):
continue
try:
data = yaml.safe_load(path.read_text(encoding="utf-8"))
if not isinstance(data, dict):
logger.warning("Skipping template %s: root is not a mapping", path.name)
continue
if data.get("schema_version") != "ods.templates.v1":
logger.warning("Skipping template %s: unsupported schema_version", path.name)
continue
# Validate against JSON Schema if available
if _TEMPLATE_SCHEMA is not None and _jsonschema_mod is not None:
try:
_jsonschema_mod.validate(data, _TEMPLATE_SCHEMA)
except _jsonschema_mod.ValidationError as ve:
logger.warning("Template validation failed for %s: %s", path.name, ve.message)
continue
template = data.get("template")
if not isinstance(template, dict) or not template.get("id") or not template.get("services"):
logger.warning("Skipping template %s: missing required fields", path.name)
continue
templates.append(template)
except (yaml.YAMLError, OSError, ValueError) as e:
logger.warning("Failed loading template %s: %s", path.name, e)
logger.info("Loaded %d service templates", len(templates))
return templates
TEMPLATES = load_templates()