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
#!/usr/bin/env bash
# ods-cli - Command line interface for ODS
# Mission: M5 (Clonable ODS Setup Server)
# Registry-driven service resolution; VERSION below is the product version.
set -euo pipefail
# Require Bash 4+ (associative arrays used by service registry and ods-cli)
if (( BASH_VERSINFO[0] < 4 )); then
# macOS starts env bash with Apple's Bash 3.2 even after Homebrew installs
# Bash 4+. Re-exec the installed modern Bash before using associative arrays.
for _ods_modern_bash in /opt/homebrew/bin/bash /usr/local/bin/bash; do
if [[ -x "$_ods_modern_bash" ]] &&
"$_ods_modern_bash" -c '(( BASH_VERSINFO[0] >= 4 ))' >/dev/null 2>&1; then
exec "$_ods_modern_bash" "$0" "$@"
fi
done
echo -e "\033[0;31m✗\033[0m ods-cli requires Bash 4.0+ (you have $BASH_VERSION)" >&2
echo " macOS ships Bash 3.2 due to licensing. Install a modern version:" >&2
echo " brew install bash" >&2
echo " Then re-run with: /opt/homebrew/bin/bash $0 $*" >&2
exit 1
fi
#=============================================================================
# Configuration
#=============================================================================
# Commands cd into INSTALL_DIR; resolve user-typed paths against where ods ran.
ODS_CALLER_PWD="$PWD"
_caller_path() {
if [[ -z "$1" || "$1" == /* ]]; then
printf '%s' "$1"
else
printf '%s/%s' "$ODS_CALLER_PWD" "$1"
fi
}
_source="${BASH_SOURCE[0]}"
while [[ -L "$_source" ]]; do
_dir="$(cd "$(dirname "$_source")" && pwd)"
_source="$(readlink "$_source")"
[[ "$_source" != /* ]] && _source="$_dir/$_source"
done
SCRIPT_DIR="$(cd "$(dirname "$_source")" && pwd)"
_resolve_cli_install_dir() {
if [[ -n "${INSTALL_DIR:-}" ]]; then
printf '%s\n' "$INSTALL_DIR"
elif [[ -n "${ODS_HOME:-}" ]]; then
printf '%s\n' "$ODS_HOME"
elif [[ -n "${ODS_SCRIPT_HINT:-}" ]] && [[ -f "$ODS_SCRIPT_HINT/.env" ]]; then
printf '%s\n' "$ODS_SCRIPT_HINT"
elif [[ -n "${ODS_INSTALL_DIR:-}" ]]; then
printf '%s\n' "$ODS_INSTALL_DIR"
elif [[ -f "$SCRIPT_DIR/docker-compose.base.yml" || -f "$SCRIPT_DIR/docker-compose.yml" ]]; then
# Installed copies and symlink targets are self-locating. This keeps a
# custom-path CLI from silently operating on an unrelated $HOME/ods.
printf '%s\n' "$SCRIPT_DIR"
else
printf '%s\n' "$HOME/ods"
fi
}
INSTALL_DIR="$(_resolve_cli_install_dir)"
VERSION="3.0.0"
if [[ -f "$INSTALL_DIR/.env" ]]; then
_v=$(awk -F= '/^ODS_VERSION=/{gsub(/^["'"'"']|["'"'"']$/,"",$2); print $2; exit}' "$INSTALL_DIR/.env" 2>/dev/null) || true
[[ -n "${_v:-}" ]] && VERSION="$_v"
fi
# Colors — use ANSI-C quoting ($'\033') so the variables hold real ESC bytes
# at assignment time. Single-quoted strings store the backslash literally,
# which breaks unquoted heredocs (cmd_help) that never re-interpret escapes.
# Guard on TTY + NO_COLOR so redirected / piped output stays clean.
# Per no-color.org, NO_COLOR disables colors when it is present (set to any
# value, including empty), so we check set-ness with ${NO_COLOR+x} — which
# expands to "x" whenever NO_COLOR is set and to "" only when truly unset —
# rather than ${NO_COLOR:-} which would treat NO_COLOR="" as unset.
if [[ -t 1 ]] && [[ -z "${NO_COLOR+x}" ]]; then
RED=$'\033[0;31m'
GREEN=$'\033[0;32m'
YELLOW=$'\033[1;33m'
BLUE=$'\033[0;34m'
CYAN=$'\033[0;36m'
NC=$'\033[0m'
else
RED=''
GREEN=''
YELLOW=''
BLUE=''
CYAN=''
NC=''
fi
#=============================================================================
# Helpers
#=============================================================================
log() { echo -e "${CYAN}[ods]${NC} $1" >&2; }
success() { echo -e "${GREEN}✓${NC} $1"; }
warn() { echo -e "${YELLOW}⚠${NC} $1" >&2; }
error() { echo -e "${RED}✗${NC} $1" >&2; exit 1; }
log_error() { echo -e "${RED}✗${NC} $1" >&2; }
# A failed remote-provider operation also says where to get help.
_remote_provider_fail() {
echo -e "${RED}✗${NC} $1" >&2
echo " Need help? Ask on the ODS Discord: https://discord.gg/4ntNp9MAwC" >&2
exit 1
}
# Why curl got no answer from the Dashboard API, from its exit status.
_remote_provider_transport_reason() {
case "$1" in
6|7) printf 'could not connect to the Dashboard API; check that ODS is running with: ods status' ;;
28) printf 'the Dashboard API did not answer in time; check: ods status' ;;
52|56) printf 'the connection closed before the Dashboard API answered; check: ods status' ;;
*) printf 'curl exit %s' "$1" ;;
esac
}
# Map cmd_list status string to a colour. Returns an empty string for unknown
# statuses so future state names don't break formatting.
_status_color() {
case "$1" in
enabled|always-on) echo "$GREEN" ;;
disabled|stopped) echo "$YELLOW" ;;
unhealthy|error) echo "$RED" ;;
*) echo "" ;;
esac
}
_json_escape() {
local s="${1-}"
s=${s//\\/\\\\}
s=${s//\"/\\\"}
s=${s//$'\b'/\\b}
s=${s//$'\f'/\\f}
s=${s//$'\n'/\\n}
s=${s//$'\r'/\\r}
s=${s//$'\t'/\\t}
printf '%s' "$s"
}
# Print a separator of repeated characters filling the given width.
# Usage: hr <width> [<char=─>]
hr() {
local w="${1:-10}" c="${2:-─}" out=''
printf -v out '%*s' "$w" ''
printf '%s' "${out// /$c}"
}
# Update or add a key=value in .env
_env_set() {
local key="$1" val="$2" file="$INSTALL_DIR/.env"
# The probe must use the same literal-prefix test as the awk update below:
# a regex here treats dots/brackets in the key as wildcards, so a key like
# FOO.BAR could "match" FOO_BAR=... and then be silently dropped by awk.
if awk -v k="$key" 'index($0, k "=") == 1 { found = 1 } END { exit !found }' "$file" 2>/dev/null; then
# Use awk to avoid sed delimiter collisions with values containing | / or =
awk -v k="$key" -v v="$val" '{
if (index($0, k "=") == 1) print k "=" v; else print
}' "$file" > "${file}.tmp" && cat "${file}.tmp" > "$file" && rm -f "${file}.tmp"
else
# Appending after a last line that has no newline would join the new
# assignment onto that line and corrupt both keys.
if [[ -s "$file" && -n "$(tail -c 1 "$file")" ]]; then
printf '\n' >> "$file"
fi
echo "${key}=${val}" >> "$file"
fi
}
_env_unset() {
local key="$1" file="$INSTALL_DIR/.env"
[[ -f "$file" ]] || return 0
awk -v k="$key" 'index($0, k "=") != 1 { print }' "$file" > "${file}.tmp" \
&& cat "${file}.tmp" > "$file" \
&& rm -f "${file}.tmp"
}
_env_get_raw() {
local key="$1" file="$INSTALL_DIR/.env"
[[ -f "$file" ]] || { echo ""; return 0; }
awk -v k="$key" '
index($0, k "=") == 1 { value = substr($0, length(k) + 2); found = 1 }
END { if (found) print value }
' "$file" 2>/dev/null | tr -d '\r' || true
}
_ensure_hermes_dashboard_session_token() {
[[ -f "$INSTALL_DIR/.env" ]] || return 0
[[ -n "$(_env_get_raw HERMES_DASHBOARD_SESSION_TOKEN)" ]] && return 0
local token
if command -v openssl >/dev/null 2>&1; then
token="$(openssl rand -hex 32)"
else
token="$(head -c 32 /dev/urandom | od -An -tx1 | tr -d ' \n')"
fi
[[ "$token" =~ ^[0-9a-f]{64}$ ]] \
|| error "Could not generate HERMES_DASHBOARD_SESSION_TOKEN"
_env_set "HERMES_DASHBOARD_SESSION_TOKEN" "$token"
}
_ods_cli_proxy_enabled() {
[[ -f "$INSTALL_DIR/extensions/services/ods-proxy/compose.yaml" ]] \
|| [[ -f "$INSTALL_DIR/data/user-extensions/ods-proxy/compose.yaml" ]]
}
# A BIND_ADDRESS other than loopback publishes Open WebUI beyond this machine,
# with or without the ODS proxy, so it needs the same sign-in enforcement.
_ods_cli_bind_is_network() {
local bind
bind="$(_env_get_raw BIND_ADDRESS)"
bind="${bind#\"}"; bind="${bind%\"}"; bind="${bind#\'}"; bind="${bind%\'}"
case "${bind:-127.0.0.1}" in
127.0.0.1|::1|\[::1\]|localhost) return 1 ;;
*) return 0 ;;
esac
}
_ods_cli_network_access_enabled() {
_ods_cli_proxy_enabled || _ods_cli_bind_is_network
}
_ods_cli_require_proxy_auth() {
[[ -f "$INSTALL_DIR/.env" ]] \
|| error "Cannot enable network access without $INSTALL_DIR/.env."
if [[ "$(_env_get_raw WEBUI_AUTH)" != "true" ]]; then
_env_set "WEBUI_AUTH" "true" \
|| error "Could not enforce WEBUI_AUTH=true before enabling network access."
log " Network access requires sign-in; set WEBUI_AUTH=true."
fi
export WEBUI_AUTH=true
}
_ods_cli_prepare_proxy_start() {
local -a compose_flags=("$@")
_ods_cli_require_proxy_auth
_compose_run_with_summary \
"Applying authenticated Open WebUI configuration" \
"${compose_flags[@]}" up -d --no-deps --force-recreate open-webui
}
_ods_cli_bootstrap_status() {
local status_file="$INSTALL_DIR/data/bootstrap-status.json"
[[ -f "$status_file" ]] || return 0
grep -o '"status"[[:space:]]*:[[:space:]]*"[^"]*"' "$status_file" \
| sed -n '1p' \
| sed 's/.*"status"[[:space:]]*:[[:space:]]*"//' \
| sed 's/"//' \
|| true
}
_ods_cli_bootstrap_status_field() {
local key="$1" status_file="$INSTALL_DIR/data/bootstrap-status.json"
[[ -f "$status_file" ]] || return 0
grep -o "\"${key}\"[[:space:]]*:[[:space:]]*\"[^\"]*\"" "$status_file" \
| sed -n '1p' \
| sed "s/.*\"${key}\"[[:space:]]*:[[:space:]]*\"//" \
| sed 's/"//' \
|| true
}
_ods_cli_bootstrap_status_number() {
local key="$1" status_file="$INSTALL_DIR/data/bootstrap-status.json"
[[ -f "$status_file" ]] || return 0
grep -o "\"${key}\"[[:space:]]*:[[:space:]]*[0-9][0-9.]*" "$status_file" \
| sed -n '1p' \
| sed "s/.*:[[:space:]]*//" \
|| true
}
_ods_cli_file_size() {
local path="$1"
if stat -c %s "$path" 2>/dev/null; then
return 0
fi
stat -f %z "$path" 2>/dev/null || echo 0
}
_ods_cli_bootstrap_upgrade_process_running() {
local model="$1" args
[[ -n "$model" ]] || return 1
while IFS= read -r args; do
case "$args" in
*"/scripts/bootstrap-upgrade.sh"*" $model "*|*" scripts/bootstrap-upgrade.sh"*" $model "*)
return 0
;;
esac
done < <(ps -eo args= 2>/dev/null || true)
return 1
}
_ods_cli_bootstrap_active_status_settled() {
local status="$1"
case "$status" in
downloading|starting|verifying|swapping) ;;
*) return 1 ;;
esac
local model env_model model_path expected_bytes actual_bytes
model="$(_ods_cli_bootstrap_status_field model)"
[[ -n "$model" ]] || return 1
if _ods_cli_bootstrap_upgrade_process_running "$model"; then
return 1
fi
env_model="$(_env_get_raw GGUF_FILE)"
[[ "$env_model" == "$model" ]] || return 1
model_path="$INSTALL_DIR/data/models/$model"
[[ -f "$model_path" ]] || return 1
expected_bytes="$(_ods_cli_bootstrap_status_number bytesTotal)"
if [[ "$expected_bytes" =~ ^[0-9]+$ ]] && (( expected_bytes > 0 )); then
actual_bytes="$(_ods_cli_file_size "$model_path")"
[[ "$actual_bytes" =~ ^[0-9]+$ ]] || return 1
(( actual_bytes >= expected_bytes )) || return 1
fi
return 0
}
_ods_cli_bootstrap_download_near_swap() {
local model percent percent_int downloaded total remaining threshold
model="$(_ods_cli_bootstrap_status_field model)"
[[ -n "$model" ]] || return 1
_ods_cli_bootstrap_upgrade_process_running "$model" || return 1
threshold="${ODS_CLI_BOOTSTRAP_COMPOSE_DOWNLOAD_WAIT_BYTES:-1073741824}"
if ! [[ "$threshold" =~ ^[0-9]+$ ]]; then
threshold=1073741824
fi
downloaded="$(_ods_cli_bootstrap_status_number bytesDownloaded)"
total="$(_ods_cli_bootstrap_status_number bytesTotal)"
if [[ "$downloaded" =~ ^[0-9]+$ && "$total" =~ ^[0-9]+$ ]] && (( total > 0 )); then
remaining=$(( total - downloaded ))
(( remaining < 0 )) && remaining=0
(( remaining <= threshold )) && return 0
fi
percent="$(_ods_cli_bootstrap_status_number percent)"
percent_int="${percent%%.*}"
if [[ "$percent_int" =~ ^[0-9]+$ ]] && (( percent_int >= 95 )); then
return 0
fi
return 1
}
_ods_cli_wait_for_bootstrap_compose_safe() {
local action="${1:-service operation}"
local status_file="$INSTALL_DIR/data/bootstrap-status.json"
[[ -f "$status_file" ]] || return 0
local max_wait="${ODS_CLI_BOOTSTRAP_COMPOSE_WAIT_SECONDS:-1800}"
local interval="${ODS_CLI_BOOTSTRAP_COMPOSE_WAIT_INTERVAL:-5}"
if ! [[ "$max_wait" =~ ^[0-9]+$ ]] || (( max_wait < 0 )); then
max_wait=1800
fi
if ! [[ "$interval" =~ ^[0-9]+$ ]] || (( interval < 1 )); then
interval=5
fi
local waited=0 announced=false status=""
while true; do
status="$(_ods_cli_bootstrap_status)"
case "$status" in
downloading)
if _ods_cli_bootstrap_active_status_settled "$status"; then
if [[ "$announced" == "true" ]]; then
log " Model Upgrade: stale $status status already settled; continuing with $action"
else
warn "Model upgrade status is stale ($status) but the full model is already configured; continuing with $action."
fi
return 0
fi
if ! _ods_cli_bootstrap_download_near_swap; then
log " Model Upgrade: downloading in background; continuing with $action before hot-swap begins"
return 0
fi
if [[ "$announced" == "false" ]]; then
log " Model Upgrade: download nearly complete; waiting before $action touches llama-server"
announced=true
fi
if (( waited >= max_wait )); then
warn "Model upgrade is still $status after ${max_wait}s; refusing to run $action against an active hot-swap."
return 1
fi
sleep "$interval"
waited=$(( waited + interval ))
;;
starting|verifying|swapping)
if _ods_cli_bootstrap_active_status_settled "$status"; then
if [[ "$announced" == "true" ]]; then
log " Model Upgrade: stale $status status already settled; continuing with $action"
else
warn "Model upgrade status is stale ($status) but the full model is already configured; continuing with $action."
fi
return 0
fi
if [[ "$announced" == "false" ]]; then
log " Model Upgrade: $status; waiting before $action touches llama-server"
announced=true
fi
if (( waited >= max_wait )); then
warn "Model upgrade is still $status after ${max_wait}s; refusing to run $action against an active hot-swap."
return 1
fi
sleep "$interval"
waited=$(( waited + interval ))
;;
*)
if [[ "$announced" == "true" ]]; then
log " Model Upgrade: ${status:-idle}; continuing with $action"
fi
return 0
;;
esac
done
}
_ods_cli_reload_model_env() {
# A background bootstrap promotion can rewrite these values while a start
# or restart command is waiting. Clear the process snapshot first so a key
# removed from .env cannot keep overriding Docker Compose.
unset GGUF_FILE LLM_MODEL MAX_CONTEXT CTX_SIZE
load_env
}
_get_host_logical_cpus() {
local cores
# nproc and /proc/cpuinfo are Linux-only; on macOS both are absent, so the
# old chain always fell through to 1 and starved the CPU budget whenever
# Docker's own NCPU was unavailable. Probe sysctl (macOS/BSD) between them.
cores=$(nproc 2>/dev/null \
|| sysctl -n hw.logicalcpu 2>/dev/null \
|| grep -c '^processor' /proc/cpuinfo 2>/dev/null \
|| echo "1")
if [[ "$cores" =~ ^[0-9]+$ ]] && [[ "$cores" -gt 0 ]]; then
echo "$cores"
else
echo "1"
fi
}
_get_docker_available_cpus() {
local cores=""
if command -v docker &>/dev/null; then
cores=$(docker info --format '{{.NCPU}}' 2>/dev/null || true)
cores="${cores//[!0-9]/}"
fi
if [[ "$cores" =~ ^[0-9]+$ ]] && [[ "$cores" -gt 0 ]]; then
echo "$cores"
return 0
fi
_get_host_logical_cpus
}
_calculate_llama_cpu_budget() {
local backend="${1:-cpu}"
local available="${2:-$(_get_docker_available_cpus)}"
local desired_limit=8
local desired_reservation=1
case "$backend" in
amd)
desired_limit=16
desired_reservation=4
;;
nvidia|intel|sycl)
desired_limit=16
desired_reservation=2
;;
apple)
desired_limit=8
desired_reservation=2
;;
esac
if ! [[ "$available" =~ ^[0-9]+$ ]] || [[ "$available" -lt 1 ]]; then
available=1
fi
local limit="$desired_limit"
local reservation="$desired_reservation"
[[ "$available" -lt "$limit" ]] && limit="$available"
[[ "$reservation" -gt "$limit" ]] && reservation="$limit"
echo "$limit $reservation $available"
}
_select_auto_cpu_value() {
local existing="$1" detected="$2"
if [[ "$existing" =~ ^[0-9]+([.][0-9]+)?$ ]] && LC_ALL=C awk "BEGIN { exit !($existing > 0 && $existing <= $detected) }"; then
echo "$existing"
else
echo "$detected"
fi
}
_cap_cpu_value() {
local desired="$1" ceiling="$2"
LC_ALL=C awk -v desired="$desired" -v ceiling="$ceiling" '
BEGIN {
if (ceiling <= 0) ceiling = 1
value = desired
if (value > ceiling) value = ceiling
if (value < 0.01) value = 0.01
printf "%.1f", value
}'
}
_ensure_service_cpu_pair() {
local available="$1" name="$2" desired_limit="$3" desired_reservation="$4"
local limit_key="${name}_CPU_LIMIT"
local reservation_key="${name}_CPU_RESERVATION"
local detected_limit detected_reservation current_limit current_reservation final_limit final_reservation
detected_limit="$(_cap_cpu_value "$desired_limit" "$available")"
current_limit="$(_env_get_raw "$limit_key")"
final_limit="$(_select_auto_cpu_value "$current_limit" "$detected_limit")"
detected_reservation="$(_cap_cpu_value "$desired_reservation" "$final_limit")"
current_reservation="$(_env_get_raw "$reservation_key")"
final_reservation="$(_select_auto_cpu_value "$current_reservation" "$detected_reservation")"
if LC_ALL=C awk "BEGIN { exit !($final_reservation > $final_limit) }"; then
final_reservation="$final_limit"
fi
if [[ "$current_limit" != "$final_limit" ]]; then
_env_set "$limit_key" "$final_limit"
SERVICE_CPU_BUDGET_CHANGED=true
fi
if [[ "$current_reservation" != "$final_reservation" ]]; then
_env_set "$reservation_key" "$final_reservation"
SERVICE_CPU_BUDGET_CHANGED=true
fi
}
ensure_llama_cpu_budget() {
local env_file="$INSTALL_DIR/.env"
[[ -f "$env_file" ]] || return 0
local backend
backend="$(_env_get_raw "GPU_BACKEND")"
backend=$(echo "${backend:-cpu}" | tr '[:upper:]' '[:lower:]')
[[ "$backend" == "none" ]] && backend="cpu"
local limit_raw reservation_raw available
read -r limit_raw reservation_raw available <<< "$(_calculate_llama_cpu_budget "$backend")"
local detected_limit="${limit_raw}.0"
local detected_reservation="${reservation_raw}.0"
local current_limit current_reservation final_limit final_reservation
current_limit="$(_env_get_raw "LLAMA_CPU_LIMIT")"
current_reservation="$(_env_get_raw "LLAMA_CPU_RESERVATION")"
final_limit="$(_select_auto_cpu_value "$current_limit" "$detected_limit")"
final_reservation="$(_select_auto_cpu_value "$current_reservation" "$detected_reservation")"
if LC_ALL=C awk "BEGIN { exit !($final_reservation > $final_limit) }"; then
final_reservation="$final_limit"
fi
local changed=false
if [[ "$current_limit" != "$final_limit" ]]; then
_env_set "LLAMA_CPU_LIMIT" "$final_limit"
changed=true
fi
if [[ "$current_reservation" != "$final_reservation" ]]; then
_env_set "LLAMA_CPU_RESERVATION" "$final_reservation"
changed=true
fi
if [[ "$changed" == "true" ]]; then
log "Auto-adjusted llama-server CPU budget: limit=${final_limit}, reservation=${final_reservation} (Docker CPUs: ${available})"
fi
SERVICE_CPU_BUDGET_CHANGED=false
_ensure_service_cpu_pair "$available" "TTS" "8.0" "2.0"
_ensure_service_cpu_pair "$available" "WHISPER" "4.0" "1.0"
_ensure_service_cpu_pair "$available" "HERMES" "4.0" "0.5"
_ensure_service_cpu_pair "$available" "COMFYUI" "16.0" "2.0"
if [[ "$SERVICE_CPU_BUDGET_CHANGED" == "true" ]]; then
log "Auto-adjusted bundled service CPU budgets (Docker CPUs: ${available})"
fi
unset SERVICE_CPU_BUDGET_CHANGED
}
check_install() {
if [[ ! -d "$INSTALL_DIR" ]]; then
error "ODS not found at $INSTALL_DIR. Set ODS_HOME or run installer first."
fi
if [[ ! -f "$INSTALL_DIR/docker-compose.base.yml" ]]; then
# Backward compat: check for monolithic docker-compose.yml
if [[ ! -f "$INSTALL_DIR/docker-compose.yml" ]]; then
error "docker-compose.base.yml not found in $INSTALL_DIR"
fi
fi
}
# Extract the major component of a semver string (e.g. "2.1.0" → "2").
# Used only for counting major-version jumps; not for ordering comparisons.
_semver_major() {
echo "${1%%.*}"
}
# Full 3-component semver less-than: returns 0 (true) if v1 < v2.
# Strips any leading "v" and ignores pre-release suffixes.
_semver_lt() {
local v1="${1#v}" v2="${2#v}"
local IFS='.'
local -a a=($v1) b=($v2)
local i
for i in 0 1 2; do
local n1="${a[$i]:-0}" n2="${b[$i]:-0}"
n1="${n1%%[!0-9]*}" n2="${n2%%[!0-9]*}"
if (( n1 < n2 )); then return 0; fi
if (( n1 > n2 )); then return 1; fi
done
return 1 # equal → not less-than
}
# Read a top-level or nested string field from a JSON file.
# Usage: _manifest_field <file> <field> e.g. _manifest_field manifest.json ods_version
# Logs a warning to stderr on parse failure rather than silently returning empty.
_manifest_field() {
local file="$1" field="$2" value=""
if [[ ! -f "$file" ]]; then
warn "_manifest_field: file not found: ${file}" >&2
return 1
fi
if command -v jq &>/dev/null; then
if ! value=$(jq -r --arg f "$field" '.[$f] // .release.version // empty' "$file"); then
warn "_manifest_field: jq failed to parse ${file}" >&2
fi
fi
if [[ -z "$value" ]] && command -v python3 &>/dev/null; then
# Pass file and field as argv to avoid shell-injection via string interpolation.
if ! value=$(python3 -c '
import json, sys
try:
d = json.load(open(sys.argv[1]))
f = sys.argv[2]
print(d.get(f) or d.get("release", {}).get("version") or "")
except Exception as e:
sys.stderr.write("_manifest_field: " + str(e) + "\n")
' "$file" "$field"); then
warn "_manifest_field: python3 failed to parse ${file}" >&2
fi
fi
echo "$value"
}
# Version compatibility check for ods update.
# Returns 0 (ok) or 1 (user aborted / hard-blocked).
# Sets _COMPAT_INSTALLED_VER and _COMPAT_TARGET_VER as side-effects.
#
# Version source precedence (single source of truth policy):
# installed: ODS_VERSION in .env > .version file > manifest.json ods_version
# target: manifest.json ods_version (post-pull reflects the incoming release)
_check_version_compat() {
local force="${1:-false}"
# 1. Installed version
# `|| true` preserves the tolerant fallback semantics required by
# the maintainer audit on PR #998: under `set -euo pipefail`,
# a fresh install whose .env lacks ODS_VERSION must fall back
# to .version / manifest.json (handled below), not exit out of
# the surrounding command. Landed on main via #1008.
_COMPAT_INSTALLED_VER=$(grep '^ODS_VERSION=' "$INSTALL_DIR/.env" 2>/dev/null \
| sed -n '1p' | cut -d= -f2 | tr -d '[:space:]' || true)
# Fall back to .version file (written by ods-update.sh / PR #349 convention)
if [[ -z "$_COMPAT_INSTALLED_VER" && -f "$INSTALL_DIR/.version" ]]; then
_COMPAT_INSTALLED_VER=$(jq -r '.version // empty' "$INSTALL_DIR/.version" 2>/dev/null \
|| grep -o '"version"[[:space:]]*:[[:space:]]*"[^"]*"' \
"$INSTALL_DIR/.version" 2>/dev/null | cut -d'"' -f4 \
|| true)
fi
if [[ -z "$_COMPAT_INSTALLED_VER" && -f "$INSTALL_DIR/manifest.json" ]]; then
_COMPAT_INSTALLED_VER=$(_manifest_field "$INSTALL_DIR/manifest.json" "ods_version")
fi
[[ -z "$_COMPAT_INSTALLED_VER" ]] && _COMPAT_INSTALLED_VER="$VERSION"
# 2. Target version — from manifest.json (reflects the incoming release after pull)
_COMPAT_TARGET_VER=""
if [[ -f "$INSTALL_DIR/manifest.json" ]]; then
_COMPAT_TARGET_VER=$(_manifest_field "$INSTALL_DIR/manifest.json" "ods_version")
fi
# 3. min_compatible_ods_version — read via _manifest_field to avoid 2>/dev/null + injection
local min_compat_ver=""
if [[ -f "$INSTALL_DIR/manifest.json" ]]; then
min_compat_ver=$(_manifest_field "$INSTALL_DIR/manifest.json" "min_compatible_ods_version")
fi
# Skip checks if we can't determine versions
if [[ -z "$_COMPAT_INSTALLED_VER" || -z "$_COMPAT_TARGET_VER" ]]; then
return 0
fi
# Skip if installed == target (no actual update)
[[ "$_COMPAT_INSTALLED_VER" == "$_COMPAT_TARGET_VER" ]] && return 0
local cur_major new_major
cur_major=$(_semver_major "$_COMPAT_INSTALLED_VER")
new_major=$(_semver_major "$_COMPAT_TARGET_VER")
# major_jump may be negative (downgrade); use arithmetic not regex for sign-aware logic
local major_jump=$(( new_major - cur_major ))
# 4. Downgrade detection — warn and confirm before proceeding
if (( major_jump < 0 )); then
echo ""
echo -e "${YELLOW}┌──────────────────────────────────────────────────────────┐${NC}"
echo -e "${YELLOW}│ Downgrade detected │${NC}"
echo -e "${YELLOW}└──────────────────────────────────────────────────────────┘${NC}"
echo ""
warn "Installed : v${_COMPAT_INSTALLED_VER} (major ${cur_major})"
warn "Target : v${_COMPAT_TARGET_VER} (major ${new_major})"
echo ""
log "Downgrading may corrupt data or break your installation."
log "Consider restoring a backup instead: ods rollback"
echo ""
if [[ "$force" == "true" ]]; then
warn "--force specified: proceeding with downgrade."
else
read -p " Proceed with downgrade? [y/N] " -n 1 -r || REPLY=""
echo ""
if [[ ! $REPLY =~ ^[Yy]$ ]]; then
log "Update cancelled."
return 1
fi
fi
echo ""
fi
# 5. Hard block: installed version is below min_compatible_ods_version.
# Uses full 3-component comparison — major-only was insufficient
# (e.g. 1.2.0 vs min 1.5.0 both have major 1 but 1.2.0 < 1.5.0).
if [[ -n "$min_compat_ver" ]] && _semver_lt "$_COMPAT_INSTALLED_VER" "$min_compat_ver"; then
echo ""
echo -e "${RED}╔══════════════════════════════════════════════════════════╗${NC}"
echo -e "${RED}║ UPGRADE BLOCKED — installed version is too old ║${NC}"
echo -e "${RED}╚══════════════════════════════════════════════════════════╝${NC}"
echo ""
warn "Installed : v${_COMPAT_INSTALLED_VER}"
warn "Target : v${_COMPAT_TARGET_VER}"
warn "Minimum : v${min_compat_ver} (min_compatible_ods_version)"
echo ""
log "Your installation is below the minimum supported upgrade version."
log "Upgrade incrementally: first update to v${min_compat_ver}, then re-run."
log "See CHANGELOG.md for migration steps."
echo ""
if [[ "$force" == "true" ]]; then
warn "--force specified: proceeding despite compatibility block. DATA LOSS RISK."
else
log "Use 'ods update --force' to override (not recommended)."
return 1
fi
fi
# 6. Warn: major version jump > 1
if (( major_jump > 1 )); then
echo ""
echo -e "${YELLOW}┌──────────────────────────────────────────────────────────┐${NC}"
echo -e "${YELLOW}│ Major version jump detected │${NC}"
echo -e "${YELLOW}└──────────────────────────────────────────────────────────┘${NC}"
echo ""
warn "Installed : v${_COMPAT_INSTALLED_VER} (major ${cur_major})"
warn "Target : v${_COMPAT_TARGET_VER} (major ${new_major})"
warn "Jump : ${major_jump} major versions"
echo ""
log "Skipping more than 1 major version may introduce breaking changes."
log "Recommended: upgrade step-by-step (v${cur_major} → v$((cur_major+1)) → … → v${new_major})."
log "Review CHANGELOG.md for each major version before proceeding."
echo ""
if [[ "$force" == "true" ]]; then
warn "--force specified: skipping confirmation."
else
read -p " Proceed with v${_COMPAT_INSTALLED_VER} → v${_COMPAT_TARGET_VER} anyway? [y/N] " -n 1 -r || REPLY=""
echo ""
if [[ ! $REPLY =~ ^[Yy]$ ]]; then
log "Update cancelled."
return 1
fi
warn "Proceeding — back up your data first: ods backup"
fi
echo ""
fi
return 0
}
#=============================================================================
# Safe .env loading (no eval; use lib/safe-env.sh)
#=============================================================================
[[ -f "$SCRIPT_DIR/lib/safe-env.sh" ]] && . "$SCRIPT_DIR/lib/safe-env.sh"
load_env() {
[[ -f "$INSTALL_DIR/.env" ]] || { warn ".env not found at $INSTALL_DIR — run installer first"; return 1; }
load_env_file "$INSTALL_DIR/.env"
}
#=============================================================================
# Service Registry
#=============================================================================
. "$SCRIPT_DIR/lib/service-registry.sh"
# Resolve a user-provided service name to the compose service ID that serves
# it on this install. With LLM_BACKEND=vllm the vLLM engine serves the model
# and the in-stack llama-server is profiled out (docker-compose.vllm.yml).
# Naming llama-server to Compose would enable its profile and start a second
# engine on the GPU, so "llm" and "llama-server" mean vllm-server there.
resolve_service() {
local resolved backend="${LLM_BACKEND:-}"
resolved=$(sr_resolve "$1")
if [[ "$resolved" == "llama-server" && "${backend,,}" == "vllm" ]]; then
resolved="vllm-server"
fi
echo "$resolved"
}
# Regenerate .compose-flags after enable/disable
_regenerate_compose_flags() {
if [[ -x "$INSTALL_DIR/scripts/resolve-compose-stack.sh" ]]; then
# --gpu-count gates the multigpu-{backend}.yml overlay; without it,
# toggling any extension would silently strip multi-GPU plumbing
# from the persisted cache.
# Capture the resolver's stderr instead of discarding it: it reports
# actionable causes (e.g. missing PyYAML) that would otherwise only
# surface commands later as compose's "no configuration file provided".
local resolver_err=""
if ! resolver_err=$("$INSTALL_DIR/scripts/resolve-compose-stack.sh" \
--script-dir "$INSTALL_DIR" --tier "${TIER:-1}" --gpu-backend "${GPU_BACKEND:-nvidia}" \
--gpu-count "${GPU_COUNT:-1}" --ods-mode "${ODS_MODE:-local}" \
2>&1 > "$INSTALL_DIR/.compose-flags"); then
rm -f "$INSTALL_DIR/.compose-flags"
warn "Could not regenerate the compose stack cache. 'ods start' will fail until this is resolved:"
[[ -n "$resolver_err" ]] && printf '%s\n' "$resolver_err" >&2
elif [[ "$resolver_err" == *WARNING:* ]]; then
# The stack resolved, but refused extension files (and anything
# that depends on them) were left out. Say which, and why.
printf '%s\n' "$resolver_err" | grep '^WARNING:' >&2 || true
fi
else
rm -f "$INSTALL_DIR/.compose-flags"
fi
}
# Run a lifecycle hook for a service (reads manifest directly via Python)
_run_hook() {
local service_id="$1" hook_name="$2"
local ext_dir="$INSTALL_DIR/extensions/services/$service_id"
# Also check user-extensions
[[ -d "$ext_dir" ]] || ext_dir="$INSTALL_DIR/data/user-extensions/$service_id"
[[ -d "$ext_dir" ]] || return 0
local hook_path
hook_path=$(python3 - "$ext_dir" "$hook_name" <<'PYEOF'
import yaml, sys
from pathlib import Path
ext_dir = Path(sys.argv[1])
hook_name = sys.argv[2]
manifest_path = None
for name in ("manifest.yaml", "manifest.yml"):
candidate = ext_dir / name
if candidate.exists():
manifest_path = candidate
break
if manifest_path is None:
sys.exit(0)
with open(manifest_path) as f:
m = yaml.safe_load(f)
if not isinstance(m, dict):
sys.exit(0)
service = m.get("service", {})
if not isinstance(service, dict):
sys.exit(0)
# Check hooks map first
hooks = service.get("hooks", {})
hook_script = ""
if isinstance(hooks, dict):
hook_script = hooks.get(hook_name, "")
# Fallback: setup_hook -> post_install only
if not hook_script and hook_name == "post_install":
hook_script = service.get("setup_hook", "")
if not hook_script:
sys.exit(0)
# Validate path containment
hook_path = (ext_dir / hook_script).resolve()
try:
hook_path.relative_to(ext_dir.resolve())
except ValueError:
print(f"ERROR: hook path escapes extension directory: {hook_script}", file=sys.stderr)
sys.exit(1)
if not hook_path.is_file():
sys.exit(0)
print(str(hook_path))
PYEOF
) || return 0
[[ -z "$hook_path" || ! -f "$hook_path" ]] && return 0
log "Running $hook_name hook for $service_id..."
SERVICE_ID="$service_id" \
SERVICE_PORT="${SERVICE_PORTS[$service_id]:-0}" \
SERVICE_DATA_DIR="$INSTALL_DIR/data/$service_id" \
ODS_VERSION="$VERSION" \
GPU_BACKEND="${GPU_BACKEND:-}" \
HOOK_NAME="$hook_name" \
bash "$hook_path" "$INSTALL_DIR" "${GPU_BACKEND:-}" \
|| warn "$hook_name hook failed for $service_id (non-fatal)"
}
# Build full compose flags: base + GPU overlay + enabled extensions
get_compose_flags() {
_ensure_hermes_dashboard_session_token
# Fast path: use saved flags from installer if available
if [[ -f "$INSTALL_DIR/.compose-flags" ]]; then
local cached
cached=$(< "$INSTALL_DIR/.compose-flags")
if [[ "$cached" == -f\ * ]]; then
# Validate that every referenced compose file still exists.
# Protects against renames across upgrades (e.g. multigpu.yml →
# multigpu-nvidia.yml) where the cache would otherwise hand docker
# compose a path that no longer resolves.
local stale=0 prev="" tok
for tok in $cached; do
if [[ "$prev" == "-f" ]]; then
if [[ "$tok" = /* ]]; then
[[ -f "$tok" ]] || { stale=1; break; }
else
[[ -f "$INSTALL_DIR/$tok" ]] || { stale=1; break; }
fi
fi
prev="$tok"
done
local _ods_mode="${ODS_MODE:-local}"
# An ODS-managed llama-server outside the stack (Windows Portal).
local _host_native_active="false"
[[ -n "${NATIVE_LLM_BASE_URL:-}" && "$_ods_mode" != "cloud" ]] && _host_native_active="true"
if [[ "$_ods_mode" == "cloud" ]] && \
{ [[ "$cached" == *"docker-compose.cpu.yml"* ]] || [[ "$cached" == *"compose.local.yaml"* ]] || [[ "$cached" != *"docker-compose.cloud.yml"* ]]; }; then
stale=1
fi
if [[ "$_host_native_active" == "true" ]] && \
{ [[ "$cached" == *"compose.local.yaml"* ]] || [[ "$cached" == *"docker-compose.amd.yml"* ]] || [[ "$cached" == *"docker-compose.cloud.yml"* ]] || [[ "$cached" != *"docker-compose.host-native-llm.yml"* ]]; }; then
stale=1
fi
if [[ "$_host_native_active" != "true" ]] && [[ "$cached" == *"docker-compose.host-native-llm.yml"* ]]; then
stale=1
fi
if [[ "$_ods_mode" != "cloud" ]] && [[ "$cached" == *"docker-compose.cloud.yml"* ]]; then
stale=1
fi
# LLM_BACKEND=vllm swaps the in-stack llama-server for the vLLM
# engine overlay, which (like a host-native route) leaves out the
# compose.local.yaml waits on llama-server. A cache from the other
# route starts the wrong engine.
local _llm_backend="${LLM_BACKEND:-}"
if [[ "${_llm_backend,,}" == "vllm" ]]; then
if [[ "$cached" != *"docker-compose.vllm.yml"* || "$cached" == *"compose.local.yaml"* ]]; then
stale=1
fi
elif [[ "$cached" == *"docker-compose.vllm.yml"* ]]; then
stale=1
fi
# The retired Lemonade overlay can outlive an update that kept
# the old file on disk; the stack must be resolved again.
if [[ "$cached" == *"docker-compose.lemonade-external.yml"* ]]; then
stale=1
fi
# Registered model stores (scripts/register-model-store.py) and the
# active store's /models mount come after install. A cache from
# before them would start llama-server on the default directory,
# where the selected model is missing, and Compose then leaves
# LiteLLM and the Dashboard unstarted.
if [[ -f "$INSTALL_DIR/.model-stores.compose.json" \
&& "$cached" != *".model-stores.compose.json"* ]]; then
stale=1
fi
# docs/PROFILES.md has owners add docker-compose.override.yml to
# turn services off; the resolver appends it when it exists.
if [[ -f "$INSTALL_DIR/docker-compose.override.yml" \
&& "$cached" != *"docker-compose.override.yml"* ]]; then
stale=1
fi
if [[ "${ODS_ACTIVE_MODEL_STORE:-default}" != "default" ]]; then
[[ "$cached" == *".active-model-store.compose.json"* ]] || stale=1
elif [[ "$cached" == *".active-model-store.compose.json"* ]]; then
stale=1
fi
# The AMD image follows AMD_INFERENCE_BACKEND (vulkan or rocm).
if [[ "$cached" == *"docker-compose.amd.yml"* ]]; then
if [[ "${AMD_INFERENCE_BACKEND:-vulkan}" == "rocm" ]]; then
[[ "$cached" == *"docker-compose.amd-rocm.yml"* ]] || stale=1
else
[[ "$cached" != *"docker-compose.amd-rocm.yml"* ]] || stale=1
fi
fi
if [[ "$stale" == "0" ]]; then
if [[ "$cached" == *user-extensions* || -d "$INSTALL_DIR/data/user-extensions" ]]; then
local policy="$INSTALL_DIR/scripts/compose-cache-policy.py"
[[ -f "$policy" ]] || { warn "Saved extensions need the Compose security validator; repair ODS."; return 1; }
local policy_python="${ODS_PYTHON_CMD:-python3}"
if [[ -f "$INSTALL_DIR/lib/python-cmd.sh" ]]; then
policy_python="$(. "$INSTALL_DIR/lib/python-cmd.sh"; ods_detect_python_cmd_with_module yaml)" || return 1
fi
"$policy_python" "$policy" --install-dir "$INSTALL_DIR" --flags="$cached" --format flags
return $?
fi
echo "$cached"
return
fi
fi
# Stale or corrupt — remove and fall through to dynamic resolution
rm -f "$INSTALL_DIR/.compose-flags"
fi
# Fallback: resolve dynamically
local base_flags
if [[ -x "$INSTALL_DIR/scripts/resolve-compose-stack.sh" ]]; then
# Resolver handles base + GPU overlay + extension compose files.
# --gpu-count gates the multigpu-{backend}.yml overlay — without it,
# this fallback path resolves to a single-GPU stack on multi-GPU hosts.
base_flags=$("$INSTALL_DIR/scripts/resolve-compose-stack.sh" \
--script-dir "$INSTALL_DIR" --tier "${TIER:-1}" --gpu-backend "${GPU_BACKEND:-nvidia}" \
--gpu-count "${GPU_COUNT:-1}" --ods-mode "${ODS_MODE:-local}")
echo "$base_flags"
elif [[ -f "$INSTALL_DIR/docker-compose.base.yml" ]]; then
base_flags="-f docker-compose.base.yml"
local ext_flags
ext_flags=$(sr_compose_flags)
echo "$base_flags $ext_flags"
else
base_flags="-f docker-compose.yml"
local ext_flags
ext_flags=$(sr_compose_flags)
echo "$base_flags $ext_flags"
fi
}
# Run `docker compose <args...>` with a compact summary on success and a
# surfaced error banner on failure.
#
# Usage: _compose_run_with_summary <verb> <compose_args...>
# <verb> Human-readable gerund phrase, e.g. "Restarting all services"
# <compose_args> Everything that goes after `docker compose`, including
# any `-f` flags resolved by get_compose_flags.
#
# Behavior:
# - Runs `docker compose --progress quiet <compose_args>`, capturing
# stdout+stderr to a mktemp log file.
# - On success: prints "<verb> — done" and removes the log file.
# - On failure: prints an error banner, surfaces up to 20 lines matching
# /error|unhealthy|failed|dependency/, preserves the full
# log file for inspection, and returns the compose exit
# code so the caller (under `set -e`) aborts with it.
#
# The summary grep pipeline can legitimately produce zero matches if the
# failing compose output has no error-keyword hits. `upstream/main` today
# runs under `set -e` only (no `pipefail`), so grep's exit 1 is absorbed
# by the pipeline's final-stage exit and the function continues to the
# log-path surface below. When pipefail is eventually adopted (sibling
# nounset/exit-code audit change), grep's no-match or a SIGPIPE from
# `head -20` on >20 matches would abort this function before the caller
# sees the compose log path or the compose exit code. `|| warn "..."`
# is the project-blessed form (per CLAUDE.md) for "tolerate this specific
# non-match and log why the summary is empty" — it costs nothing today
# and keeps the function correct under future pipefail.
_compose_run_with_summary() {
local _verb="$1"; shift
log "${_verb}..."
_check_docker_access
local _compose_log
_compose_log=$(mktemp)
trap 'rm -f "$_compose_log"' INT TERM
local _is_compose_up=false _is_compose_pull=false _arg
for _arg in "$@"; do
[[ "$_arg" == "up" ]] && _is_compose_up=true
[[ "$_arg" == "pull" ]] && _is_compose_pull=true
done
_compose_remove_conflicting_ods_containers() {
local _log_path="$1"
local _removed=false
local _name _id
while read -r _name _id; do
[[ -n "${_name:-}" && -n "${_id:-}" ]] || continue
case "$_name" in
/ods-*|ods-*)
docker rm -f "$_id" >>"$_log_path" 2>&1 || return 1
_removed=true
;;
*)
warn "Refusing to remove conflicting non-ODS container $_name."
return 1
;;
esac
done < <(sed -nE 's/.*container name "([^"]+)".*already in use by container "([0-9a-fA-F]+)".*/\1 \2/p' "$_log_path" | awk '!seen[$0]++')
$_removed
}
local _rc=0
docker compose --progress quiet "$@" >"$_compose_log" 2>&1 || _rc=$?
local _pull_max_attempts="${ODS_COMPOSE_PULL_RETRY_ATTEMPTS:-3}"
if ! [[ "$_pull_max_attempts" =~ ^[0-9]+$ ]] || (( _pull_max_attempts < 1 )); then
_pull_max_attempts=3
fi
local _pull_attempt=1
local _pull_retries=$(( _pull_max_attempts - 1 ))
while (( _rc != 0 )) && $_is_compose_pull \
&& (( _pull_attempt < _pull_max_attempts )) \
&& grep -Eiq 'context deadline exceeded|i/o timeout|TLS handshake timeout|connection reset by peer|connection timed out|temporary failure|network is unreachable|net/http: request canceled|unexpected EOF' "$_compose_log"; do
local _pull_delay
case "$_pull_attempt" in
1) _pull_delay="${ODS_COMPOSE_PULL_RETRY_DELAY_1:-5}" ;;
2) _pull_delay="${ODS_COMPOSE_PULL_RETRY_DELAY_2:-15}" ;;
*) _pull_delay="${ODS_COMPOSE_PULL_RETRY_DELAY_N:-30}" ;;
esac
warn "Docker registry pull hit a transient network error; retrying (${_pull_attempt}/${_pull_retries})."
sleep "$_pull_delay"
_pull_attempt=$(( _pull_attempt + 1 ))
: >"$_compose_log"
_rc=0
docker compose --progress quiet "$@" >"$_compose_log" 2>&1 || _rc=$?
done
if (( _rc != 0 )) && $_is_compose_up \
&& grep -Eiq 'port is already allocated|Bind for .* failed: port is already allocated' "$_compose_log"; then
warn "Docker reported a port allocation race; waiting briefly and retrying once."
sleep "${ODS_COMPOSE_PORT_RETRY_DELAY:-10}"
: >"$_compose_log"
_rc=0
docker compose --progress quiet "$@" >"$_compose_log" 2>&1 || _rc=$?
fi
local _startup_max_attempts="${ODS_COMPOSE_STARTUP_RETRY_ATTEMPTS:-3}"
if ! [[ "$_startup_max_attempts" =~ ^[0-9]+$ ]] || (( _startup_max_attempts < 1 )); then
_startup_max_attempts=3
fi
local _startup_attempt=1
local _startup_retries=$(( _startup_max_attempts - 1 ))
local _name_conflict_retries="${ODS_COMPOSE_NAME_CONFLICT_RETRY_ATTEMPTS:-1}"
if ! [[ "$_name_conflict_retries" =~ ^[0-9]+$ ]] || (( _name_conflict_retries < 0 )); then
_name_conflict_retries=1
fi
local _name_conflict_attempt=0
while (( _rc != 0 )) && $_is_compose_up; do
if grep -Eiq 'container name "/?ods-[^"]+" is already in use by container "[0-9a-fA-F]+"' "$_compose_log"; then
if (( _name_conflict_attempt >= _name_conflict_retries )); then
break
fi
_name_conflict_attempt=$(( _name_conflict_attempt + 1 ))
warn "Docker reported a stale ODS container-name conflict; removing the conflicting container and retrying (${_name_conflict_attempt}/${_name_conflict_retries})."
_compose_remove_conflicting_ods_containers "$_compose_log" || break
sleep "${ODS_COMPOSE_NAME_CONFLICT_RETRY_DELAY:-3}"
elif (( _startup_attempt < _startup_max_attempts )) \
&& grep -Eiq 'dependency failed to start|No such container|container .* (exited|is unhealthy)|service .* failed to start|failed to start.*container|failed to create task.*OCI runtime create failed|OCI runtime create failed.*message recipient disconnected from message bus' "$_compose_log"; then
warn "Docker reported a transient service startup failure; waiting briefly and retrying (${_startup_attempt}/${_startup_retries})."
sleep "${ODS_COMPOSE_STARTUP_RETRY_DELAY:-15}"
_startup_attempt=$(( _startup_attempt + 1 ))
else
break
fi
: >"$_compose_log"
_rc=0
docker compose --progress quiet "$@" >"$_compose_log" 2>&1 || _rc=$?
done
if (( _rc == 0 )); then
success "${_verb} — done"
rm -f "$_compose_log"
trap - INT TERM
return 0
fi
log_error "${_verb} failed:"
local _surfaced
_surfaced=$(grep -iE 'error|unhealthy|failed|dependency|permission denied|docker API|docker daemon|docker\.sock|/var/run/docker\.sock|no such service:' "$_compose_log" \
| sed 's/^/ /' \
| head -20 || true)
if [[ -n "$_surfaced" ]]; then
printf '%s\n' "$_surfaced"
else
warn "(no error keywords matched in compose log)"
fi
# Connect failed services to logs and recovery steps if not in test stub mode
if [[ -z "${DOCKER_STUB_MODE:-}" ]]; then
local -a _compose_args=() _target_services=()
local _arg _seen_verb=false _skip_value=false
for _arg in "$@"; do
if ! $_seen_verb; then
if [[ "$_arg" == "up" || "$_arg" == "down" || "$_arg" == "stop" || "$_arg" == "pull" ]]; then
_seen_verb=true
else
_compose_args+=("$_arg")
fi
continue
fi
if $_skip_value; then
_skip_value=false
continue
fi
case "$_arg" in
--pull|--timeout|-t|--scale|--wait-timeout|--exit-code-from|--attach|--no-attach) _skip_value=true ;;
-*) ;;
*) _target_services+=("$_arg") ;;
esac
done
local _failed_candidates=()
local _c
# Names in compose's "Found orphan containers" warning belong to
# stale, unrelated containers, so that line is never evidence. Other
# log names stay: a targeted service can fail on an unhealthy
# dependency ("dependency failed to start: container ods-x ...").
local _log_names _target_names=""
_log_names=$(grep -viE 'found orphan containers' "$_compose_log" | grep -oE 'ods-[a-zA-Z0-9_-]+' || true) # no match = no names
if (( ${#_target_services[@]} > 0 )); then
# Targeted command: also include the targeted services' own
# containers. A ps failure only loses optional evidence; the
# compose error above is already surfaced.
_target_names=$(docker compose "${_compose_args[@]}" ps -a --format "{{.Name}}" "${_target_services[@]}" 2>/dev/null || true)
fi
while read -r _c; do
[[ -n "$_c" ]] && _failed_candidates+=("$_c")
done < <(printf '%s\n%s\n' "$_log_names" "$_target_names" | sort -u)
local _failed_containers=()
if (( ${#_failed_candidates[@]} > 0 )); then
local _project_containers
_project_containers=$(docker compose "${_compose_args[@]}" ps -a --format "{{.Name}}" 2>/dev/null || true)
for _c in "${_failed_candidates[@]}"; do
if grep -qxFe "$_c" <<< "$_project_containers"; then
local _inspect
_inspect=$(docker inspect --format '{{.State.Status}} {{if .State.Health}}{{.State.Health.Status}}{{else}}none{{end}}' "$_c" 2>/dev/null || true)
local _status="" _health=""
read -r _status _health <<< "$_inspect"
if [[ "$_status" == "exited" || "$_status" == "dead" || "$_status" == "restarting" || "$_health" == "unhealthy" ]]; then
_failed_containers+=("$_c")
fi
fi
done
fi
for _c in "${_failed_containers[@]}"; do
echo ""
warn "Recent logs for container $_c (evidence):"
docker logs --tail 20 "$_c" 2>&1 | sed 's/^/ /' || true
done
if (( ${#_failed_containers[@]} > 0 )); then
echo ""
warn "Actionable recovery step:"
warn " Run 'ods doctor' to inspect system readiness and get suggested fixes."
fi
fi
if grep -qiE 'permission denied.*(docker API|docker daemon|docker\.sock|/var/run/docker\.sock)|/var/run/docker\.sock.*permission denied' "$_compose_log"; then
warn "Docker socket permission denied. Add your user to the docker group, then start a new login shell:"
warn " sudo usermod -aG docker \"\$USER\""
warn " newgrp docker # or log out and back in"
warn "Then verify with: docker ps"
fi
echo ""
log "Full compose output: $_compose_log"
echo " Need help? Ask on the ODS Discord: https://discord.gg/4ntNp9MAwC" >&2
trap - INT TERM
return "$_rc"
}
#=============================================================================
# Warn (don't exit) when the current user can't reach the Docker daemon on
# Linux. Phase 05 of the installer sets DOCKER_CMD="sudo docker" for users
# not in the docker group, but ods-cli calls bare `docker compose` and
# can't see that. Without this check, --rebuild-images fails with an opaque
# "permission denied while trying to connect to the Docker daemon socket"
# and users have no idea what to do next. macOS Docker Desktop grants
# socket access to the logged-in user, so the check is Linux-only.
#=============================================================================
_check_docker_access() {
[[ "$(uname -s)" == Linux* ]] || return 0
local _docker_ps_output
if _docker_ps_output=$(docker ps 2>&1); then
return 0
fi
if grep -qiE 'permission denied.*(docker API|docker daemon|docker\.sock|/var/run/docker\.sock)|/var/run/docker\.sock.*permission denied' <<<"$_docker_ps_output"; then
warn "Current user cannot reach the Docker daemon: Docker socket permission denied."
warn "Run: sudo usermod -aG docker \"\$USER\""
warn "Then run: newgrp docker (or log out and back in) and retry."
else
warn "Current user cannot reach the Docker daemon. Start Docker and verify with: docker ps"
fi
}
#=============================================================================
# Rebuild local-built images (opt-in via --rebuild-images on restart/start/update).
# Always rebuilds: dashboard, dashboard-api, ape, token-spy, privacy-shield.
# Conditionally rebuilds based on .env state:
# - comfyui (ENABLE_COMFYUI=true)
# Mirrors the conditional logic in installers/phases/11-services.sh. Unlike that
# phase's image-inspect fast-path, --rebuild-images is an explicit opt-in so we
# always rebuild every applicable service from source.
#=============================================================================
_ods_cli_rebuild_images() {
local flags=("$@")
local svcs=(dashboard dashboard-api ape token-spy privacy-shield)
# Mirror phases/11-services.sh conditional builds: ComfyUI when enabled.
# llama-server is a pulled upstream image on every GPU backend.
[[ "${ENABLE_COMFYUI:-}" == "true" ]] && svcs+=(comfyui)
_check_docker_access
log "Rebuilding local-built images (--rebuild-images)..."
if ! docker compose "${flags[@]}" build --no-cache "${svcs[@]}"; then
warn "One or more images failed to rebuild (continuing — see compose output above)"
fi
}
_ods_cli_pull_external_images() {
local flags=("$@")
local helper="$INSTALL_DIR/installers/lib/compose-images.sh"
if ! command -v ods_compose_external_images >/dev/null 2>&1 && [[ -f "$helper" ]]; then
# Reuse the installer's image discovery contract: pull registry images,
# skip local build tags such as ods-llama-sycl:local.
. "$helper"
fi
if ! command -v ods_compose_external_images >/dev/null 2>&1; then
_compose_run_with_summary "Pulling latest images" "${flags[@]}" pull
return
fi
local image_output=""
if ! image_output="$(ods_compose_external_images "docker compose" "${flags[@]}")"; then
warn "Could not resolve external Compose image list; falling back to docker compose pull."
_compose_run_with_summary "Pulling latest images" "${flags[@]}" pull
return
fi
local -a images=()
local image
while IFS= read -r image; do
[[ -n "$image" ]] && images+=("$image")
done <<< "$image_output"
if (( ${#images[@]} == 0 )); then
success "Pulling latest images — done"
return 0
fi
_check_docker_access
log "Pulling latest images..."
local count=0 total=${#images[@]} failed=0
for image in "${images[@]}"; do
count=$((count + 1))
log " [$count/$total] $image"
local _pull_max_attempts="${ODS_COMPOSE_PULL_RETRY_ATTEMPTS:-3}"
if ! [[ "$_pull_max_attempts" =~ ^[0-9]+$ ]] || (( _pull_max_attempts < 1 )); then
_pull_max_attempts=3
fi
local _pull_attempt=1 _pull_ok=false _pull_log
_pull_log=$(mktemp)
while (( _pull_attempt <= _pull_max_attempts )); do
: >"$_pull_log"
if docker pull "$image" >"$_pull_log" 2>&1; then
_pull_ok=true
break
fi
if (( _pull_attempt >= _pull_max_attempts )) \
|| ! grep -Eiq 'context deadline exceeded|i/o timeout|TLS handshake timeout|connection reset by peer|connection timed out|temporary failure|network is unreachable|net/http: request canceled|unexpected EOF' "$_pull_log"; then
break
fi
local _pull_delay
case "$_pull_attempt" in
1) _pull_delay="${ODS_COMPOSE_PULL_RETRY_DELAY_1:-5}" ;;
2) _pull_delay="${ODS_COMPOSE_PULL_RETRY_DELAY_2:-15}" ;;
*) _pull_delay="${ODS_COMPOSE_PULL_RETRY_DELAY_N:-30}" ;;
esac
warn "Docker registry pull hit a transient network error; retrying (${_pull_attempt}/$((_pull_max_attempts - 1)))."
sleep "$_pull_delay"
_pull_attempt=$((_pull_attempt + 1))
done
if [[ "$_pull_ok" != "true" ]]; then
cat "$_pull_log" >&2
failed=$((failed + 1))
fi
rm -f "$_pull_log"
done
if (( failed > 0 )); then
log_error "Pulling latest images failed: $failed/$total image(s)"
return 1
fi
success "Pulling latest images — done"
}
#=============================================================================
# Commands
#=============================================================================
# A core service the installation deliberately left out is not part of the
# stack, so status must not report it as "not responding". Lean and
# gateway-only installs set ENABLE_OPEN_WEBUI=false; Open WebUI is then an
# optional Library add-back rather than a missing core service. A core
# extension whose compose file the installer left disabled (Pixel Model Relay
# on an install without Pixel) is likewise not part of the stack.
_ods_cli_service_not_installed() {
local service_dir="${INSTALL_DIR}/extensions/services/$1"
[[ "$1" == "open-webui" && "${ENABLE_OPEN_WEBUI:-true}" == "false" ]] && return 0
[[ -f "$service_dir/compose.yaml.disabled" && ! -f "$service_dir/compose.yaml" ]] || return 1
shift
# Native Pixel intentionally selects disabled-named fragments. Use the
# same resolved stack as status instead of hiding an installed service.
local previous="" argument selected
for argument in "$@"; do
if [[ "$previous" == "-f" ]]; then
selected="$argument"
[[ "$selected" == /* ]] || selected="$INSTALL_DIR/$selected"
[[ "$selected" -ef "$service_dir/compose.yaml.disabled" ]] && return 1
fi
previous="$argument"
done
return 0
}
_ods_cli_service_health() {
local sid="$1" port="$2" health_path="$3"
shift 3
if [[ "${SERVICE_HEALTH_SOURCES[$sid]:-http}" == "container" ]]; then
local container_id="" inspect="" state="" container_health=""
container_id=$(docker compose "$@" ps -q "$sid" 2>/dev/null || true)
if [[ -n "$container_id" ]]; then
inspect=$(docker inspect \
--format '{{.State.Status}} {{if .State.Health}}{{.State.Health.Status}}{{else}}none{{end}}' \
"$container_id" 2>/dev/null || true)
read -r state container_health <<<"$inspect"
fi
if [[ "$state" == "running" && "$container_health" == "healthy" ]]; then
printf 'healthy\n'
else
printf 'unhealthy\n'
fi
return 0
fi
local url="http://127.0.0.1:${port}${health_path}"
local timeout="${SERVICE_HEALTH_TIMEOUTS[$sid]:-5}"
if curl -sf --max-time "$timeout" "$url" >/dev/null 2>&1; then
printf 'healthy\n'
else
printf 'unhealthy\n'
fi
}
# The vLLM engine (LLM_BACKEND=vllm) publishes no host port. Its Docker
# healthcheck asks /health, which answers only once the model is loaded, so
# Docker's state is its status: healthy, starting (a cold start loads the
# weights and compiles kernels for up to 15 minutes), unhealthy, or stopped.
_ODS_VLLM_NAME="vLLM (LLM Inference)"
_ods_cli_vllm_health() {
local inspect state="" health=""
if ! inspect=$(docker inspect --format \
'{{.State.Status}} {{if .State.Health}}{{.State.Health.Status}}{{else}}none{{end}}' \
ods-vllm-server 2>&1); then
printf 'stopped\n'
return 0
fi
read -r state health <<<"$inspect"
if [[ "$state" != "running" ]]; then
printf 'stopped\n'
elif [[ "$health" == "healthy" || "$health" == "starting" ]]; then
printf '%s\n' "$health"
else
printf 'unhealthy\n'
fi
}
cmd_status() {
local json_mode="false"
while [[ $# -gt 0 ]]; do
case "$1" in
--json) json_mode="true"; shift ;;
*) error "Unknown argument to 'ods status': $1" ;;
esac
done
if [[ "$json_mode" == "true" ]]; then
# Subshell isolates cmd_status_json's RETURN trap so it can't leak
# into this caller's frame and re-fire with an unbound $tmp under set -u.
( cmd_status_json )
return $?
fi
check_install
cd "$INSTALL_DIR"
load_env
sr_load
# Only status needs the model-route selector. Keep unrelated CLI commands
# usable while repairing a partial install that is missing this library.
# shellcheck source=lib/preflight-llm-route.sh
. "$SCRIPT_DIR/lib/preflight-llm-route.sh"
local flags_str
flags_str=$(get_compose_flags)
local -a flags
read -ra flags <<< "$flags_str"
echo -e "${BLUE}━━━ ODS Status ━━━${NC}"
echo ""
# Container status. Let compose's own stderr through: when the daemon is
# unreachable the user needs "Cannot connect to the Docker daemon", not a
# flag-less fallback complaining about a missing configuration file.
docker compose "${flags[@]}" ps --format "table {{.Name}}\t{{.Status}}\t{{.Ports}}" \
|| warn "Could not list containers (see the docker error above); continuing with health checks."
echo ""
# Registry-driven health checks (parallel)
echo -e "${BLUE}━━━ Health Checks ━━━${NC}"
# Create temp directory for health check results
local tmpdir
tmpdir=$(mktemp -d)
trap "rm -rf '$tmpdir'" RETURN
# Array to track background job PIDs
local -a pids=()
# Launch parallel health checks
for sid in "${SERVICE_IDS[@]}"; do
# Cloud and external-model installs intentionally do not start the
# managed model stack; a host-native llama-server (Windows Portal)
# keeps model-router. Report the active LiteLLM gateway instead.
if ods_status_skips_managed_inference "$sid"; then
continue
fi
_ods_cli_service_not_installed "$sid" "${flags[@]}" && continue
local health="${SERVICE_HEALTH[$sid]}"
local port_env="${SERVICE_PORT_ENVS[$sid]}"
local default_port="${SERVICE_PORTS[$sid]}"
local name="${SERVICE_NAMES[$sid]:-$sid}"
local cat="${SERVICE_CATEGORIES[$sid]}"
# Container-authoritative internal services have no host port but are
# still part of operator status.
[[ -z "$health" ]] && continue
[[ "$default_port" == "0" && "${SERVICE_HEALTH_SOURCES[$sid]:-http}" != "container" ]] && continue
# Resolve port from env var or default
local port="$default_port"
if [[ -n "$port_env" ]]; then
port="${!port_env:-$default_port}"
fi
# For non-core services, only check if container is running
if [[ "$cat" != "core" ]]; then
if ! docker compose "${flags[@]}" ps --format "{{.Name}}" 2>/dev/null | grep -qE "ods-${sid}|${sid}"; then
continue # Not running, skip silently
fi
fi
# Launch health check in background
(
if [[ "$(_ods_cli_service_health "$sid" "$port" "$health" "${flags[@]}")" == "healthy" ]]; then
echo "healthy|$name" > "$tmpdir/$sid"
else
echo "unhealthy|$name" > "$tmpdir/$sid"
fi
) &
pids+=($!)
done
# Wait for all health checks to complete
for pid in "${pids[@]}"; do
wait "$pid" 2>/dev/null || true
done
# Display results in SERVICE_IDS order
for sid in "${SERVICE_IDS[@]}"; do
if [[ -f "$tmpdir/$sid" ]]; then
local result
result=$(cat "$tmpdir/$sid")
local status="${result%%|*}"
local name="${result#*|}"
if [[ "$status" == "healthy" ]]; then
success "$name: healthy"
else
warn "$name: not responding"
fi
fi
done
if ods_preflight_vllm_engine; then
case "$(_ods_cli_vllm_health)" in
healthy) success "$_ODS_VLLM_NAME: healthy" ;;
starting) log "$_ODS_VLLM_NAME: starting. A first start loads the model and compiles kernels, which can take 15 minutes. Follow it with: ods logs llm" ;;
*) warn "$_ODS_VLLM_NAME: not responding. See why with: ods logs llm" ;;
esac
fi
echo ""
# Select GPU tooling by backend, not by installed vendor utilities.
if [[ "${GPU_BACKEND:-}" == "amd" || "${GPU_BACKEND:-}" == "apple" ]]; then
( _gpu_status )
elif [[ "${GPU_BACKEND:-nvidia}" == "nvidia" ]] && command -v nvidia-smi &> /dev/null; then
echo -e "${BLUE}━━━ GPU Status ━━━${NC}"
nvidia-smi --query-gpu=name,utilization.gpu,memory.used,memory.total,temperature.gpu --format=csv,noheader,nounits | \
awk -F', ' '{printf " %s: %s%% GPU | %sMB/%sMB VRAM | %s°C\n", $1, $2, $3, $4, $5}' \
|| warn "nvidia-smi failed"
fi
# Bootstrap status. This file may be mid-write, so missing fields should
# not abort `ods status` under pipefail.
local bootstrap_file="$INSTALL_DIR/data/bootstrap-status.json"
if [[ -f "$bootstrap_file" ]]; then
local bs_status
bs_status="$(_ods_cli_bootstrap_status)"
if [[ "$bs_status" == "downloading" || "$bs_status" == "starting" || "$bs_status" == "verifying" || "$bs_status" == "swapping" ]]; then
local bs_model bs_percent
bs_model=$(grep -o '"model"[[:space:]]*:[[:space:]]*"[^"]*"' "$bootstrap_file" | sed -n '1p' | sed 's/.*"model"[[:space:]]*:[[:space:]]*"//' | sed 's/"//' || true)
bs_percent=$(grep -o '"percent"[[:space:]]*:[[:space:]]*[0-9.]*' "$bootstrap_file" | sed -n '1p' | sed 's/.*:[[:space:]]*//' || true)
log ""
log " Model Upgrade: $bs_model (${bs_percent:-?}% downloaded)"
fi
fi
}
cmd_status_json() {
check_install
cd "$INSTALL_DIR"
sr_load
load_env
# shellcheck source=lib/preflight-llm-route.sh
. "$SCRIPT_DIR/lib/preflight-llm-route.sh"
local flags_str
flags_str=$(get_compose_flags)
local -a flags
read -ra flags <<< "$flags_str"
# Keep one snapshot and its success separate: a stopped stack has valid,
# empty ps output. Only a failed read leaves container state unknown.
local running_services="" container_state_known="false"
if running_services=$(docker compose "${flags[@]}" ps --format "{{.Service}}" 2>/dev/null); then
container_state_known="true"
elif command -v docker-compose >/dev/null 2>&1; then
if running_services=$(docker-compose "${flags[@]}" ps --services --filter "status=running" 2>/dev/null); then
container_state_known="true"
fi
fi
# Temp file to accumulate per-service JSON objects
local tmp
tmp=$(mktemp)
trap 'rm -f "$tmp"' RETURN
for sid in "${SERVICE_IDS[@]}"; do
if ods_status_skips_managed_inference "$sid"; then
continue
fi
_ods_cli_service_not_installed "$sid" "${flags[@]}" && continue
local cat="${SERVICE_CATEGORIES[$sid]}"
local health="${SERVICE_HEALTH[$sid]}"
local port_env="${SERVICE_PORT_ENVS[$sid]}"
local default_port="${SERVICE_PORTS[$sid]}"
local name="${SERVICE_NAMES[$sid]:-$sid}"
# Container-authoritative internal services have no host port but are
# still part of operator status.
[[ -z "$health" ]] && continue
[[ "$default_port" == "0" && "${SERVICE_HEALTH_SOURCES[$sid]:-http}" != "container" ]] && continue
# Resolve port from env var or default
local port="$default_port"
if [[ -n "$port_env" ]]; then
port="${!port_env:-$default_port}"
fi
local container_status="unknown"
local status="unknown"
# An empty successful snapshot still proves no service is running.
if [[ "$container_state_known" == "true" ]]; then
if grep -Fxq -- "$sid" <<<"$running_services"; then
container_status="running"
else
container_status="stopped"
fi
fi
# For non-core services that are clearly stopped, avoid HTTP probe
if [[ "$cat" != "core" && "$container_status" == "stopped" ]]; then
status="stopped"
else
status="$(_ods_cli_service_health "$sid" "$port" "$health" "${flags[@]}")"
fi
jq -n \
--arg id "$sid" \
--arg name "$name" \
--arg category "$cat" \
--arg port "$port" \
--arg status "$status" \
--arg containerStatus "$container_status" \
'{id: $id, name: $name, category: $category, port: $port, status: $status, containerStatus: $containerStatus}' >> "$tmp"
done
if ods_preflight_vllm_engine; then
local vllm_status vllm_container="unknown"
vllm_status="$(_ods_cli_vllm_health)"
if [[ "$container_state_known" == "true" ]]; then
vllm_container="stopped"
grep -Fxq -- vllm-server <<<"$running_services" && vllm_container="running"
fi
# No host port: model-router and LiteLLM reach it on the ODS network.
jq -n --arg name "$_ODS_VLLM_NAME" --arg status "$vllm_status" --arg containerStatus "$vllm_container" \
'{id: "vllm-server", name: $name, category: "core", port: "", status: $status, containerStatus: $containerStatus}' >> "$tmp"
fi
# GPU summary (optional)
local gpu_summary_json="null"
if [[ "${GPU_BACKEND:-}" == "apple" ]]; then
# Apple Silicon: integrated GPU with unified memory. Surface the same
# fields as `ods gpu status` so consumers of status-json can render
# non-null GPU info on macOS.
local _chip _total_mem_gb _gpu_cores
_chip="$(sysctl -n machdep.cpu.brand_string 2>/dev/null || echo 'Apple Silicon')"
_total_mem_gb=$(( $(sysctl -n hw.memsize 2>/dev/null || echo 0) / 1024 / 1024 / 1024 ))
if command -v jq >/dev/null 2>&1; then
_gpu_cores=$(system_profiler SPDisplaysDataType -json 2>/dev/null \
| jq -r '.SPDisplaysDataType[0].sppci_cores // "?"' 2>/dev/null)
else
_gpu_cores="?"
fi
gpu_summary_json=$(jq -n \
--arg backend "apple" \
--arg chip "$_chip" \
--argjson unified_memory_gb "$_total_mem_gb" \
--argjson gpu_cores "$([[ "$_gpu_cores" =~ ^[0-9]+$ ]] && printf '%s' "$_gpu_cores" || printf 'null')" \
'{backend: $backend, chip: $chip, unified_memory_gb: $unified_memory_gb, gpu_cores: $gpu_cores}')
elif [[ "${GPU_BACKEND:-nvidia}" == "nvidia" ]] && command -v nvidia-smi >/dev/null 2>&1; then
# Represent each GPU line as raw strings in an array
gpu_summary_json=$(nvidia-smi --query-gpu=name,utilization.gpu,memory.used,memory.total,temperature.gpu \
--format=csv,noheader,nounits 2>/dev/null | jq -R -s 'split("\n") | map(select(length > 0))')
fi
# Aggregate into a single document
jq -s \
--arg installDir "$INSTALL_DIR" \
--arg composeFlags "$flags_str" \
--arg mode "${ODS_MODE:-local}" \
--arg tier "${TIER:-}" \
--arg currentModel "${LLM_MODEL:-}" \
--argjson gpu "$gpu_summary_json" \
'{installDir: $installDir,
composeFlags: $composeFlags,
mode: $mode,
tier: $tier,
currentModel: $currentModel,
gpu: $gpu,
services: .}' "$tmp"
}
cmd_logs() {
check_install
cd "$INSTALL_DIR"
load_env
local service="${1:-}"
local lines="${2:-100}"
if [[ -z "$service" ]]; then
log "Usage: ods logs <service> [lines]"
log "Run 'ods list' to see available services."
exit 1
fi
service=$(resolve_service "$service")
local flags_str
flags_str=$(get_compose_flags)
local -a flags
read -ra flags <<< "$flags_str"
docker compose "${flags[@]}" logs -f --tail "$lines" "$service"
}
_ods_cli_wait_for_hermes_ready() {
local timeout interval attempts state i
timeout="${ODS_HERMES_READY_TIMEOUT:-300}"
interval="${ODS_HERMES_READY_INTERVAL:-3}"
[[ "$timeout" =~ ^[1-9][0-9]*$ ]] || timeout=300
[[ "$interval" =~ ^[1-9][0-9]*$ ]] || interval=3
# Hermes is optional. A restart that does not include it must not acquire
# a new product dependency or delay otherwise-healthy installations.
docker inspect ods-hermes >/dev/null 2>&1 || return 0
log "Waiting for Hermes agent readiness..."
attempts=$(( (timeout + interval - 1) / interval ))
for (( i=1; i<=attempts; i++ )); do
state=$(docker inspect --format \
'{{if .State.Health}}{{.State.Health.Status}}{{else}}{{.State.Status}}{{end}}' \
ods-hermes 2>/dev/null || true)
case "$state" in
healthy)
success "Hermes agent — ready"
return 0
;;
exited|dead)
log_error "Hermes agent did not recover after restart (state: $state)."
return 1
;;
esac
(( i < attempts )) && sleep "$interval"
done
log_error "Hermes agent did not become ready within ${timeout}s (last state: ${state:-missing})."
return 1
}
# `docker compose up -d` returns before LiteLLM serves, and its Docker
# healthcheck runs every 30 s. Portal chat goes through LiteLLM, so a chat sent
# right after a start or restart failed once (fleet F58: 6-16 s after the
# Windows lifecycle restart returned). Probe its readiness endpoint directly.
# A slow gateway only warns: the start itself succeeded.
_ods_cli_wait_for_litellm_ready() {
local timeout interval attempts i
timeout="${ODS_LITELLM_READY_TIMEOUT:-90}"
interval="${ODS_LITELLM_READY_INTERVAL:-2}"
[[ "$timeout" =~ ^[1-9][0-9]*$ ]] || timeout=90
[[ "$interval" =~ ^[1-9][0-9]*$ ]] || interval=2
# Not every stack runs LiteLLM.
docker inspect ods-litellm >/dev/null 2>&1 || return 0
log "Waiting for the model gateway (LiteLLM)..."
attempts=$(( (timeout + interval - 1) / interval ))
for (( i=1; i<=attempts; i++ )); do
if docker exec ods-litellm python3 -c \
"import urllib.request; urllib.request.urlopen('http://127.0.0.1:4000/health/readiness', timeout=5)" \
>/dev/null 2>&1; then
success "Model gateway — ready"
return 0
fi
(( i < attempts )) && sleep "$interval"
done
warn "The model gateway (LiteLLM) is still starting after ${timeout}s; chat can fail until it is ready. Check it with: ods status"
return 0
}
_ods_cli_wait_for_hermes_ready_with_retry() {
local flags=("$@")
local state flag hermes_selected=false
# `ods disable hermes` stops its container but leaves it in place, so the
# container existing does not mean this stack runs Hermes. Wait only when
# its Compose file is part of the stack being restarted.
for flag in "${flags[@]}"; do
if [[ "$flag" == extensions/services/hermes/compose.yaml \
|| "$flag" == */extensions/services/hermes/compose.yaml ]]; then
hermes_selected=true
fi
done
[[ "$hermes_selected" == true ]] || return 0
if _ods_cli_wait_for_hermes_ready; then
return 0
fi
state=$(docker inspect --format \
'{{if .State.Health}}{{.State.Health.Status}}{{else}}{{.State.Status}}{{end}}' \
ods-hermes 2>/dev/null || true)
[[ "$state" == "unhealthy" ]] || return 1
# Repeated fleet restart cycles can occasionally leave Hermes in Docker's
# explicit unhealthy state even though a clean recreate recovers it. Retry
# only that terminal state once; a second failed readiness check remains a
# hard restart failure.
log "Hermes was unhealthy after restart; recreating it once..."
_compose_run_with_summary "Retrying Hermes" \
"${flags[@]}" up -d --force-recreate --no-build --pull never hermes
_ods_cli_refresh_soul || true
_ods_cli_wait_for_hermes_ready
}
cmd_restart() {
check_install
cd "$INSTALL_DIR"
load_env
# Parse flags vs positional service name
local rebuild_images="false"
local service=""
while [[ $# -gt 0 ]]; do
case "$1" in
--rebuild-images) rebuild_images="true"; shift ;;
--) shift; break ;;
-*) error "Unknown option: $1" ;;
*) service="$1"; shift ;;
esac
done
# A full restart or a llama-server restart under a model switch leaves the
# switch half-applied, as an update would. Refuse before changing CPU
# budgets in .env or dispatching to the native Mac llama helper.
if [[ -z "$service" || "$(resolve_service "$service")" == llama-server ]]; then
_ods_cli_refuse_under_model_lifecycle restart
fi
ensure_llama_cpu_budget
if [[ -n "$service" && "$(resolve_service "$service")" == llama-server ]] \
&& _ods_cli_macos_native_llama; then
_ods_cli_macos_llama restart
return 0
fi
local flags_str
flags_str=$(get_compose_flags)
local -a flags
read -ra flags <<< "$flags_str"
[[ "$rebuild_images" == "true" ]] && _ods_cli_rebuild_images "${flags[@]}"
local resolved_service="$service"
if [[ -n "$resolved_service" ]]; then
resolved_service=$(resolve_service "$resolved_service")
fi
if [[ "$resolved_service" == "ods-proxy" ]]; then
_ods_cli_prepare_proxy_start "${flags[@]}"
elif [[ -z "$resolved_service" || "$resolved_service" == "open-webui" ]] \
&& _ods_cli_network_access_enabled; then
_ods_cli_require_proxy_auth
fi
if ! _ods_cli_repair_rootless_ownership "$resolved_service"; then
error "Rootless bind-mount ownership is not ready; service restart was cancelled."
fi
local refresh_soul="false"
if [[ -z "$resolved_service" || "$resolved_service" == "hermes" ]]; then
refresh_soul="true"
# Must run before compose as well as after it. If a previous failed
# compose created data/persona/SOUL.md as a directory, Docker will fail
# the Hermes file bind mount before the post-start refresh can repair it.
_ods_cli_refresh_soul || true
fi
if [[ -z "$resolved_service" || "$resolved_service" == "llama-server" ]]; then
_ods_cli_wait_for_bootstrap_compose_safe "restart"
_ods_cli_reload_model_env
ensure_llama_cpu_budget
flags_str=$(get_compose_flags)
read -ra flags <<< "$flags_str"
fi
local restarted_mode="${ODS_MODE:-}"
if [[ -z "$resolved_service" ]]; then
_compose_run_with_summary "Restarting all services" \
"${flags[@]}" up -d --force-recreate --no-build --pull never
else
_compose_run_with_summary "Restarting $resolved_service" \
"${flags[@]}" up -d --force-recreate --no-build --pull never "$resolved_service"
fi
# Refresh SOUL.md after compose has ensured Hermes is running, so the
# generated install context can be copied into /opt/data/SOUL.md without
# needing the Docker Desktop-hostile nested bind mount.
if [[ "$refresh_soul" == "true" ]]; then
_ods_cli_refresh_soul || true
fi
if [[ -z "$resolved_service" || "$resolved_service" == "litellm" ]]; then
_ods_cli_wait_for_litellm_ready
fi
# `docker compose up -d` only proves that container creation was accepted.
# Do not tell users a full/Hermes restart is done while Dream Talk and the
# default agent path can still return a startup error.
if [[ -z "$resolved_service" || "$resolved_service" == "hermes" ]]; then
_ods_cli_wait_for_hermes_ready_with_retry "${flags[@]}"
fi
# `ods mode` changes .env, while the native agent deliberately pins its
# startup mode. Refresh that process only after the complete stack has
# applied the new environment, never on an unrelated service restart.
if [[ -z "$resolved_service" && -f "$INSTALL_DIR/bin/ods-host-agent.py" ]]; then
cmd_agent refresh-mode "$restarted_mode" || return 1
fi
if [[ -z "$resolved_service" || "$resolved_service" == "llama-server" ]]; then
_ods_cli_maybe_resume_bootstrap_upgrade || true
fi
}
_ods_cli_maybe_resume_bootstrap_upgrade() {
local status_file="$INSTALL_DIR/data/bootstrap-status.json"
local args_file="$INSTALL_DIR/data/bootstrap-upgrade.args"
[[ -f "$status_file" && -f "$args_file" && -f "$INSTALL_DIR/scripts/bootstrap-upgrade.sh" ]] || return 0
local bs_status
bs_status=$(grep -o '"status"[[:space:]]*:[[:space:]]*"[^"]*"' "$status_file" | sed -n '1p' | sed 's/.*"status"[[:space:]]*:[[:space:]]*"//' | sed 's/"//' || true)
local retry_reason="previous download failed"
if [[ "$bs_status" == "failed" || "$bs_status" == "error" ]]; then
retry_reason="previous download failed"
elif [[ "$bs_status" == "starting" || "$bs_status" == "downloading" || "$bs_status" == "verifying" || "$bs_status" == "swapping" ]]; then
_ods_cli_bootstrap_upgrade_status_is_stale "$status_file" || return 0
retry_reason="stale download appears stopped"
else
return 0
fi
if command -v pgrep >/dev/null 2>&1 && pgrep -f "bootstrap-upgrade.sh.*$INSTALL_DIR" >/dev/null 2>&1; then
log " Model Upgrade: retry already running"
return 0
fi
local full_gguf_file full_gguf_url full_gguf_sha256 full_llm_model full_max_context bootstrap_gguf_file
full_gguf_file=$(sed -n '1p' "$args_file")
full_gguf_url=$(sed -n '2p' "$args_file")
full_gguf_sha256=$(sed -n '3p' "$args_file")
full_llm_model=$(sed -n '4p' "$args_file")
full_max_context=$(sed -n '5p' "$args_file")
bootstrap_gguf_file=$(sed -n '6p' "$args_file")
if [[ -z "$full_gguf_file" || -z "$full_gguf_url" || -z "$full_llm_model" || -z "$full_max_context" || -z "$bootstrap_gguf_file" ]]; then
warn "Bootstrap model upgrade failed previously, but retry metadata is incomplete."
return 0
fi
mkdir -p "$INSTALL_DIR/logs"
nohup bash "$INSTALL_DIR/scripts/bootstrap-upgrade.sh" \
"$INSTALL_DIR" "$full_gguf_file" "$full_gguf_url" \
"$full_gguf_sha256" "$full_llm_model" "$full_max_context" \
"$bootstrap_gguf_file" \
> "$INSTALL_DIR/logs/model-upgrade.log" 2>&1 &
log " Model Upgrade: $retry_reason; retrying in background ($full_llm_model)"
log " Check progress: tail -f $INSTALL_DIR/logs/model-upgrade.log"
}
_ods_cli_bootstrap_upgrade_status_is_stale() {
local status_file="$1"
local stale_seconds="${ODS_BOOTSTRAP_UPGRADE_STALE_SECONDS:-900}"
[[ "$stale_seconds" =~ ^[0-9]+$ ]] || stale_seconds=900
local updated_at
updated_at=$(grep -o '"updatedAt"[[:space:]]*:[[:space:]]*"[^"]*"' "$status_file" | sed -n '1p' | sed 's/.*"updatedAt"[[:space:]]*:[[:space:]]*"//' | sed 's/"//' || true)
[[ -n "$updated_at" ]] || return 1
local updated_epoch=""
updated_epoch=$(date -u -d "$updated_at" +%s 2>/dev/null || true)
if [[ -z "$updated_epoch" ]]; then
updated_epoch=$(date -j -u -f "%Y-%m-%dT%H:%M:%SZ" "$updated_at" +%s 2>/dev/null || true)
fi
[[ "$updated_epoch" =~ ^[0-9]+$ ]] || return 1
local now_epoch
now_epoch=$(date -u +%s 2>/dev/null || date +%s)
[[ "$now_epoch" =~ ^[0-9]+$ ]] || return 1
(( now_epoch - updated_epoch > stale_seconds ))
}
# Refresh data/hermes/SOUL.md from the static template + detected install
# state. Idempotent. Called automatically by cmd_restart (when restarting
# hermes or the whole stack) and invocable manually by an operator.
_ods_cli_refresh_soul() {
local script="$INSTALL_DIR/scripts/build-installation-context.py"
[[ -x "$script" ]] || [[ -f "$script" ]] || return 0
local py
py=$(command -v python3 || command -v python || true)
[[ -n "$py" ]] || return 0
"$py" "$script" >/dev/null 2>&1 || return 1
# Push the updated assembled SOUL.md into the running container's
# data dir, where Hermes actually reads from at session.create
# time. The bind-mount target (/opt/hermes/docker/SOUL.md) is just
# the upstream-default that Hermes's entrypoint copies to
# /opt/data/SOUL.md ONLY on first start; the per-install file is
# what's read after that. macOS Docker Desktop's virtiofs refuses
# to bind-mount /opt/data/SOUL.md directly (nested-mount limit),
# so we use docker exec for the in-container copy — works on
# Linux + macOS uniformly. Container has to be running for this
# to matter; if it's not, the entrypoint will pick up the docker/
# default on next start anyway.
if command -v docker >/dev/null 2>&1; then
if docker ps --format '{{.Names}}' 2>/dev/null | grep -q '^ods-hermes$'; then
docker exec ods-hermes cp /opt/hermes/docker/SOUL.md /opt/data/SOUL.md \
>/dev/null 2>&1 || true
fi
fi
return 0
}
_stop_owned_containers_for_recovery() {
local helper="$INSTALL_DIR/scripts/stop-owned-containers.py"
local policy_python="${ODS_PYTHON_CMD:-python3}"
local -a args=(--install-dir "$INSTALL_DIR")
[[ -n "${1:-}" ]] && args+=(--service "$1")
warn "Compose validation failed; stopping only existing containers verified as belonging to this installation."
"$policy_python" "$helper" "${args[@]}"
}
# On macOS the model runs natively as the launchd job com.ods.llama-server, and
# the Compose llama-server is a replicas-0 placeholder: Compose would report a
# stop, start or restart without touching the running model. ods-macos.sh owns
# that job.
_ods_cli_macos_native_llama() {
[[ "$(uname -s)" == Darwin && "${GPU_BACKEND:-}" == apple ]]
}
_ods_cli_macos_llama() {
local action="$1" macos_cli="$INSTALL_DIR/ods-macos.sh"
if [[ ! -f "$macos_cli" ]]; then
echo -e "${RED}✗${NC} The macOS service CLI is missing ($macos_cli), so ODS cannot $action the model server on this Mac. Re-run the installer to restore it." >&2
echo " Need help? Ask on the ODS Discord: https://discord.gg/4ntNp9MAwC" >&2
exit 1
fi
if ! INSTALL_DIR="$INSTALL_DIR" "${BASH:-bash}" "$macos_cli" "$action" llama-server; then
echo " Need help? Ask on the ODS Discord: https://discord.gg/4ntNp9MAwC" >&2
exit 1
fi
}
cmd_stop() {
check_install
cd "$INSTALL_DIR"
load_env
local service="${1:-}"
if [[ -n "$service" && "$(resolve_service "$service")" == llama-server ]] \
&& _ods_cli_macos_native_llama; then
_ods_cli_macos_llama stop
return 0
fi
local flags_str
if ! flags_str=$(get_compose_flags); then
[[ -n "$service" ]] && service=$(resolve_service "$service")
_stop_owned_containers_for_recovery "$service"
return $?
fi
local -a flags
read -ra flags <<< "$flags_str"
if [[ -z "$service" ]]; then
# Keep stopped containers and their Compose install-path labels. A
# later uninstall needs those labels to prove which volumes it owns.
_compose_run_with_summary "Stopping all services" "${flags[@]}" stop
else
service=$(resolve_service "$service")
_compose_run_with_summary "Stopping $service" "${flags[@]}" stop "$service"
fi
}
_ods_cli_repair_rootless_ownership() {
local service="${1:-}"
local helper="$INSTALL_DIR/lib/rootless-ownership.sh"
[[ -f "$helper" ]] || return 0
# shellcheck source=lib/rootless-ownership.sh
source "$helper"
ods_fix_rootless_ownership "$INSTALL_DIR" "$service"
}
# The legacy OpenClaw extension was removed. Starts never remove orphan
# containers, so an upgrade that stopped before its final stack start can leave
# the old ods-openclaw container running; say how to remove it.
_ods_cli_warn_legacy_openclaw_container() {
if docker container inspect ods-openclaw >/dev/null 2>&1; then
warn "The removed legacy OpenClaw container ods-openclaw still exists. Remove it with: docker rm -f ods-openclaw (see docs/MIGRATION-OPENCLAW-TO-HERMES.md)"
fi
}
cmd_start() {
check_install
cd "$INSTALL_DIR"
load_env
ensure_llama_cpu_budget
sr_load
# Parse flags vs positional service name
local rebuild_images="false"
local restart_wsl_agent="true"
local service=""
while [[ $# -gt 0 ]]; do
case "$1" in
--rebuild-images) rebuild_images="true"; shift ;;
# The Windows lifecycle controller owns the verified native restart.
--defer-wsl-agent-restart) restart_wsl_agent="false"; shift ;;
--) shift; break ;;
-*) error "Unknown option: $1" ;;
*) service="$1"; shift ;;
esac
done
if [[ "$restart_wsl_agent" == false && -n "$service" ]]; then
error "Deferred WSL agent restart requires a complete stack start."
fi
if [[ -n "$service" && "$(resolve_service "$service")" == llama-server ]] \
&& _ods_cli_macos_native_llama; then
_ods_cli_macos_llama start
return 0
fi
local flags_str
flags_str=$(get_compose_flags)
local -a flags
read -ra flags <<< "$flags_str"
[[ "$rebuild_images" == "true" ]] && _ods_cli_rebuild_images "${flags[@]}"
local resolved_service="$service"
if [[ -n "$resolved_service" ]]; then
resolved_service=$(resolve_service "$resolved_service")
fi
if [[ -z "$resolved_service" && -f "$INSTALL_DIR/lib/wsl-agent-address.sh" ]]; then
# Refresh only automatically managed NAT addresses after WSL restarts.
# shellcheck source=lib/wsl-agent-address.sh
. "$INSTALL_DIR/lib/wsl-agent-address.sh"
ods_prepare_wsl_agent_address "$INSTALL_DIR" "$restart_wsl_agent" || error "WSL control address could not be prepared; start cancelled."
load_env
fi
if [[ "$resolved_service" == "ods-proxy" ]]; then
_ods_cli_prepare_proxy_start "${flags[@]}"
elif [[ -z "$resolved_service" || "$resolved_service" == "open-webui" ]] \
&& _ods_cli_network_access_enabled; then
_ods_cli_require_proxy_auth
fi
local refresh_soul="false"
if [[ -z "$resolved_service" || "$resolved_service" == "hermes" ]]; then
refresh_soul="true"
_ods_cli_refresh_soul || true
fi
if [[ -z "$resolved_service" || "$resolved_service" == "llama-server" ]]; then
_ods_cli_wait_for_bootstrap_compose_safe "start"
_ods_cli_reload_model_env
ensure_llama_cpu_budget
flags_str=$(get_compose_flags)
read -ra flags <<< "$flags_str"
fi
if ! _ods_cli_repair_rootless_ownership "$resolved_service"; then
error "Rootless bind-mount ownership is not ready; service start was cancelled."
fi
# WSL-only: recover stale Docker Desktop bind mounts before Compose starts.
# The helper itself no-ops on non-WSL and non-Docker-Desktop hosts; the
# uname gate here keeps Python from being a hard requirement on plain Linux.
if [[ "$(uname -r 2>/dev/null)" == *[Mm]icrosoft* ]]; then
local _wsl_bind_recovery="$INSTALL_DIR/scripts/wsl-bind-recovery.py"
if [[ ! -f "$_wsl_bind_recovery" ]]; then
error "WSL bind-mount recovery helper is missing: $_wsl_bind_recovery. Reinstall or update ODS before starting services."
fi
if ! "${ODS_PYTHON_CMD:-python3}" "$_wsl_bind_recovery" --install-dir "$INSTALL_DIR" --service "$resolved_service" -- "${flags[@]}"; then
error "WSL bind-mount recovery failed; service start was cancelled."
fi
fi
if [[ -z "$resolved_service" ]]; then
_compose_run_with_summary "Starting all services" "${flags[@]}" up -d
_ods_cli_warn_legacy_openclaw_container
else
_run_hook "$resolved_service" "pre_start"
_compose_run_with_summary "Starting $resolved_service" "${flags[@]}" up -d "$resolved_service"
_run_hook "$resolved_service" "post_start"
fi
if [[ "$refresh_soul" == "true" ]]; then
_ods_cli_refresh_soul || true
fi
if [[ -z "$resolved_service" || "$resolved_service" == "litellm" ]]; then
_ods_cli_wait_for_litellm_ready
fi
if [[ -z "$resolved_service" || "$resolved_service" == "llama-server" ]]; then
_ods_cli_maybe_resume_bootstrap_upgrade || true
fi
}
cmd_dry_run() {
check_install
cd "$INSTALL_DIR"
load_env
echo -e "${BLUE}━━━ ODS Update — Dry Run ━━━${NC}"
echo "Preview only. No changes will be applied."
echo ""
# ── version ──────────────────────────────────────────────────────────────
local cur_ver="0.0.0"
if [[ -f "$INSTALL_DIR/.env" ]]; then
local _v
_v=$(grep '^ODS_VERSION=' "$INSTALL_DIR/.env" 2>/dev/null | cut -d= -f2 | tr -d '[:space:]' || true)
[[ -n "$_v" ]] && cur_ver="$_v"
fi
if [[ "$cur_ver" == "0.0.0" && -f "$INSTALL_DIR/.version" ]]; then
local _vf
_vf=$(jq -r '.version // empty' "$INSTALL_DIR/.version" 2>/dev/null || true)
[[ -n "$_vf" ]] && cur_ver="$_vf"
fi
# Try dashboard API first; fall back to direct GitHub query.
local api_json=""
local dashboard_api_port="${DASHBOARD_API_PORT:-3002}"
local api_key=""
api_key=$(grep '^DASHBOARD_API_KEY=' "$INSTALL_DIR/.env" 2>/dev/null | cut -d= -f2 | tr -d '[:space:]' || true)
if [[ -z "$api_key" && -f "$INSTALL_DIR/data/dashboard-api-key.txt" ]]; then
api_key=$(cat "$INSTALL_DIR/data/dashboard-api-key.txt" | tr -d '\r\n ' || true)
fi
if [[ -n "$api_key" ]]; then
# A header file keeps the key out of argv, which any local user can read.
api_json=$(curl -sf --max-time 5 \
-H @<(printf 'Authorization: Bearer %s\n' "$api_key") \
"http://127.0.0.1:${dashboard_api_port}/api/update/dry-run" 2>/dev/null || true)
fi
local latest_ver="" changelog_url="" update_status="" check_error=""
if [[ -n "$api_json" ]] && echo "$api_json" | jq -e '.current_version' >/dev/null 2>&1; then
latest_ver=$(echo "$api_json" | jq -r '.latest_version // empty')
changelog_url=$(echo "$api_json" | jq -r '.changelog_url // empty')
check_error=$(echo "$api_json" | jq -r '.version_check_error // empty')
local api_available
api_available=$(echo "$api_json" | jq -r '.update_available // false')
[[ "$api_available" == "true" ]] && update_status="update available" || update_status="up to date"
else
# Direct GitHub fallback
local gh_resp
gh_resp=$(curl -sf --max-time 8 \
"https://api.github.com/repos/Osmantic/ODS/releases/latest" 2>/dev/null || true)
if [[ -n "$gh_resp" ]] && command -v jq >/dev/null 2>&1; then
latest_ver=$(echo "$gh_resp" | jq -r '.tag_name // empty' 2>/dev/null | sed 's/^v//' || true)
changelog_url=$(echo "$gh_resp" | jq -r '.html_url // empty' 2>/dev/null || true)
fi
if [[ -n "$latest_ver" ]]; then
if _semver_lt "$cur_ver" "$latest_ver"; then
update_status="update available"
else
update_status="up to date"
fi
fi
fi
echo -e "${BLUE}━━━ Version ━━━${NC}"
echo " Installed : v${cur_ver}"
if [[ -n "$latest_ver" ]]; then
echo " Available : v${latest_ver}"
if [[ "$update_status" == "update available" ]]; then
echo -e " Status : ${YELLOW}${update_status}${NC}"
else
echo -e " Status : ${GREEN}${update_status}${NC}"
fi
[[ -n "$changelog_url" ]] && echo " Changelog : ${changelog_url}"
else
echo " Available : (${check_error:-could not reach GitHub})"
fi
echo ""
# ── image tags ────────────────────────────────────────────────────────────
echo -e "${BLUE}━━━ Image tags (would be pulled) ━━━${NC}"
local flags_str
flags_str=$(get_compose_flags)
local -a flags
read -ra flags <<< "$flags_str"
# List what `ods update` pulls: its own discovery over this install's
# resolved stack (see _ods_cli_pull_external_images). The API can only read
# every compose file's image lines, unresolved and for every GPU backend,
# so its list is the fallback.
local images_shown=false image_output=""
local helper="$INSTALL_DIR/installers/lib/compose-images.sh"
if ! command -v ods_compose_external_images >/dev/null 2>&1 && [[ -f "$helper" ]]; then
. "$helper"
fi
if command -v ods_compose_external_images >/dev/null 2>&1 \
&& image_output="$(ods_compose_external_images "docker compose" "${flags[@]}")"; then
local _img_line
while IFS= read -r _img_line; do
[[ -n "$_img_line" ]] && echo " ${_img_line}"
done <<< "$image_output"
[[ -n "$image_output" ]] || echo " (none: every service image is built locally)"
images_shown=true
fi
# Use process substitution so flags like images_shown update in this shell (not a pipe subshell).
if [[ "$images_shown" == "false" ]] && [[ -n "$api_json" ]] \
&& echo "$api_json" | jq -e '.images | length > 0' >/dev/null 2>&1; then
local _img_line _any_api=false
while IFS= read -r _img_line || [[ -n "$_img_line" ]]; do
[[ -z "$_img_line" ]] && continue
echo " ${_img_line}"
_any_api=true
done < <(echo "$api_json" | jq -r '.images[]' | sort -u)
[[ "$_any_api" == "true" ]] && images_shown=true
fi
[[ "$images_shown" == "false" ]] && echo " (could not resolve compose config)"
echo ""
echo -e "${BLUE}━━━ Running image digests ━━━${NC}"
# Read each running container's image ID. `docker compose images` moved
# that column when it added PLATFORM, so this section printed platforms.
# A preview that cannot list the stack reports it as not running.
local running_ids=""
running_ids=$(docker compose "${flags[@]}" ps -q 2>/dev/null || true)
if [[ -n "$running_ids" ]]; then
# shellcheck disable=SC2086 # one container ID per word
docker inspect --format '{{.Name}} {{.Image}}' $running_ids 2>/dev/null \
| awk '{sub(/^\//, "", $1); sub(/^sha256:/, "", $2); printf " %-30s %s\n", $1, substr($2, 1, 12)}' \
|| echo " (could not read the running containers)"
else
echo " (services not running)"
fi
echo ""
# ── model / GGUF ─────────────────────────────────────────────────────────
echo -e "${BLUE}━━━ Model configuration (.env) ━━━${NC}"
local -a model_keys=(TIER LLM_MODEL GGUF_FILE CTX_SIZE GPU_BACKEND N_GPU_LAYERS)
local key
for key in "${model_keys[@]}"; do
local val
val=$(grep "^${key}=" "$INSTALL_DIR/.env" 2>/dev/null | cut -d= -f2 | tr -d '[:space:]' || true)
printf " %-16s %s\n" "${key}:" "${val:-(not set)}"
done
echo ""
# ── .env keys the update path reads/writes ────────────────────────────────
echo -e "${BLUE}━━━ .env keys (read/write) ━━━${NC}"
local -a update_keys=(ODS_VERSION TIER LLM_MODEL GGUF_FILE CTX_SIZE GPU_BACKEND N_GPU_LAYERS)
if [[ -n "$api_json" ]] && echo "$api_json" | jq -e '.env_keys' >/dev/null 2>&1; then
echo "$api_json" | jq -r '.env_keys | to_entries[] | " \(.key): \(.value)"' 2>/dev/null \
|| true
else
for key in "${update_keys[@]}"; do
local val
val=$(grep "^${key}=" "$INSTALL_DIR/.env" 2>/dev/null | cut -d= -f2 | tr -d '[:space:]' || true)
printf " %-16s %s\n" "${key}:" "${val:-(not set)}"
done
fi
echo ""
# ── summary ───────────────────────────────────────────────────────────────
echo "To apply this update: ods update"
echo ""
warn "Dry run complete. Nothing was changed."
}
cmd_update() {
check_install
cd "$INSTALL_DIR"
load_env
# Parse flags
local dry_run="false"
local force_flag="false"
local rebuild_images="false"
while [[ $# -gt 0 ]]; do
case "$1" in
--dry-run|-n) dry_run="true"; shift ;;
--force|-f) force_flag="true"; shift ;;
--rebuild-images) rebuild_images="true"; shift ;;
--*) error "Unknown option: $1" ;;
-*) error "Unknown option: $1" ;;
*) error "Unexpected argument: $1" ;;
esac
done
if [[ "$dry_run" == "true" ]]; then
cmd_dry_run
return 0
fi
# Version compatibility check — warn on major version jumps before touching anything
if ! _check_version_compat "$force_flag"; then
exit 0
fi
# Show what we're updating from/to (if versions were resolved)
if [[ -n "${_COMPAT_INSTALLED_VER:-}" && -n "${_COMPAT_TARGET_VER:-}" \
&& "$_COMPAT_INSTALLED_VER" != "$_COMPAT_TARGET_VER" ]]; then
log "Updating: v${_COMPAT_INSTALLED_VER} → v${_COMPAT_TARGET_VER}"
fi
# Never restart the agent or recreate the stack under a model switch or a
# Portal access check: either would be left half-applied.
_ods_cli_refuse_under_model_lifecycle update
# Require the configuration snapshot that `ods rollback` can restore,
# before changing configuration, Compose selection, images or containers.
local _snap_label="pre-update-$(date +%Y%m%d-%H%M%S)"
if [[ ! -x "$INSTALL_DIR/ods-update.sh" ]]; then
error "ods-update.sh is missing or not executable; restore it before updating so a rollback snapshot can be created."
fi
log "Creating pre-update snapshot (${_snap_label})..."
if ! bash "$INSTALL_DIR/ods-update.sh" backup "$_snap_label"; then
error "Pre-update snapshot failed. Resolve backup storage and retry; no update was applied."
fi
# Upsert SHIELD_API_KEY when missing (pre-PR-#1069 upgrade path).
# Without it the dashboard Privacy Shield stats panel fails after
# update because dashboard-api can no longer authenticate its
# proxied /stats call. Mirrors the env-generator.sh upsert pattern.
if [[ -z "$(_env_get_raw "SHIELD_API_KEY")" ]]; then
local shield_key
shield_key="$(openssl rand -hex 32 2>/dev/null)" || shield_key=""
if [[ ! "$shield_key" =~ ^[0-9a-fA-F]{64}$ ]]; then
shield_key="$(od -An -N 32 -tx1 /dev/urandom 2>/dev/null | tr -d ' \n')" || shield_key=""
fi
[[ "$shield_key" =~ ^[0-9a-fA-F]{64}$ ]] \
|| error "Could not generate SHIELD_API_KEY; existing configuration was preserved."
_env_set "SHIELD_API_KEY" "$shield_key"
fi
ensure_llama_cpu_budget
local flags_str
flags_str=$(get_compose_flags)
local -a flags
read -ra flags <<< "$flags_str"
if ! _ods_cli_pull_external_images "${flags[@]}"; then
error "Failed to pull latest images"
fi
_ods_cli_wait_for_bootstrap_compose_safe "update"
load_env
ensure_llama_cpu_budget
flags_str=$(get_compose_flags)
read -ra flags <<< "$flags_str"
[[ "$rebuild_images" == "true" ]] && _ods_cli_rebuild_images "${flags[@]}"
# Recreating everything recreates Open WebUI too.
if _ods_cli_network_access_enabled; then
_ods_cli_require_proxy_auth
fi
if ! _compose_run_with_summary "Recreating containers with new images" "${flags[@]}" up -d --force-recreate; then
error "Failed to recreate containers. Run 'ods rollback' to restore previous state."
fi
log "Waiting for services to stabilize..."
sleep 10
# Verify update was successful
log "Verifying update..."
local failed_services=0
local total_services=0
local active_services=""
local running_services=""
active_services=$(docker compose "${flags[@]}" config --services 2>/dev/null \
|| docker compose "${flags[@]}" ps --all --services 2>/dev/null \
|| true)
running_services=$(docker compose "${flags[@]}" ps --services --status running 2>/dev/null || true)
if [[ -z "$active_services" ]]; then
log_error "Update verification failed: active compose stack has no services"
log_error "Run 'ods status' to check service health"
exit 1
fi
# Check only the active compose stack. sr_list_enabled() lists every
# installed extension with a compose file, including disabled optional
# services, which can make a healthy update look failed.
while IFS= read -r service; do
[[ -z "$service" ]] && continue
((++total_services))
if grep -Fxq "$service" <<< "$running_services"; then
continue
fi
# Some user extensions are one-shot jobs that legitimately exit 0
# after compose recreates them. Treat those as successful, but still
# fail missing containers and non-zero exits.
local ids=""
local completed_ok="false"
ids=$(docker compose "${flags[@]}" ps --all -q "$service" 2>/dev/null || true)
if [[ -n "$ids" ]]; then
completed_ok="true"
while IFS= read -r id; do
[[ -z "$id" ]] && continue
local state=""
state=$(docker inspect -f '{{.State.Status}} {{.State.ExitCode}}' "$id" 2>/dev/null || true)
case "$state" in
"running "*) ;;
"exited 0") ;;
*) completed_ok="false"; break ;;
esac
done <<< "$ids"
fi
if [[ "$completed_ok" != "true" ]]; then
warn "Service $service is not running"
((++failed_services))
fi
done <<< "$active_services"
if [[ $failed_services -gt 0 ]]; then
log_error "Update verification failed: $failed_services/$total_services services are not running"
log_error "Run 'ods rollback' to restore previous state"
log_error "Or run 'ods status' to check service health"
exit 1
fi
# Persist the new installed version in .env so future runs know what's installed
if [[ -n "${_COMPAT_TARGET_VER:-}" ]]; then
_env_set "ODS_VERSION" "$_COMPAT_TARGET_VER"
fi
# Restart host agent so new endpoints / code changes take effect
log "Restarting host agent..."
cmd_agent restart || warn "Host agent restart failed (non-fatal)"
success "Update complete"
cmd_status
}
cmd_shell() {
check_install
cd "$INSTALL_DIR"
# Load the service registry so SERVICE_IDS is populated in our shell.
sr_load
# Resolve aliases (e.g. "llm" -> "llama-server").
local service
service=$(sr_resolve "${1:-llm}")
# Validate against registry before doing anything.
local _found=false
for _sid in "${SERVICE_IDS[@]}"; do
if [[ "$_sid" == "$service" ]]; then
_found=true
break
fi
done
if ! $_found; then
error "Unknown service: $service"
fi
local container
container=$(sr_container "$service")
# Distinguish "daemon down" from "container stopped" — the container-running
# check below uses `docker ps`, which also exits non-zero when the daemon
# is unreachable. Without this preflight a user whose Docker is stopped
# sees "Container X is not running" and tries `ods start`, which also
# fails, creating a confusing loop. The explicit check lets the error
# reflect the actual cause.
#
# `docker info` can hang for 20+ seconds when Docker Desktop is mid-boot
# (socket exists, daemon not yet accepting RPCs). `timeout` isn't stock
# macOS, but `perl alarm` is (perl ships with macOS ≥ 10.5 and every
# Linux/WSL2 distro we target). `alarm` is inherited across `exec`, so
# the docker process receives SIGALRM after 3s if it hasn't returned.
if ! perl -e 'alarm 3; exec "docker", "info"' >/dev/null 2>&1; then
error "Docker is not running (or not responding within 3s). Start Docker Desktop / dockerd and retry."
fi
# Confirm the container is running before trying to exec.
if ! docker ps 2>/dev/null --format '{{.Names}}' | grep -qx "$container"; then
error "Container $container is not running. Start it with: ods start $service"
fi
log "Opening shell in $container..."
# Distinguish "no bash binary" from "exec failed" by probing first.
if docker exec "$container" test -x /bin/bash >/dev/null 2>&1; then
docker exec -it "$container" /bin/bash
else
docker exec -it "$container" /bin/sh
fi
}
# File-scope helpers used by `ods config show` and `ods preset diff` to
# mask secret values. `.env.schema.json` is the authoritative source; keys
# marked `"secret": true` are treated as secrets. A keyword fallback covers
# schema gaps (e.g. ANTHROPIC_API_KEY is currently secret:false) and the case
# where the schema file or jq is unavailable. Callers must invoke
# _cmd_config_load_secret_schema once (after check_install, so INSTALL_DIR is
# set) before calling _cmd_config_is_secret.
_cmd_config_secret_keys=()
_cmd_config_schema_loaded=0
_cmd_config_load_secret_schema() {
local _schema_path="$INSTALL_DIR/.env.schema.json"
_cmd_config_secret_keys=()
_cmd_config_schema_loaded=0
[[ -f "$_schema_path" ]] || return 0
# Prefer jq when available — fast, single-process, schema-typed.
if command -v jq >/dev/null 2>&1; then
mapfile -t _cmd_config_secret_keys < <(jq -r '.properties | to_entries[] | select(.value.secret == true) | .key' "$_schema_path" 2>/dev/null)
_cmd_config_schema_loaded=1
return 0
fi
# python3 fallback for environments without jq (Git Bash on Windows
# is the common one). The installer guarantees python3, so this
# path closes the gap where N8N_USER / LANGFUSE_INIT_USER_EMAIL etc.
# would otherwise leak through the keyword fallback.
if command -v python3 >/dev/null 2>&1; then
mapfile -t _cmd_config_secret_keys < <(python3 - "$_schema_path" <<'PYEOF' 2>/dev/null
import json, sys
try:
with open(sys.argv[1]) as f:
data = json.load(f)
except (OSError, json.JSONDecodeError):
sys.exit(0)
for key, spec in (data.get("properties") or {}).items():
if isinstance(spec, dict) and spec.get("secret") is True:
print(key)
PYEOF
)
_cmd_config_schema_loaded=1
return 0
fi
# Neither jq nor python3 — leave _cmd_config_schema_loaded=0 so
# _cmd_config_is_secret falls through to the keyword regex (which
# covers user/email keys explicitly to avoid leaks in this case).
}
_cmd_config_is_secret() {
local _k="$1" _s _kl
if (( _cmd_config_schema_loaded == 1 )); then
for _s in "${_cmd_config_secret_keys[@]}"; do
_s="${_s%$'\r'}"
[[ "$_k" == "$_s" ]] && return 0
done
# Fall through to keyword match — defense in depth against schema gaps
# and against malformed schemas where jq/python returns zero secret keys.
fi
_kl="${_k,,}"
# `*user*` and `*email*` cover N8N_USER, LANGFUSE_INIT_USER_EMAIL, etc.
# in environments where neither jq nor python3 was available to read
# `.env.schema.json` (Git Bash without jq). Risks light over-masking
# on operational keys like USER_HOME, but `cat .env` remains the
# escape hatch — `ods config show` defaults to over-mask on
# purpose.
case "$_kl" in
*secret*|*password*|*pass*|*token*|*key*|*salt*|*bearer*|*user*|*email*) return 0 ;;
esac
return 1
}
cmd_config() {
check_install
local action="${1:-show}"
case "$action" in
show)
echo -e "${BLUE}━━━ Configuration ━━━${NC}"
echo "Install dir: $INSTALL_DIR"
echo ""
echo -e "${CYAN}.env contents:${NC}"
_cmd_config_load_secret_schema
local _line _key
while IFS= read -r _line; do
[[ -z "$_line" || "$_line" =~ ^[[:space:]]*# ]] && continue
_key="${_line%%=*}"
if _cmd_config_is_secret "$_key"; then
echo " ${_key}=***"
else
echo " $_line"
fi
done < "$INSTALL_DIR/.env"
;;
edit)
${EDITOR:-nano} "$INSTALL_DIR/.env"
warn "Restart services for changes to take effect: ods restart"
;;
validate)
cd "$INSTALL_DIR"
if [[ -x "$INSTALL_DIR/scripts/validate-env.sh" ]]; then
# Invoke through "$BASH" (the currently-running shell, guaranteed
# Bash 4+ by the version check at the top of this file). The
# target script uses associative arrays (declare -A), which
# crash under macOS's system /bin/bash (3.2).
"$BASH" "$INSTALL_DIR/scripts/validate-env.sh" "$INSTALL_DIR/.env" "$INSTALL_DIR/.env.schema.json"
else
warn "validate-env.sh not found at $INSTALL_DIR/scripts/validate-env.sh"
warn "Make sure you're on a recent ODS release."
fi
echo ""
if [[ -x "$INSTALL_DIR/scripts/validate-manifests.sh" ]]; then
log "Validating extension manifests and compatibility..."
if "$BASH" "$INSTALL_DIR/scripts/validate-manifests.sh"; then
success "Extension manifests validated"
else
warn "Extension manifest validation reported issues. See output above."
return 1
fi
else
warn "validate-manifests.sh not found at $INSTALL_DIR/scripts/validate-manifests.sh"
fi
;;
*)
log "Usage: ods config [show|edit|validate]"
;;
esac
}
_chat_curl() {
local token="$1" response status
shift
# --fail-with-body is unavailable on older supported curl releases. Append
# the HTTP status instead, preserving both transport errors and API bodies.
if [[ -n "$token" ]]; then
response=$(curl -H @<(printf 'Authorization: Bearer %s\n' "$token") \
--write-out '\n%{http_code}' "$@") || return $?
else
response=$(curl --write-out '\n%{http_code}' "$@") || return $?
fi
status="${response##*$'\n'}"
printf '%s' "${response%$'\n'*}"
if [[ "$status" -ge 400 ]]; then
return 22
fi
}
cmd_chat() {
check_install
load_env # B6 fix: use safe env loading function
local message="${1:-Hello}"
local model="${2:-}"
# Match the installed route used by ODS clients. A gateway-selected install
# may deliberately have no local llama-server, or keep one loaded while a
# remote provider is active. Never probe it as a fallback for that route.
# shellcheck source=lib/preflight-llm-route.sh
. "$SCRIPT_DIR/lib/preflight-llm-route.sh"
local _llm_port="${SERVICE_PORTS[llama-server]:-11434}"
_llm_port="${OLLAMA_PORT:-${LLAMA_SERVER_PORT:-$_llm_port}}"
local _token="" _route_name="llama-server"
if [[ "${ODS_MODEL_SWITCHBOARD:-enabled}" == enabled ]] || ods_preflight_uses_litellm; then
_llm_port="${LITELLM_PORT:-4000}"
_token="${LITELLM_KEY:-${LITELLM_MASTER_KEY:-}}"
[[ -n "$_token" ]] || error "Chat cannot authenticate to the gateway: LITELLM_KEY is missing."
_route_name="LLM gateway"
if [[ -z "$model" ]]; then
if [[ "${ODS_MODEL_SWITCHBOARD:-enabled}" == enabled ]]; then
model="ods/current"
else
model="default"
fi
fi
fi
local _probe
_probe=$(_chat_curl "$_token" --silent --show-error --max-time 3 \
"http://127.0.0.1:${_llm_port}/v1/models" 2>&1) || {
error "$_route_name not reachable at http://127.0.0.1:${_llm_port} - is 'ods status' showing it healthy? $_probe"
}
if [[ -z "$model" ]]; then
model=$(printf '%s' "$_probe" | jq -er '.data[0].id' 2>/dev/null || echo "local")
fi
log "Sending to $model..."
# Use jq to safely construct JSON payload (prevents injection)
local payload
payload=$(jq -n --arg model "$model" --arg msg "$message" \
'{model: $model, messages: [{role: "user", content: $msg}], max_tokens: 500}')
local _resp
_resp=$(_chat_curl "$_token" --silent --show-error --max-time 30 \
"http://127.0.0.1:${_llm_port}/v1/chat/completions" \
-H "Content-Type: application/json" \
-d "$payload" 2>&1) || {
error "LLM request failed: $_resp"
}
[[ -z "$_resp" ]] && error "LLM returned empty response"
local _content
_content=$(printf '%s' "$_resp" | jq -er '.choices[0].message.content') || {
local _err
_err=$(printf '%s' "$_resp" | jq -r '.error.message // "unknown error"' 2>/dev/null || true)
error "LLM error: ${_err:-unparseable response}"
}
printf '%s\n' "$_content"
}
cmd_benchmark() {
check_install
load_env # B6 fix: use safe env loading function
log "Running quick benchmark..."
local start=$(date +%s)
local response
if ! response=$(cmd_chat "Say exactly: Hello World" 2>&1); then
error "Benchmark failed: LLM unreachable or error - see 'ods chat' for details"
fi
local end=$(date +%s)
local duration=$(( end - start ))
echo ""
echo -e "${BLUE}━━━ Benchmark Results ━━━${NC}"
echo " Response time: ${duration}s"
echo " Response: $response"
if [[ $duration -lt 2 ]]; then
success "Performance: Excellent (<2s)"
elif [[ $duration -lt 5 ]]; then
success "Performance: Good (<5s)"
else
warn "Performance: Slow (>5s) - check GPU/model"
fi
}
cmd_doctor() {
check_install
cd "$INSTALL_DIR"
local json_mode="false"
local report_file="/tmp/ods-doctor-report.json"
# Parse arguments
while [[ $# -gt 0 ]]; do
case "$1" in
--json)
json_mode="true"
shift
;;
--report)
[[ -n "${2:-}" ]] || { echo "Error: --report requires a path argument" >&2; return 1; }
report_file="$(_caller_path "$2")"
shift 2
;;
*)
report_file="$(_caller_path "$1")"
shift
;;
esac
done
if [[ ! -x "$INSTALL_DIR/scripts/ods-doctor.sh" ]]; then
error "ods-doctor script not found at $INSTALL_DIR/scripts/ods-doctor.sh"
fi
# Run doctor script. If it fails to generate a report, show the script output
# to make failures actionable for operators. Each run writes a new private
# report and only that one is shown: a file already at $report_file (an
# earlier run, or another user's in the shared /tmp) must never stand in
# for this run (fleet: after a failed run, doctor showed an old install's
# model and runtime).
local doctor_out run_report
doctor_out=$(mktemp)
run_report=$(mktemp)
"$INSTALL_DIR/scripts/ods-doctor.sh" "$run_report" >"$doctor_out" 2>&1 || true
if [[ ! -s "$run_report" ]]; then
cat "$doctor_out" >&2
rm -f "$doctor_out" "$run_report"
echo -e "${RED}✗${NC} The doctor stopped before it finished its report; its output is above." >&2
echo " Need help? Ask on the ODS Discord: https://discord.gg/4ntNp9MAwC" >&2
exit 1
fi
rm -f "$doctor_out"
# cp names its own failure (for example, another user's file at the
# default path); this run's report then stays where it is.
if cp -- "$run_report" "$report_file"; then
rm -f "$run_report"
else
warn "This run's report is at $run_report"
report_file="$run_report"
fi
# JSON mode: just output the report
if [[ "$json_mode" == "true" ]]; then
cat "$report_file"
return 0
fi
# If python3 is unavailable, fall back to printing the JSON report.
if ! command -v python3 >/dev/null 2>&1; then
warn "python3 not found; printing raw JSON report (use --json to suppress this warning)"
cat "$report_file"
return 1
fi
# Parse and display operator-friendly output
echo -e "${BLUE}━━━ ODS Diagnostics ━━━${NC}"
echo ""
# Use Python to parse JSON and display results
python3 - "$report_file" <<'PY'
import json
import sys
RED = '\033[0;31m'
GREEN = '\033[0;32m'
YELLOW = '\033[1;33m'
BLUE = '\033[0;34m'
CYAN = '\033[0;36m'
NC = '\033[0m'
report_file = sys.argv[1]
try:
with open(report_file, 'r') as f:
report = json.load(f)
except Exception as e:
print(f"{RED}✗{NC} Failed to parse report: {e}")
sys.exit(1)
# Runtime checks
runtime = report.get('runtime', {})
print(f"{CYAN}Runtime Environment:{NC}")
checks = [
('Docker CLI', runtime.get('docker_cli', False)),
('Docker Daemon', runtime.get('docker_daemon', False)),
('Docker Compose', runtime.get('compose_cli', False)),
('Dashboard HTTP', runtime.get('dashboard_http', False)),
]
# Reports without an enablement field retain the legacy required check.
webui_disabled = runtime.get('webui_enabled') is False
if not webui_disabled:
checks.append(('WebUI HTTP', runtime.get('webui_http', False)))
has_failures = False
for name, status in checks:
if status:
print(f" {GREEN}✓{NC} {name}")
else:
print(f" {RED}✗{NC} {name}")
has_failures = True
if webui_disabled:
print(f" {CYAN}ℹ{NC} WebUI HTTP (not installed)")
llm_backend = runtime.get('llm_backend', {})
if llm_backend:
llm_status = llm_backend.get('status', 'unknown')
llm_provider = llm_backend.get('provider', 'unknown')
llm_url = llm_backend.get('url', '')
llm_model = llm_backend.get('model', '')
local_warn = llm_backend.get('local_running_warning', False)
recovery = llm_backend.get('recovery_hint', '')
# The vLLM engine (vllm-server) is ODS's own local model server, like llama-server.
is_external = llm_provider not in ("llama-server", "vLLM")
backend_label = f"{llm_provider} (external)" if is_external else f"{llm_provider} (local)"
if llm_status == 'ok':
print(f" {GREEN}✓{NC} LLM Backend: {backend_label} — responding")
if llm_url:
print(f" Endpoint: {llm_url}")
if llm_model:
print(f" Model: {llm_model}")
else:
print(f" {RED}✗{NC} LLM Backend: {backend_label} — not responding")
if llm_url:
print(f" Endpoint: {llm_url}")
if recovery:
print(f" Recovery: {recovery}")
has_failures = True
if local_warn:
print(f" {YELLOW}⚠{NC} Note: Unused local llama-server container is running")
dgx_check = runtime.get('dgx_spark_cuda_arch_check', {})
dgx_status = dgx_check.get('status')
dgx_message = dgx_check.get('message', '')
if dgx_status == 'pass':
print(f" {GREEN}✓{NC} DGX Spark / RTX Spark llama-server CUDA arch")
elif dgx_status == 'warn':
print(f" {YELLOW}⚠{NC} DGX Spark / RTX Spark llama-server CUDA arch: {dgx_message}")
amd_runtime = runtime.get('amd_runtime', {})
if amd_runtime.get('available'):
status = amd_runtime.get('health', 'unknown')
symbol = GREEN + '✓' + NC if status == 'reachable' else YELLOW + '⚠' + NC
print(
f" {symbol} AMD runtime: "
f"{amd_runtime.get('runtime')} / {amd_runtime.get('selectedBackend')} / "
f"{amd_runtime.get('location')} / {status}"
)
for warning in amd_runtime.get('warnings', [])[:3]:
print(f" {YELLOW}⚠{NC} {warning}")
# API mode runs no local AMD runtime: its reason is not a warning (fleet, Strixy).
elif amd_runtime.get('reason') and amd_runtime.get('reason') not in ('not_amd', 'api_mode'):
print(f" {YELLOW}⚠{NC} AMD runtime: {amd_runtime.get('reason')}")
inference_contract = runtime.get('inference_contract') or {}
if inference_contract:
counts = inference_contract.get('issue_counts') or {}
blockers = counts.get('blockers', 0)
warnings = counts.get('warnings', 0)
symbol = GREEN + '✓' + NC if blockers == 0 and warnings == 0 else (RED + '✗' + NC if blockers else YELLOW + '⚠' + NC)
print(
f" {symbol} Inference contract: "
f"mode={inference_contract.get('ods_mode', 'unknown')}, "
f"owner={inference_contract.get('expected_inference_owner', 'unknown')}, "
f"gateway={inference_contract.get('expected_gateway', 'unknown')}"
)
for issue in (inference_contract.get('issues') or [])[:3]:
print(f" {YELLOW if issue.get('severity') == 'warn' else RED}⚠{NC} {issue.get('id')}: {issue.get('detail')}")
print()
# Voice checks
stt_cached = runtime.get('stt_model_cached', 'unknown')
stt_model = runtime.get('stt_model_name') or '<not configured>'
tts_http = runtime.get('tts_http', 'unknown')
if stt_cached != 'unknown' or tts_http != 'unknown':
print(f"{CYAN}Voice Readiness:{NC}")
if stt_cached == 'true':
print(f" {GREEN}✓{NC} Whisper STT model cached: {stt_model}")
elif stt_cached == 'false':
print(f" {YELLOW}⚠{NC} Whisper STT model missing: {stt_model}")
has_failures = True
elif stt_cached == 'service_down':
print(f" {RED}✗{NC} Whisper STT service not responding")
has_failures = True
elif stt_cached == 'disabled':
print(f" {YELLOW}?{NC} Whisper STT disabled")
else:
print(f" {YELLOW}?{NC} Whisper STT model cache unknown")
if tts_http == 'true':
print(f" {GREEN}✓{NC} Kokoro TTS responding")
elif tts_http == 'false':
print(f" {RED}✗{NC} Kokoro TTS not responding")
has_failures = True
elif tts_http == 'disabled':
print(f" {YELLOW}?{NC} Kokoro TTS disabled")
else:
print(f" {YELLOW}?{NC} Kokoro TTS status unknown")
print()
# Preflight checks
preflight = report.get('preflight', {})
pf_checks = preflight.get('checks', [])
blockers = []
warnings = []
if pf_checks:
print(f"{CYAN}Preflight Checks:{NC}")
for check in pf_checks:
name = check.get('name', check.get('id', 'Unknown'))
status = check.get('status', 'unknown')
message = check.get('message', '')
if status == 'pass':
print(f" {GREEN}✓{NC} {name}")
elif status == 'warn':
print(f" {YELLOW}⚠{NC} {name}: {message}")
warnings.append((name, message))
elif status == 'blocker':
print(f" {RED}✗{NC} {name}: {message}")
blockers.append((name, message))
has_failures = True
else:
print(f" {YELLOW}?{NC} {name}: {message}")
print()
# Evidence-ranked diagnoses
diagnoses = report.get('diagnoses', [])
if diagnoses:
print(f"{CYAN}Diagnoses:{NC}")
severity_colors = {
'blocker': RED,
'warn': YELLOW,
'info': CYAN,
}
for diagnosis in diagnoses[:5]:
severity = diagnosis.get('severity', 'info')
color = severity_colors.get(severity, CYAN)
diag_id = diagnosis.get('id', 'ODS-UNKNOWN')
confidence = diagnosis.get('confidence', 'unknown')
title = diagnosis.get('title', 'Unknown diagnosis')
print(f" {color}{severity.upper()}{NC} {diag_id}: {title} ({confidence} confidence)")
evidence = diagnosis.get('evidence') or []
if evidence:
first = evidence[0]
print(f" evidence: {first.get('source', 'unknown')} — {first.get('detail', '')}")
next_steps = diagnosis.get('next_steps') or []
if next_steps:
print(f" next: {next_steps[0]}")
if severity == 'blocker':
has_failures = True
if len(diagnoses) > 5:
print(f" ... {len(diagnoses) - 5} more diagnosis item(s) in the JSON report")
print()
# Summary
summary = report.get('summary', {})
blocker_count = summary.get('preflight_blockers', 0)
warning_count = summary.get('preflight_warnings', 0)
runtime_warning_count = summary.get('runtime_warnings', 0)
diagnosis_blocker_count = summary.get('diagnoses_blockers', 0)
diagnosis_warning_count = summary.get('diagnoses_warnings', 0)
runtime_ready = summary.get('runtime_ready', False)
print(f"{CYAN}Summary:{NC}")
if blocker_count > 0:
print(f" {RED}✗{NC} {blocker_count} blocker(s) found")
if warning_count > 0:
print(f" {YELLOW}⚠{NC} {warning_count} warning(s) found")
if runtime_warning_count > 0:
print(f" {YELLOW}⚠{NC} {runtime_warning_count} runtime warning(s) found")
if diagnosis_blocker_count > 0:
print(f" {RED}✗{NC} {diagnosis_blocker_count} diagnosis blocker(s) found")
if diagnosis_warning_count > 0:
print(f" {YELLOW}⚠{NC} {diagnosis_warning_count} diagnosis warning(s) found")
if blocker_count == 0 and warning_count == 0 and runtime_warning_count == 0 and diagnosis_blocker_count == 0 and diagnosis_warning_count == 0 and runtime_ready:
print(f" {GREEN}✓{NC} All checks passed")
print()
# Autofix hints
hints = report.get('autofix_hints', [])
if hints:
print(f"{CYAN}Suggested Fixes:{NC}")
for i, hint in enumerate(hints[:6], 1):
print(f" {i}. {hint}")
print()
# Exit code: 1 if blockers or runtime failures, 0 otherwise
if has_failures or blocker_count > 0:
sys.exit(1)
else:
sys.exit(0)
PY
return $?
}
cmd_audit() {
check_install
sr_load
local -a script_args=()
local scope="${1:-}"
if [[ "$scope" == "extensions" || "$scope" == "extension" ]]; then
shift
fi
while [[ $# -gt 0 ]]; do
case "$1" in
--json|--strict)
script_args+=("$1")
shift
;;
--help|-h)
python3 "$INSTALL_DIR/scripts/audit-extensions.py" --help
return 0
;;
*)
script_args+=("$(resolve_service "$1")")
shift
;;
esac
done
if [[ ! -f "$INSTALL_DIR/scripts/audit-extensions.py" ]]; then
error "audit-extensions.py not found at $INSTALL_DIR/scripts/audit-extensions.py"
fi
python3 "$INSTALL_DIR/scripts/audit-extensions.py" --project-dir "$INSTALL_DIR" "${script_args[@]}"
}
#=============================================================================
# Extension Management Commands
#=============================================================================
# Track visited services during recursive enable to prevent circular deps
declare -a _ENABLE_VISITED=()
# Host services (manifest type host-systemd) run outside Compose, so the
# selection helper has no compose.yaml to move and would fail with "No Compose
# selection file". Say what to do instead, matching the Dashboard's extension
# detail for OpenCode. A shadowing user extension that ships Compose files
# goes through the normal selection path.
_ods_cli_reject_host_service() {
local service_id="$1" action="$2" ext_dir="$3"
[[ "${SERVICE_TYPES[$service_id]:-docker}" == "host-systemd" ]] || return 0
[[ -e "$ext_dir/compose.yaml" || -e "$ext_dir/compose.yaml.disabled" ]] && return 0
log_error "$service_id runs on the host, not as a Compose extension; 'ods $action' does not apply to it."
if [[ "$service_id" == "opencode" ]]; then
log "Open the OpenCode page in the ODS dashboard (/apps/opencode)."
log "Start OpenCode there when it is stopped; on Linux, set it up there when it is not installed."
log "Or re-run the ODS installer with --opencode to add it, or --no-opencode to remove it."
fi
echo " Need help? Ask on the ODS Discord: https://discord.gg/4ntNp9MAwC" >&2
exit 1
}
cmd_enable() {
check_install
sr_load
load_env 2>/dev/null || true
local input="${1:-}"
[[ -z "$input" ]] && { log "Usage: ods enable <service>"; exit 1; }
local service_id
service_id=$(sr_resolve "$input")
# Circular dependency guard
for _visited in "${_ENABLE_VISITED[@]}"; do
if [[ "$_visited" == "$service_id" ]]; then
warn "Circular dependency detected: $service_id already being enabled. Skipping."
return 0
fi
done
_ENABLE_VISITED+=("$service_id")
# Match Dashboard resolution: an installed user extension shadows a
# bundled definition with the same id, even when its Compose is disabled.
local ext_dir="$INSTALL_DIR/data/user-extensions/$service_id"
[[ ! -d "$ext_dir" ]] && ext_dir="$INSTALL_DIR/extensions/services/$service_id"
[[ -d "$ext_dir" ]] || error "Unknown service: $input"
local disabled="$ext_dir/compose.yaml.disabled"
# Check it's not a core service
local cat="${SERVICE_CATEGORIES[$service_id]:-optional}"
[[ "$cat" == "core" ]] && { success "$service_id is a core service (always enabled)."; return 0; }
_ods_cli_reject_host_service "$service_id" enable "$ext_dir"
if [[ "$service_id" == "ods-proxy" ]]; then
_ods_cli_require_proxy_auth
fi
# Check GPU backend compatibility
local gpu_backends="${SERVICE_GPU_BACKENDS[$service_id]:-}"
if [[ -n "$gpu_backends" ]]; then
# Load current GPU_BACKEND from .env
local current_backend="${GPU_BACKEND:-nvidia}"
if [[ -f "$INSTALL_DIR/.env" ]]; then
local env_backend
env_backend=$(grep "^GPU_BACKEND=" "$INSTALL_DIR/.env" 2>/dev/null | cut -d= -f2 | tr -d '"' || true)
if [[ -n "$env_backend" ]]; then
current_backend="$env_backend"
else
warn "Could not read GPU_BACKEND from .env, using default: nvidia"
fi
fi
# Handle "all" sentinel - services that work on any backend
if [[ " $gpu_backends " =~ " all " ]]; then
# Service works on all backends, skip compatibility check
:
# Apple Silicon exemption - all Docker services work on macOS regardless of gpu_backends
elif [[ "$current_backend" == "apple" ]]; then
# All Docker services run on macOS regardless of gpu_backends declaration
:
# Check if current backend is in the supported list
elif [[ ! " $gpu_backends " =~ " $current_backend " ]]; then
warn "$service_id may not work with GPU backend: $current_backend"
warn " Supported backends: $gpu_backends"
warn " Current backend: $current_backend"
read -p " Continue anyway? [y/N] " -n 1 -r || REPLY=""
echo
if [[ ! $REPLY =~ ^[Yy]$ ]]; then
log "Cancelled."
return 1
fi
fi
fi
# Check inter-extension dependencies
local deps="${SERVICE_DEPENDS[$service_id]:-}"
if [[ -n "$deps" ]]; then
local missing=()
for dep in $deps; do
# An installed user extension shadows the bundled definition.
local dep_cf="$INSTALL_DIR/data/user-extensions/$dep/compose.yaml"
[[ -d "$INSTALL_DIR/data/user-extensions/$dep" ]] || \
dep_cf="$INSTALL_DIR/extensions/services/$dep/compose.yaml"
local dep_cat="${SERVICE_CATEGORIES[$dep]:-optional}"
# Core services are always available; check extension deps
if [[ "$dep_cat" != "core" && ! -f "$dep_cf" ]]; then
missing+=("$dep")
fi
done
if [[ ${#missing[@]} -gt 0 ]]; then
warn "$service_id depends on disabled services: ${missing[*]}"
read -p " Enable them too? [Y/n] " -n 1 -r || REPLY=""
echo
if [[ ! $REPLY =~ ^[Nn]$ ]]; then
for dep in "${missing[@]}"; do
cmd_enable "$dep"
done
else
warn "Cancelled enabling $service_id; enable its dependencies first."
return 1
fi
fi
fi
# The helper rechecks on-disk prerequisites and commits selection under
# the same cross-process lock as CLI disable and Dashboard selection.
# It rebuilds saved flags inside that lock so concurrent writers cannot
# repopulate the cache from an outdated selection.
local selector="$INSTALL_DIR/scripts/extension-selection.py"
[[ -f "$selector" ]] || error "Extension selection guard missing: $selector"
local selector_python="${ODS_PYTHON_CMD:-python3}"
if [[ -f "$INSTALL_DIR/lib/python-cmd.sh" ]]; then
selector_python="$(. "$INSTALL_DIR/lib/python-cmd.sh"; ods_detect_python_cmd_with_module yaml)" || return 1
fi
local -a core_args=()
local sid
for sid in "${SERVICE_IDS[@]}"; do
[[ "${SERVICE_CATEGORIES[$sid]:-}" == "core" ]] && core_args+=(--core-service "$sid")
done
local final_state
final_state=$("$selector_python" "$selector" enable \
--install-dir "$INSTALL_DIR" --service-id "$service_id" \
--tier "${TIER:-1}" --gpu-backend "${GPU_BACKEND:-nvidia}" \
--gpu-count "${GPU_COUNT:-1}" --ods-mode "${ODS_MODE:-local}" \
"${core_args[@]}") || return 1
if [[ "$final_state" == "already-enabled" ]]; then
success "$service_id is already enabled."
elif [[ "$final_state" == "enabled" ]]; then
# Check if service needs a Docker build (has Dockerfile but no image)
if { [[ -f "$ext_dir/Dockerfile" ]] || [[ -f "$ext_dir/Dockerfile.rust" ]]; } && \
! docker image inspect "ods-${service_id}:latest" &>/dev/null; then
success "$service_id enabled. Image needs building first:"
echo " docker compose build $service_id && ods start $service_id"
else
success "$service_id enabled. Run 'ods start $service_id' to launch."
fi
else
error "Unexpected extension selection result for $service_id: $final_state"
fi
}
cmd_disable() {
check_install
cd "$INSTALL_DIR"
load_env
sr_load
load_env 2>/dev/null || true
local input="${1:-}"
[[ -z "$input" ]] && { log "Usage: ods disable <service>"; exit 1; }
local service_id
service_id=$(sr_resolve "$input")
# Match the Dashboard and selection helper's user-first shadowing.
local ext_dir="$INSTALL_DIR/data/user-extensions/$service_id"
[[ ! -d "$ext_dir" ]] && ext_dir="$INSTALL_DIR/extensions/services/$service_id"
[[ -d "$ext_dir" ]] || error "Unknown service: $input"
# Check it's not a core service
local cat="${SERVICE_CATEGORIES[$service_id]:-optional}"
[[ "$cat" == "core" ]] && error "Cannot disable core service: $service_id"
_ods_cli_reject_host_service "$service_id" disable "$ext_dir"
# A preliminary check avoids resolving Compose with known dependents.
# The helper repeats the check and holds its selection lock through the
# service stop and rename, so a concurrent enable cannot interleave.
local selector="$INSTALL_DIR/scripts/extension-selection.py"
[[ -f "$selector" ]] || error "Extension selection guard missing: $selector"
local selector_python="${ODS_PYTHON_CMD:-python3}"
if [[ -f "$INSTALL_DIR/lib/python-cmd.sh" ]]; then
selector_python="$(. "$INSTALL_DIR/lib/python-cmd.sh"; ods_detect_python_cmd_with_module yaml)" || return 1
fi
local initial_state
initial_state=$("$selector_python" "$selector" check-disable \
--install-dir "$INSTALL_DIR" --service-id "$service_id") || return 1
if [[ "$initial_state" == "already-disabled" ]]; then
success "$service_id is already disabled. Data preserved."
return 0
fi
local flags_str="" stop_mode=owned
if flags_str=$(get_compose_flags); then
stop_mode=compose
else
warn "Compose validation failed; stopping only existing containers verified as belonging to this installation."
fi
local -a stop_args=(--stop-mode "$stop_mode")
if [[ "$stop_mode" == compose ]]; then
stop_args+=(--compose-flags="$flags_str")
fi
local final_state
if ! final_state=$("$selector_python" "$selector" disable \
--install-dir "$INSTALL_DIR" --service-id "$service_id" \
"${stop_args[@]}"); then
return 1
fi
# The helper invalidates .compose-flags under the lock. The next Compose
# command resolves the current tree instead of writing a stale cache here.
local _data_dir="$INSTALL_DIR/data/$service_id"
if [[ -d "$_data_dir" ]]; then
local _data_size
_data_size=$(du -sh "$_data_dir" 2>/dev/null | cut -f1 || true)
success "$service_id disabled. Data preserved (${_data_size} in data/$service_id). Use 'ods purge $service_id' to delete."
else
success "$service_id disabled."
fi
}
cmd_purge() {
check_install
sr_load
if [[ $# -lt 1 ]]; then
error "Usage: ods purge <service>"
fi
local service_id
service_id=$(sr_resolve "$1")
# Validate against known service IDs
local _found=false
for _sid in "${SERVICE_IDS[@]}"; do
if [[ "$_sid" == "$service_id" ]]; then
_found=true
break
fi
done
if ! $_found; then
error "Unknown service: $service_id"
fi
# Block core services
local _cat="${SERVICE_CATEGORIES[$service_id]:-optional}"
if [[ "$_cat" == "core" ]]; then
error "Cannot purge core service data: $service_id"
fi
# Check if service is still enabled (compose.yaml exists = enabled)
# Check built-in extensions first, then dashboard-installed user extensions
local _cf="$INSTALL_DIR/extensions/services/$service_id/compose.yaml"
[[ -f "$_cf" ]] || _cf="$INSTALL_DIR/data/user-extensions/$service_id/compose.yaml"
if [[ -f "$_cf" ]]; then
error "$service_id is still enabled. Run 'ods disable $service_id' first."
fi
# Check if container is still running (disable may have failed to stop it)
local _container="${SERVICE_CONTAINERS[$service_id]:-ods-$service_id}"
local _running_containers
if ! _running_containers=$(docker ps --format '{{.Names}}'$'\t''{{.Label "com.docker.compose.service"}}'$'\t''{{.Label "com.docker.compose.project.working_dir"}}'); then
error "Cannot verify whether $service_id is running. Restore Docker connectivity and retry; data was not deleted."
fi
if cut -f1 <<< "$_running_containers" | grep -Fxq -- "$_container"; then
error "$service_id container is still running. Run 'ods stop $service_id' first."
fi
# Its companions (a database, worker or cache in the same fragment, named
# <id>-*) write the same data; one left running must block the delete too.
# Scope the refusal to this installation's directory. Recipe labels may
# name a legacy file or a frozen native recipe, or outlive their source.
# Refusing deletion must still protect those live writers; it does not
# grant authority to stop or modify any container.
local _install_real _name _companion _workdir
_install_real=$(cd -P "$INSTALL_DIR" && pwd)
while IFS=$'\t' read -r _name _companion _workdir; do
[[ "$_companion" == "$service_id"-* ]] || continue
# A separately registered extension keeps its own lifecycle and data.
[[ -n "${SERVICE_CONTAINERS[$_companion]+set}" ]] && continue
[[ "$_workdir" == "$INSTALL_DIR" || "$_workdir" == "$_install_real" ]] || continue
error "$service_id's $_companion service is still running (container $_name). Stop it first; data was not deleted."
done <<< "$_running_containers"
# Check data directory exists
local _data_dir="$INSTALL_DIR/data/$service_id"
if [[ ! -d "$_data_dir" ]]; then
log "No data directory found for $service_id."
return 0
fi
# Show size and confirm
local _data_size
_data_size=$(du -sh "$_data_dir" 2>/dev/null | cut -f1 || true)
warn "This will permanently delete all data for $service_id (${_data_size})."
warn "Directory: $_data_dir"
log ""
local _confirm
read -p " Type '$service_id' to confirm deletion: " -r _confirm || _confirm=""
if [[ "$_confirm" != "$service_id" ]]; then
log "Purge cancelled."
return 0
fi
# Delete data — try direct rm first, fall back to docker for root-owned files
rm -rf "$_data_dir" 2>/dev/null || true
if [[ -d "$_data_dir" ]]; then
log "Some files are owned by root (created by Docker). Removing via container..."
if command -v docker &>/dev/null; then
docker run --rm -v "$_data_dir:/purge-target" alpine:3.24@sha256:294b683cb724975bec92580e1e685676bd4b50bda910ddb8c51d4cabeaec77e6 \
sh -c 'rm -rf /purge-target/* /purge-target/.[!.]* 2>/dev/null; true' 2>/dev/null \
|| warn "Docker cleanup failed (non-fatal)"
rm -rf "$_data_dir" 2>/dev/null || true
fi
if [[ -d "$_data_dir" ]]; then
error "Could not fully remove $_data_dir. Try: sudo rm -rf $_data_dir"
fi
fi
success "Purged $service_id data (${_data_size} freed)."
}
cmd_list() {
local json_mode="false"
while [[ $# -gt 0 ]]; do
case "$1" in
--json) json_mode="true"; shift ;;
*) error "Unknown argument to 'ods list': $1" ;;
esac
done
sr_load
load_env 2>/dev/null || true
local active_flags
active_flags=$(get_compose_flags)
if [[ "$json_mode" == "true" ]]; then
# JSON output: array of {id, category, status}
local _first=1
printf '['
for sid in "${SERVICE_IDS[@]}"; do
local cat="${SERVICE_CATEGORIES[$sid]}"
local cf="${SERVICE_COMPOSE[$sid]}"
local status
if [[ "$cat" == "core" ]]; then
status="always-on"
elif [[ -n "$cf" && -f "$cf" && "$active_flags" == *"${cf#"$INSTALL_DIR/"}"* ]]; then
status="enabled"
else
status="disabled"
fi
(( _first == 1 )) || printf ','
printf '{"id":"%s","category":"%s","status":"%s"}' \
"$(_json_escape "$sid")" \
"$(_json_escape "$cat")" \
"$(_json_escape "$status")"
_first=0
done
printf ']\n'
return 0
fi
echo -e "${BLUE}━━━ Available Services ━━━${NC}"
printf "%-20s %-12s %-10s\n" "SERVICE" "CATEGORY" "STATUS"
printf "%-20s %-12s %-10s\n" "$(hr 20)" "$(hr 12)" "$(hr 10)"
for sid in "${SERVICE_IDS[@]}"; do
local cat="${SERVICE_CATEGORIES[$sid]}"
local cf="${SERVICE_COMPOSE[$sid]}"
local status
if [[ "$cat" == "core" ]]; then
status="always-on"
elif [[ -n "$cf" && -f "$cf" && "$active_flags" == *"${cf#"$INSTALL_DIR/"}"* ]]; then
status="enabled"
else
status="disabled"
fi
# Colour vars are blanked to "" off-TTY (lines 42-56), so no extra
# `[[ -t 1 ]]` guard is needed; padding stays consistent because ANSI
# escapes have zero display width.
local color
color=$(_status_color "$status")
printf "%-20s %-12s %s%-10s%s\n" "$sid" "$cat" "$color" "$status" "$NC"
done
}
#=============================================================================
# Preset Commands
#=============================================================================
PRESETS_DIR="${INSTALL_DIR}/presets"
# Unlike mv, rename never nests a directory inside a competing destination.
_ods_cli_rename_preset_dir() {
"$1" - "$2" "$3" <<'PY'
import os
import sys
try:
if os.path.lexists(sys.argv[2]):
raise FileExistsError("preset destination already exists")
os.rename(sys.argv[1], sys.argv[2])
except OSError as error:
print("Could not rename preset directory:", error, file=sys.stderr)
raise SystemExit(1)
PY
}
# Keep a usable preset until its replacement is completely extracted and
# validated. Staging beside the destination keeps publication on one filesystem.
_ods_cli_publish_imported_preset() (
local archive="$1" name="$2"
local preset_python="${PYTHON_CMD:-python3}"
if ! "$preset_python" -c 'import os, sys; sys.exit(sys.version_info[0] != 3)' >/dev/null 2>&1; then
warn "Safe preset import requires a working Python 3 runtime. Repair ODS's Python installation and retry; existing presets were retained."
return 1
fi
local stage previous="" published=false
stage=$(mktemp -d "$PRESETS_DIR/.import-XXXXXX") || return 1
_preset_import_cleanup() {
local status=$?
trap - EXIT
# Finish custody/cleanup decisions even if interrupted while unwinding.
trap 'status=130' INT
trap 'status=143' TERM
if [[ -n "$previous" && ( -e "$previous" || -L "$previous" ) && "$published" != true ]]; then
# A signal can land after rename but before published=true, or a
# different writer can create the destination. Never merge the
# recovery copy into that directory or discard it on ambiguity.
if [[ -e "$PRESETS_DIR/$name" || -L "$PRESETS_DIR/$name" ]]; then
warn "Preset destination exists. Recovery copy retained at: $previous"
exit 1
fi
if ! _ods_cli_rename_preset_dir "$preset_python" "$previous" "$PRESETS_DIR/$name"; then
warn "Could not restore the previous preset. Recovery copy retained at: $previous"
exit 1
fi
fi
# Cleanup failure cannot undo an already committed replacement. Keep
# its original status and identify any temporary recovery files left.
if ! rm -rf -- "$stage"; then
warn "Could not remove temporary preset import files. Retained at: $stage"
fi
exit "$status"
}
trap _preset_import_cleanup EXIT
trap 'exit 130' INT
trap 'exit 143' TERM
mkdir "$stage/payload" || return 1
tar xzf "$archive" -C "$stage/payload" 2>/dev/null || {
warn "Failed to extract archive; existing presets were retained."
return 1
}
[[ -f "$stage/payload/$name/meta.txt" ]] || { warn "Invalid preset: missing meta.txt"; return 1; }
[[ -f "$stage/payload/$name/extensions.list" ]] || { warn "Invalid preset: missing extensions.list"; return 1; }
if [[ -e "$PRESETS_DIR/$name" ]]; then
previous="$stage/previous"
_ods_cli_rename_preset_dir "$preset_python" "$PRESETS_DIR/$name" "$previous" || return 1
fi
_ods_cli_rename_preset_dir "$preset_python" "$stage/payload/$name" "$PRESETS_DIR/$name" || {
warn "Failed to publish imported preset; restoring the previous preset."
return 1
}
published=true
)
# Validate preset compatibility with current system
validate_preset_compatibility() {
local preset_dir="$1"
local preset_name="$(basename "$preset_dir")"
# Check required files
[[ -f "$preset_dir/meta.txt" ]] || { error "Invalid preset: missing meta.txt"; return 1; }
[[ -f "$preset_dir/extensions.list" ]] || { error "Invalid preset: missing extensions.list"; return 1; }
[[ -f "$preset_dir/env" ]] || { warn "Preset missing .env file (will not restore config)"; }
# Check if referenced extensions still exist
local missing_exts=()
while IFS=: read -r state sid; do
[[ -z "$sid" ]] && continue
# Match the selector's user-first shadowing.
local ext_dir="$INSTALL_DIR/data/user-extensions/$sid"
[[ -d "$ext_dir" ]] || ext_dir="$INSTALL_DIR/extensions/services/$sid"
if [[ ! -d "$ext_dir" ]]; then
missing_exts+=("$sid")
fi
done < "$preset_dir/extensions.list"
if [[ ${#missing_exts[@]} -gt 0 ]]; then
log "⚠️ Preset references extensions that are no longer available:"
for ext in "${missing_exts[@]}"; do
log " - $ext"
done
log "These extensions will be skipped during restore."
fi
return 0
}
cmd_preset() {
check_install
sr_load
validate_preset_name() {
if [[ -z "$1" || "$1" == "." || "$1" == ".." || "$1" == */* || "$1" == *\\* || "$1" == -* || "$1" =~ [[:cntrl:]] ]]; then
error "Invalid preset name: path separators, directory traversal, and leading dashes are not allowed"
fi
}
local action="${1:-list}"
local name="${2:-}"
case "$action" in
save|s|load|l|delete|rm|export|e) [[ -n "$name" ]] && validate_preset_name "$name" ;;
diff|d) [[ -n "$name" ]] && validate_preset_name "$name"; [[ -n "${3:-}" ]] && validate_preset_name "$3" ;;
esac
case "$action" in
save|s)
[[ -z "$name" ]] && { log "Usage: ods preset save <name>"; exit 1; }
local preset_dir="${PRESETS_DIR}/${name}"
mkdir -p "$preset_dir"
# Save .env (contains mode, model, and all config)
if [[ -f "$INSTALL_DIR/.env" ]]; then
cp "$INSTALL_DIR/.env" "$preset_dir/env"
fi
# Save enabled/disabled extension state
local state_file="$preset_dir/extensions.list"
: > "$state_file"
for sid in "${SERVICE_IDS[@]}"; do
local cat="${SERVICE_CATEGORIES[$sid]}"
[[ "$cat" == "core" ]] && continue
# Match restore and Dashboard: a user extension shadows the
# bundled extension with the same service ID.
local ext_dir="$INSTALL_DIR/data/user-extensions/$sid"
[[ -L "$ext_dir" ]] && error "Invalid user extension: $sid"
[[ -d "$ext_dir" ]] || ext_dir="$INSTALL_DIR/extensions/services/$sid"
if [[ -f "$ext_dir/compose.yaml" ]]; then
echo "enabled:$sid" >> "$state_file"
elif [[ -f "$ext_dir/compose.yaml.disabled" ]]; then
echo "disabled:$sid" >> "$state_file"
fi
# Host-managed services (no Compose file) have no selection
# marker; the restore helper would reject them.
done
# Save metadata
cat > "$preset_dir/meta.txt" <<META
name=$name
created=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
gpu_backend=${GPU_BACKEND:-unknown}
tier=${TIER:-unknown}
META
success "Preset '${name}' saved to presets/${name}/"
log "Contains: .env, mode, profiles, extension state"
;;
load|l)
[[ -z "$name" ]] && { log "Usage: ods preset load <name>"; exit 1; }
local preset_dir="${PRESETS_DIR}/${name}"
[[ -d "$preset_dir" ]] || error "Preset not found: $name"
echo -e "${BLUE}━━━ Loading Preset: ${name} ━━━${NC}"
# Validate preset compatibility
if ! validate_preset_compatibility "$preset_dir"; then
return 1
fi
# Show what will be restored
if [[ -f "$preset_dir/meta.txt" ]]; then
echo ""
while IFS='=' read -r key value; do
[[ -z "$key" || "$key" =~ ^# ]] && continue
echo " $key: $value"
done < "$preset_dir/meta.txt"
echo ""
fi
read -p "Restore this preset? This will overwrite current .env. [y/N] " -n 1 -r || REPLY=""
echo ""
[[ $REPLY =~ ^[Yy]$ ]] || { log "Cancelled."; return 0; }
# Restore extension states under the CLI selection lock. The helper
# validates the final dependency graph before changing any marker.
if [[ -f "$preset_dir/extensions.list" ]]; then
local selector="$INSTALL_DIR/scripts/extension-selection.py"
[[ -f "$selector" ]] || error "Extension selection guard missing: $selector"
local selector_python="${ODS_PYTHON_CMD:-python3}"
if [[ -f "$INSTALL_DIR/lib/python-cmd.sh" ]]; then
selector_python="$(. "$INSTALL_DIR/lib/python-cmd.sh"; ods_detect_python_cmd_with_module yaml)" || return 1
fi
local -a core_args=()
local sid
for sid in "${SERVICE_IDS[@]}"; do
[[ "${SERVICE_CATEGORIES[$sid]:-}" == "core" ]] && core_args+=(--core-service "$sid")
done
# Snapshot the current selected overlays before any marker move.
# Inactive external-LLM overlays must not shield an optional
# local LiteLLM container from the preset's stop operation.
local current_flags
load_env
current_flags=$(get_compose_flags) || error "Could not resolve the current Compose stack"
local counts enabled disabled
if ! counts=$("$selector_python" "$selector" restore-preset \
--install-dir "$INSTALL_DIR" --preset-file "$preset_dir/extensions.list" \
--compose-flags "$current_flags" \
"${core_args[@]}"); then
warn "Preset extension selection was not fully restored. Resolve the reported issue, then retry 'ods preset load $name'."
return 1
fi
[[ "$counts" =~ ^[0-9]+\ [0-9]+$ ]] || error "Invalid extension restore result: $counts"
read -r enabled disabled <<< "$counts"
success "Extensions: $enabled enabled, $disabled disabled"
fi
# Apply environment settings only after extension selection passed.
# A malformed preset must not overwrite an otherwise working .env.
if [[ -f "$preset_dir/env" ]]; then
if ! cp "$preset_dir/env" "$INSTALL_DIR/.env"; then
warn "Extensions were selected, but preset .env could not be restored. Resolve the file error and retry 'ods preset load $name'."
return 1
fi
# The restored mode/config can change the resolved stack even
# when no extension marker changes.
if ! rm -f "$INSTALL_DIR/.compose-flags"; then
warn "Preset .env was restored, but Compose cache could not be cleared. Repair access to .compose-flags before starting ODS."
return 1
fi
local restored_mode
restored_mode=$(grep "^ODS_MODE=" "$INSTALL_DIR/.env" 2>/dev/null | cut -d= -f2 || true)
success "Restored .env (mode: ${restored_mode:-local})"
fi
echo ""
success "Preset '${name}' loaded."
log "Run 'ods start' to apply changes."
;;
list|ls)
echo -e "${BLUE}━━━ Saved Presets ━━━${NC}"
if [[ ! -d "$PRESETS_DIR" ]] || [[ -z "$(ls -A "$PRESETS_DIR" 2>/dev/null)" ]]; then
echo " No presets saved yet."
echo ""
echo " Create one with: ods preset save <name>"
return 0
fi
printf " %-20s %-22s %-10s\n" "NAME" "CREATED" "BACKEND"
printf " %-20s %-22s %-10s\n" "$(hr 20)" "$(hr 22)" "$(hr 10)"
for dir in "$PRESETS_DIR"/*/; do
[[ -d "$dir" ]] || continue
local pname
pname=$(basename "$dir")
local created="" backend=""
if [[ -f "$dir/meta.txt" ]]; then
# A malformed meta.txt should not abort listing the rest
# of the presets under pipefail.
created=$(grep "^created=" "$dir/meta.txt" 2>/dev/null | cut -d= -f2 | cut -dT -f1 || true)
backend=$(grep "^gpu_backend=" "$dir/meta.txt" 2>/dev/null | cut -d= -f2 || true)
fi
printf " %-20s %-22s %-10s\n" "$pname" "${created:-unknown}" "${backend:-unknown}"
done
;;
delete|rm)
[[ -z "$name" ]] && { log "Usage: ods preset delete <name>"; exit 1; }
local preset_dir="${PRESETS_DIR}/${name}"
[[ -d "$preset_dir" ]] || error "Preset not found: $name"
read -p "Delete preset '${name}'? [y/N] " -n 1 -r || REPLY=""
echo ""
[[ $REPLY =~ ^[Yy]$ ]] || { log "Cancelled."; return 0; }
rm -rf "$preset_dir"
success "Preset '${name}' deleted."
;;
export|e)
[[ -z "$name" ]] && { log "Usage: ods preset export <name> <output.tar.gz>"; exit 1; }
local output="${3:-}"
[[ -z "$output" ]] && { log "Usage: ods preset export <name> <output.tar.gz>"; exit 1; }
local preset_dir="${PRESETS_DIR}/${name}"
[[ -d "$preset_dir" ]] || error "Preset not found: $name"
# Validate preset has required files
[[ -f "$preset_dir/meta.txt" ]] || error "Invalid preset: missing meta.txt"
[[ -f "$preset_dir/extensions.list" ]] || error "Invalid preset: missing extensions.list"
log "Exporting preset '${name}'..."
# Resolve relative output path before cd changes the working directory
if [[ "$output" != /* ]]; then
output="$(pwd)/$output"
fi
# Create archive (relative to presets dir to avoid absolute paths)
cd "$PRESETS_DIR"
if (
umask 077
staged_archive="$(mktemp "${output}.XXXXXX")" || exit 1
trap 'rm -f -- "$staged_archive"' EXIT
trap 'exit 130' INT
trap 'exit 143' TERM
# Finish privately before replacing an existing public file.
chmod 600 "$staged_archive" || exit 1
tar czf "$staged_archive" "$name" 2>/dev/null || exit 1
[[ ! -d "$output" ]] || exit 1
mv -f -- "$staged_archive" "$output"
); then
local size
size=$(du -h "$output" 2>/dev/null | cut -f1 || true)
success "Preset exported to: $output ($size)"
else
error "Failed to create archive"
fi
cd "$INSTALL_DIR"
;;
import|i)
local archive="${2:-}"
[[ -z "$archive" ]] && { log "Usage: ods preset import <preset.tar.gz>"; exit 1; }
[[ -f "$archive" ]] || error "Archive not found: $archive"
log "Validating archive..."
# Security: Check for path traversal
if tar tzf "$archive" 2>/dev/null | grep -qE '(^/|\.\./|\.\.\\)'; then
error "Archive contains unsafe paths (absolute or ../) — refusing to import"
fi
# Validate archive structure
local archive_name
archive_name=$(tar tzf "$archive" 2>/dev/null | sed -n '1p' | cut -d/ -f1)
[[ -z "$archive_name" ]] && error "Invalid archive structure"
# Check if preset already exists
if [[ -d "${PRESETS_DIR}/${archive_name}" ]]; then
warn "Preset '${archive_name}' already exists"
read -p "Overwrite? [y/N] " -n 1 -r || REPLY=""
echo ""
[[ $REPLY =~ ^[Yy]$ ]] || { log "Cancelled."; return 0; }
fi
# Resolve before staging changes tar's extraction directory.
[[ "$archive" == /* ]] || archive="$(pwd)/$archive"
mkdir -p "$PRESETS_DIR"
if _ods_cli_publish_imported_preset "$archive" "$archive_name"; then
success "Preset '${archive_name}' imported successfully"
log "Use 'ods preset load ${archive_name}' to apply it"
else
error "Preset import failed"
fi
;;
diff|d)
local preset1="${2:-}"
local preset2="${3:-}"
# Validate arguments
if [[ -z "$preset1" ]] || [[ -z "$preset2" ]]; then
error "Usage: ods preset diff <preset1> <preset2>"
fi
local dir1="$PRESETS_DIR/$preset1"
local dir2="$PRESETS_DIR/$preset2"
# Check both presets exist
[[ -d "$dir1" ]] || error "Preset '$preset1' not found"
[[ -d "$dir2" ]] || error "Preset '$preset2' not found"
log "Comparing presets: ${CYAN}$preset1${NC} vs ${CYAN}$preset2${NC}"
echo ""
# Compare metadata
echo -e "${BLUE}━━━ Metadata ━━━${NC}"
if [[ -f "$dir1/meta.txt" ]] && [[ -f "$dir2/meta.txt" ]]; then
diff -u "$dir1/meta.txt" "$dir2/meta.txt" | tail -n +4 | sed "s/^-/$(printf "${RED}-${NC}")/" | sed "s/^+/$(printf "${GREEN}+${NC}")/" || true
fi
echo ""
# Compare extensions
echo -e "${BLUE}━━━ Service State ━━━${NC}"
if [[ -f "$dir1/extensions.list" ]] && [[ -f "$dir2/extensions.list" ]]; then
# Parse both files into associative arrays
declare -A ext1 ext2
while IFS=: read -r state sid; do
[[ -n "$sid" ]] && ext1["$sid"]="$state"
done < "$dir1/extensions.list"
while IFS=: read -r state sid; do
[[ -n "$sid" ]] && ext2["$sid"]="$state"
done < "$dir2/extensions.list"
# Find all unique service IDs
local all_sids=()
for sid in "${!ext1[@]}"; do all_sids+=("$sid"); done
for sid in "${!ext2[@]}"; do
[[ -z "${ext1[$sid]:-}" ]] && all_sids+=("$sid")
done
# Sort and compare
local has_diff=false
for sid in $(printf '%s\n' "${all_sids[@]}" | sort); do
local state1="${ext1[$sid]:-missing}"
local state2="${ext2[$sid]:-missing}"
if [[ "$state1" != "$state2" ]]; then
has_diff=true
if [[ "$state1" == "missing" ]]; then
echo -e " ${GREEN}+${NC} $sid: $state2"
elif [[ "$state2" == "missing" ]]; then
echo -e " ${RED}-${NC} $sid: $state1"
else
echo -e " ${YELLOW}~${NC} $sid: $state1 → $state2"
fi
fi
done
[[ "$has_diff" == "false" ]] && echo " (no differences)"
fi
echo ""
# Compare environment variables
echo -e "${BLUE}━━━ Environment Variables ━━━${NC}"
if [[ -f "$dir1/env" ]] && [[ -f "$dir2/env" ]]; then
# Load secret schema so `_cmd_config_is_secret` below can consult
# .env.schema.json instead of the narrow regex the old version
# used (which missed _PASS, _SALT, email admin fields, etc.).
_cmd_config_load_secret_schema
# Parse both env files
declare -A env1 env2
while IFS='=' read -r key value; do
[[ "$key" =~ ^[[:space:]]*# ]] && continue
[[ -z "$key" ]] && continue
env1["$key"]="$value"
done < "$dir1/env"
while IFS='=' read -r key value; do
[[ "$key" =~ ^[[:space:]]*# ]] && continue
[[ -z "$key" ]] && continue
env2["$key"]="$value"
done < "$dir2/env"
# Find all unique keys
local all_keys=()
for key in "${!env1[@]}"; do all_keys+=("$key"); done
for key in "${!env2[@]}"; do
[[ -z "${env1[$key]:-}" ]] && all_keys+=("$key")
done
# Sort and compare (mask secrets)
local has_diff=false
for key in $(printf '%s\n' "${all_keys[@]}" | sort); do
local val1="${env1[$key]:-}"
local val2="${env2[$key]:-}"
# Check if values differ BEFORE masking
if [[ "$val1" != "$val2" ]]; then
has_diff=true
# Mask sensitive values for display
if _cmd_config_is_secret "$key"; then
[[ -n "$val1" ]] && val1="***"
[[ -n "$val2" ]] && val2="***"
fi
if [[ -z "$val1" ]]; then
echo -e " ${GREEN}+${NC} $key=$val2"
elif [[ -z "$val2" ]]; then
echo -e " ${RED}-${NC} $key=$val1"
else
echo -e " ${YELLOW}~${NC} $key: $val1 → $val2"
fi
fi
done
[[ "$has_diff" == "false" ]] && echo " (no differences)"
fi
echo ""
;;
*)
cat <<EOF
Usage: ods preset <command> [args]
Commands:
save <name> Save current configuration as a preset
load <name> Load a preset (restores .env and service state)
list List all saved presets
delete <name> Delete a preset
export <name> <file> Export preset to .tar.gz archive
import <file> Import preset from .tar.gz archive
diff <preset1> <preset2> Compare two presets and show differences
Examples:
ods preset save gaming
ods preset load gaming
ods preset diff gaming production
ods preset export gaming ~/gaming-preset.tar.gz
EOF
;;
esac
}
#=============================================================================
# Mode Switch Commands (M1 Zero-Cloud Phase 3)
#=============================================================================
cmd_mode() {
check_install; cd "$INSTALL_DIR"
load_env || true
local mode="${1:-}"
local configured_backend
configured_backend=$(grep -m1 "^LLM_BACKEND=" .env 2>/dev/null | cut -d= -f2- | tr -d '"\047\r' || true)
if [[ -z "$mode" ]]; then
# Show current mode
local current=$(grep "^ODS_MODE=" .env 2>/dev/null | cut -d= -f2 || true)
current="${current:-local}"
local api_url=$(grep "^LLM_API_URL=" .env 2>/dev/null | cut -d= -f2 || true)
local model=$(grep "^LLM_MODEL=" .env 2>/dev/null | cut -d= -f2 || true)
local tier=$(grep "^TIER=" .env 2>/dev/null | cut -d= -f2 || true)
local engine="llama-server"
[[ "${configured_backend,,}" != "vllm" ]] || engine="vLLM engine (vllm-server)"
echo -e "${BLUE}━━━ ODS Mode ━━━${NC}"
echo ""
echo -e "Current mode: ${GREEN}${current}${NC}"
[[ -n "$api_url" ]] && echo "LLM_API_URL: $api_url"
[[ -n "$model" ]] && echo "Model: $model"
[[ -n "$tier" ]] && echo "Tier: $tier"
echo ""
case "$current" in
cloud)
echo " LLM: LiteLLM → Cloud APIs (Claude, GPT-4, etc.)"
echo " Cost: ~\$0.003-0.06/1K tokens"
;;
local)
echo " LLM: Local $engine"
echo " Cost: \$0 (electricity only)"
;;
hybrid)
echo " LLM: Local $engine → Cloud fallback on failure"
echo " Cost: \$0 when local works, cloud rates on fallback"
;;
esac
echo ""
echo -e "${CYAN}Available modes:${NC}"
echo " local — Local inference via llama-server (requires GPU/CPU)"
echo " cloud — Cloud APIs via LiteLLM (requires API keys)"
echo " hybrid — Local primary, cloud fallback"
echo ""
echo "Usage: ods mode <local|cloud|hybrid>"
return 0
fi
case "$mode" in
local|cloud|hybrid) ;;
*) error "Unknown mode: $mode. Use: local, cloud, hybrid" ;;
esac
if [[ "${configured_backend,,}" == "external" ]]; then
# Fleet row 4: "installer-managed" did not say what to do or where.
echo -e "${RED}✗${NC} ODS is in API mode, which only the installer turns on and off. Nothing was changed." >&2
echo " Rerun the ODS installer with --no-external-llm (Windows: -NoExternalLlm), then run 'ods mode $mode' again." >&2
echo " Need help? Ask on the ODS Discord: https://discord.gg/4ntNp9MAwC" >&2
exit 1
fi
if [[ "${configured_backend,,}" == "vllm" && "$mode" != "local" ]]; then
# Cloud mode has no local model server, and the resolver refuses the
# vLLM engine with it; hybrid mode was never proven with vLLM.
echo -e "${RED}✗${NC} ODS runs this model on the vLLM engine, which works only in local mode. Nothing was changed." >&2
echo " To use $mode mode, run the ODS installer again without the vLLM engine." >&2
echo " Need help? Ask on the ODS Discord: https://discord.gg/4ntNp9MAwC" >&2
exit 1
fi
# Update .env
_env_set "ODS_MODE" "$mode"
local api_url
if [[ "$mode" == "local" ]]; then
local switchboard_mode native_llm
switchboard_mode=$(grep -m1 "^ODS_MODEL_SWITCHBOARD=" .env 2>/dev/null | cut -d= -f2- | tr -d '"\047\r' || true)
native_llm=$(grep -m1 "^NATIVE_LLM_BASE_URL=" .env 2>/dev/null | cut -d= -f2- | tr -d '"\047\r' || true)
# A host-native llama-server install and a vLLM install keep the
# in-stack llama-server off; LiteLLM is what reaches the model
# (06-directories.sh), through model-router for vLLM.
local llama_off="false"
[[ -n "$native_llm" || "${configured_backend,,}" == "vllm" ]] && llama_off="true"
if [[ "$llama_off" == "true" ]]; then
api_url="http://litellm:4000"
else
api_url="http://llama-server:8080"
fi
_env_set "LLM_API_URL" "$api_url"
if [[ "${switchboard_mode,,}" == "enabled" ]]; then
_env_set "HERMES_LLM_BASE_URL" "http://model-router:9099/v1"
_env_set "HERMES_LLM_API_KEY" "no-key"
elif [[ "$llama_off" == "true" ]]; then
_env_set "HERMES_LLM_BASE_URL" "http://litellm:4000/v1"
if [[ -n "${LITELLM_KEY:-}" ]]; then
_env_set "HERMES_LLM_API_KEY" "$LITELLM_KEY"
fi
else
_env_set "HERMES_LLM_BASE_URL" "http://llama-server:8080/v1"
_env_set "HERMES_LLM_API_KEY" "sk-ods-hermes-local"
fi
else
api_url="http://litellm:4000"
_env_set "LLM_API_URL" "$api_url"
_env_set "HERMES_LLM_BASE_URL" "http://litellm:4000/v1"
if [[ -n "${LITELLM_KEY:-}" ]]; then
_env_set "HERMES_LLM_API_KEY" "$LITELLM_KEY"
fi
# Auto-enable litellm
local litellm_cf="$INSTALL_DIR/extensions/services/litellm/compose.yaml"
local litellm_disabled="${litellm_cf}.disabled"
if [[ -f "$litellm_disabled" && ! -f "$litellm_cf" ]]; then
mv "$litellm_disabled" "$litellm_cf"
success "Auto-enabled litellm for $mode mode"
fi
# Check for API keys
local has_keys=false
grep -q "^ANTHROPIC_API_KEY=." .env 2>/dev/null && has_keys=true
grep -q "^OPENAI_API_KEY=." .env 2>/dev/null && has_keys=true
if [[ "$has_keys" == "false" ]]; then
warn "No API keys found in .env — add ANTHROPIC_API_KEY or OPENAI_API_KEY"
fi
fi
echo -e "${BLUE}━━━ Mode updated ━━━${NC}"
echo " ODS_MODE = $mode"
echo " LLM_API_URL = $api_url"
load_env || true
_regenerate_compose_flags
success "Switched to $mode mode. Run 'ods restart' to apply."
}
cmd_model() {
check_install; cd "$INSTALL_DIR"
local subcmd="${1:-current}"
case "$subcmd" in
current)
local model=$(grep "^LLM_MODEL=" .env 2>/dev/null | cut -d= -f2 || true)
local tier=$(grep "^TIER=" .env 2>/dev/null | cut -d= -f2 || true)
echo -e "Current model: ${GREEN}${model:-<not set>}${NC}"
[[ -n "$tier" ]] && echo "Current tier: $tier"
return 0
;;
list)
# Resolve every tier with the same tier map `swap` uses, so the
# list shows exactly what a swap would load.
local list_tier list_line
echo -e "${BLUE}━━━ Available Tiers ━━━${NC}"
for list_tier in T0 T1 T2 T3 T4 SH SH_LARGE NV_ULTRA ARC ARC_LITE; do
list_line="$(
. "$INSTALL_DIR/installers/lib/tier-map.sh"
TIER="$list_tier"
[[ "$TIER" =~ ^T([0-9]+)$ ]] && TIER="${BASH_REMATCH[1]}"
[[ "$TIER" == "SH" ]] && TIER="SH_COMPACT"
resolve_tier_config >/dev/null
downloaded=""
[[ -s "$INSTALL_DIR/data/models/$GGUF_FILE" ]] && downloaded=" [downloaded]"
printf ' %-10s %-22s %s%s' "$list_tier" "$LLM_MODEL" "$TIER_NAME" "$downloaded"
)" || error "Could not resolve tier $list_tier from the tier map"
echo "$list_line"
done
echo ""
echo "Usage: ods model swap <tier> (the tier's model file must already be downloaded)"
;;
swap)
local tier="${2:-}"
[[ -z "$tier" ]] && error "Usage: ods model swap <T0|T1|T2|T3|T4|SH|SH_LARGE|NV_ULTRA|ARC|ARC_LITE>"
tier=$(echo "$tier" | tr '[:lower:]' '[:upper:]')
# Source tier-map and resolve full config (model, GGUF, context)
. "$INSTALL_DIR/installers/lib/tier-map.sh"
local model
model=$(tier_to_model "$tier")
[[ -z "$model" ]] && error "Unknown tier: $tier"
# Normalize aliases for resolve_tier_config (T0→0, T1→1, SH→SH_COMPACT)
TIER="$tier"
[[ "$TIER" =~ ^T([0-9]+)$ ]] && TIER="${BASH_REMATCH[1]}"
[[ "$TIER" == "SH" ]] && TIER="SH_COMPACT"
resolve_tier_config
local model_path="$INSTALL_DIR/data/models/$GGUF_FILE"
[[ -s "$model_path" ]] || error "Model file is not downloaded: $model_path"
command -v jq >/dev/null 2>&1 || \
error "jq is required to resolve the tier model catalog entry"
local model_id=""
local library="$INSTALL_DIR/config/model-library.json"
[[ -f "$library" ]] || error "Model catalog is missing: $library"
model_id=$(jq -r --arg file "$GGUF_FILE" \
'[.models[]? | select(.gguf_file == $file) | .id][0] // empty' \
"$library" 2>/dev/null || true)
[[ -n "$model_id" ]] || \
error "Tier model is missing from the model catalog: $GGUF_FILE"
local agent_key
agent_key="$(_env_get_raw ODS_AGENT_KEY)"
[[ -z "$agent_key" ]] && \
agent_key="$(_env_get_raw DASHBOARD_API_KEY)"
case "$agent_key" in
\"*\") agent_key="${agent_key:1:${#agent_key}-2}" ;;
\'*\') agent_key="${agent_key:1:${#agent_key}-2}" ;;
esac
[[ -n "$agent_key" ]] || error "ODS host-agent API key is missing from .env"
[[ "$agent_key" != *$'\n'* && "$agent_key" != *$'\r'* ]] || \
error "ODS host-agent API key contains invalid newline characters"
local agent_port agent_host
agent_port="$(_env_get_raw ODS_AGENT_PORT)"
[[ "$agent_port" =~ ^[0-9]+$ ]] || agent_port="7710"
agent_host="$(_agent_probe_host)"
local activate_url="http://${agent_host}:${agent_port}/v1/model/activate"
if ! curl -sf --max-time 3 "http://${agent_host}:${agent_port}/health" >/dev/null; then
error "ODS host agent is not reachable. Run 'ods agent restart' and retry."
fi
local request_json response_file http_code curl_status
request_json=$(jq -nc \
--arg model_id "$model_id" \
--arg tier "$TIER" \
--argjson context_length "$MAX_CONTEXT" \
'{model_id: $model_id, tier: $tier, context_length: $context_length}') || \
error "Could not build the model activation request"
response_file=$(mktemp "${TMPDIR:-/tmp}/ods-model-activate.XXXXXX") || \
error "Could not create a model activation response file"
chmod 600 "$response_file"
trap 'rm -f "$response_file"' INT TERM HUP
# Feed the bearer header over stdin so the key is never exposed in
# process arguments or left in a temporary file after interruption.
if http_code=$(printf 'Authorization: Bearer %s\n' "$agent_key" | \
curl --silent --show-error --max-time 2700 \
--output "$response_file" --write-out '%{http_code}' \
--request POST --header @- \
--header 'Content-Type: application/json' \
--data "$request_json" "$activate_url"); then
curl_status=0
else
curl_status=$?
fi
if [[ $curl_status -ne 0 ]]; then
rm -f "$response_file"
trap - INT TERM HUP
error "Model activation request failed before the host agent completed"
fi
if [[ "$http_code" != "200" ]]; then
local activation_error
activation_error=$(jq -r '.error // empty' "$response_file" 2>/dev/null || true)
[[ -z "$activation_error" ]] && activation_error=$(head -c 500 "$response_file")
rm -f "$response_file"
trap - INT TERM HUP
error "Model activation failed (HTTP $http_code): ${activation_error:-unknown error}"
fi
if [[ "$(jq -r '.status // empty' "$response_file" 2>/dev/null)" != "activated" ]]; then
rm -f "$response_file"
trap - INT TERM HUP
error "Host agent returned an invalid model activation receipt"
fi
local effective_context effective_tier
effective_context=$(jq -r '.context_length // empty' "$response_file" 2>/dev/null || true)
effective_tier=$(jq -r '.tier // empty' "$response_file" 2>/dev/null || true)
rm -f "$response_file"
trap - INT TERM HUP
success "Model activated everywhere: $model (tier ${effective_tier:-$tier}, ctx=${effective_context:-$MAX_CONTEXT})."
;;
recover)
# The dashboard's "Recover model switch" for an interrupted Portal
# model switch. --release-unverified releases a switch that
# changed nothing when its previous model cannot be proven (fleet
# row 27); the agent refuses it for any other switch.
command -v curl >/dev/null 2>&1 || error "curl is required for 'ods model recover'"
command -v jq >/dev/null 2>&1 || error "jq is required for 'ods model recover'"
local body='{}' response_file payload_file http_code phase
case "${2:-}" in
"") ;;
--release-unverified) body='{"releaseUnverified":true}' ;;
*) error "Usage: ods model recover [--release-unverified]" ;;
esac
response_file="$(mktemp)"; payload_file="$(mktemp)"
printf '%s' "$body" > "$payload_file"
http_code="$(_remote_provider_request POST /api/models/recovery "$response_file" "$payload_file" 410)" || http_code=""
rm -f "$payload_file"
phase="$(jq -r '.phase // empty' "$response_file" 2>/dev/null || true)"
if [[ "$http_code" == 200 ]]; then
rm -f "$response_file"
if [[ "$phase" == idle ]]; then
success "No model switch is waiting for recovery."
else
success "The interrupted model switch was finished; Portal can change models again."
fi
return 0
fi
echo -e "${RED}✗${NC} $(
if [[ "$http_code" != 409 ]]; then
echo "Recovery could not be confirmed${http_code:+ (HTTP $http_code)}. Run 'ods model recover' again in a minute."
elif jq -e '.reason == "model-recovery-proof-required" and .releasable == true' "$response_file" >/dev/null 2>&1; then
echo "ODS could not confirm the model Portal used before this switch, so it cannot finish the switch the usual way."
else
echo "The interrupted switch still needs repair. The saved state has been kept."
fi)" >&2
if [[ "$http_code" == 409 ]] \
&& jq -e '.reason == "model-recovery-proof-required" and .releasable == true' "$response_file" >/dev/null 2>&1; then
echo " The switch did not change anything. To release it and put Portal back on the model settings it had before, run:" >&2
echo " ods model recover --release-unverified" >&2
fi
rm -f "$response_file"
echo " Need help? Ask on the ODS Discord: https://discord.gg/4ntNp9MAwC" >&2
exit 1
;;
*)
error "Usage: ods model <current|list|swap|recover>"
;;
esac
}
_agent_probe_host() {
local bind_addr="" gateway="" kernel_release=""
bind_addr="$(_env_get_raw ODS_AGENT_BIND)"
bind_addr="${bind_addr#\"}"; bind_addr="${bind_addr%\"}"
bind_addr="${bind_addr#\'}"; bind_addr="${bind_addr%\'}"
bind_addr="$(printf '%s' "$bind_addr" | tr -d '[:space:]')"
if [[ -z "$bind_addr" && "$(uname -s)" == "Linux" ]]; then
kernel_release="$(uname -r 2>/dev/null | tr '[:upper:]' '[:lower:]' || true)"
if [[ "$kernel_release" == *microsoft* ]]; then
# The host agent deliberately binds loopback under WSL because
# Docker Desktop forwards host.docker.internal there; its compose
# gateway is not a locally bindable host-agent address.
bind_addr="127.0.0.1"
elif command -v docker >/dev/null 2>&1; then
gateway="$(docker network inspect ods-network \
--format '{{range .IPAM.Config}}{{if .Gateway}}{{println .Gateway}}{{end}}{{end}}' \
2>/dev/null | sed '/^[[:space:]]*$/d' | head -n1 | tr -d '[:space:]' || true)"
if [[ -z "$gateway" ]]; then
gateway="$(docker network inspect bridge \
--format '{{range .IPAM.Config}}{{if .Gateway}}{{println .Gateway}}{{end}}{{end}}' \
2>/dev/null | sed '/^[[:space:]]*$/d' | head -n1 | tr -d '[:space:]' || true)"
fi
bind_addr="$gateway"
fi
fi
case "$bind_addr" in
""|0.0.0.0|"*") bind_addr="127.0.0.1" ;;
::|"[::]") bind_addr="[::1]" ;;
*:*)
[[ "$bind_addr" == \[*\] ]] || bind_addr="[$bind_addr]"
;;
esac
printf '%s\n' "$bind_addr"
}
_strip_outer_quotes() {
local value="${1:-}"
case "$value" in
\"*\") value="${value:1:${#value}-2}" ;;
\'*\') value="${value:1:${#value}-2}" ;;
esac
printf '%s' "$value"
}
_dashboard_api_key() {
local api_key=""
api_key="$(_env_get_raw DASHBOARD_API_KEY)"
if [[ -z "$api_key" && -f "$INSTALL_DIR/data/dashboard-api-key.txt" ]]; then
api_key="$(cat "$INSTALL_DIR/data/dashboard-api-key.txt" 2>/dev/null || true)"
fi
api_key="$(_strip_outer_quotes "$api_key")"
api_key="$(printf '%s' "$api_key" | tr -d '\r\n ')"
printf '%s' "$api_key"
}
_dashboard_api_base_url() {
local base_url="${ODS_DASHBOARD_API_URL:-}"
if [[ -z "$base_url" ]]; then
base_url="$(_env_get_raw ODS_DASHBOARD_API_URL)"
fi
if [[ -z "$base_url" ]]; then
local port
port="$(_env_get_raw DASHBOARD_API_PORT)"
[[ "$port" =~ ^[0-9]+$ ]] || port="3002"
base_url="http://127.0.0.1:${port}"
fi
base_url="$(_strip_outer_quotes "$base_url")"
printf '%s' "${base_url%/}"
}
_remote_provider_usage() {
cat <<'EOF'
Usage: ods remote-provider <command> [options]
Commands:
status [--json]
Show sanitized remote-provider route, egress, and action status.
plan <configure|test|enable|disable|remove> [options]
Print the redacted lifecycle plan without mutating state.
configure --base-url URL --model MODEL [secret options]
Persist an OpenAI-compatible provider route and provider API key.
test [--json]
Probe the configured provider route through the internal egress service.
test --base-url URL --model MODEL [secret options]
Probe a provider without writing route state or secrets.
enable [--json]
Re-prove and reactivate the saved route without re-entering secrets.
disable
Pause the remote-provider route while keeping its profile and secrets.
remove
Delete remote-provider route state and stored secrets.
peer-models list [--json]
List models from the authenticated remote ODS peer.
peer-models download-status [--json]
Show remote peer model download status.
peer-models download MODEL [--json]
Start a model download on the remote ODS peer.
peer-models load MODEL [--json]
Load a downloaded model on the remote ODS peer.
peer-models cancel-download [--json]
Cancel an active remote peer model download.
peer-models delete MODEL --yes [--json]
Delete a downloaded model from the remote ODS peer.
Provider options for configure/test/plan configure/plan test:
--transport direct|ssh Provider transport (default direct)
--base-url URL OpenAI-compatible base URL, for example https://gpu.example/v1
--model MODEL Provider model id
--context-length TOKENS Exact provider context window (default 32768)
--max-tokens TOKENS Exact provider output limit; Portal writes each file in one reply
(default a quarter of the context window, at most 32768)
--reasoning true|false Whether the provider route supports reasoning (default false)
--ssh-host HOST SSH server host for ssh transport
--ssh-user USER SSH server user for ssh transport
--ssh-port PORT SSH server port for ssh transport (default 22)
--ssh-inference-host HOST
Remote-side inference host reached through the SSH tunnel
--ssh-inference-port PORT
Remote-side inference port reached through the SSH tunnel
--ssh-control-host HOST
Optional remote-side ODS control host reached through the SSH tunnel
--ssh-control-port PORT
Optional remote-side ODS control port reached through the SSH tunnel
Secret options for configure/test/plan configure/plan test:
--api-key-stdin Read the provider API key from the first stdin line
--api-key-file PATH Read the provider API key from a local file
--api-key-env NAME Read the provider API key from the process environment (default REMOTE_LLM_API_KEY)
--ssh-private-key-file PATH
Read the SSH private key from a local file for ssh transport
--ssh-private-key-env NAME
Read the SSH private key from the process environment (default REMOTE_LLM_SSH_PRIVATE_KEY)
--ssh-known-hosts-file PATH
Read SSH known_hosts content from a local file for ssh transport
--ssh-known-hosts-env NAME
Read SSH known_hosts content from the process environment (default REMOTE_LLM_SSH_KNOWN_HOSTS)
Raw secret arguments are intentionally unsupported so secrets do not appear in
process listings or shell history.
EOF
}
_remote_provider_require_tools() {
command -v curl >/dev/null 2>&1 || error "curl is required for remote-provider lifecycle commands"
command -v jq >/dev/null 2>&1 || error "jq is required for remote-provider lifecycle commands"
}
_remote_provider_request() {
local method="$1" path="$2" response_file="$3" payload_file="${4:-}" timeout="${5:-15}"
local api_key base_url curl_status
api_key="$(_dashboard_api_key)"
[[ -n "$api_key" ]] || error "Dashboard API key is missing from .env or data/dashboard-api-key.txt"
[[ "$api_key" != *$'\n'* && "$api_key" != *$'\r'* ]] || \
error "Dashboard API key contains invalid newline characters"
base_url="$(_dashboard_api_base_url)"
if [[ -n "$payload_file" ]]; then
if printf 'Authorization: Bearer %s\n' "$api_key" | \
curl --silent --show-error --max-time "$timeout" \
--output "$response_file" --write-out '%{http_code}' \
--request "$method" --header @- \
--header 'Content-Type: application/json' \
--data-binary @"$payload_file" "${base_url}${path}"; then
curl_status=0
else
curl_status=$?
fi
else
if printf 'Authorization: Bearer %s\n' "$api_key" | \
curl --silent --show-error --max-time "$timeout" \
--output "$response_file" --write-out '%{http_code}' \
--request "$method" --header @- "${base_url}${path}"; then
curl_status=0
else
curl_status=$?
fi
fi
return "$curl_status"
}
_remote_provider_response_error() {
local response_file="$1"
local detail=""
detail="$(jq -r '
if (.detail | type) == "object" then
.detail.message // .detail.type // (.detail | tojson)
elif (.detail // "") != "" then
.detail
elif (.error | type) == "object" then
.error.message // .error.type // (.error | tojson)
else
.error // empty
end
' "$response_file" 2>/dev/null || true)"
if [[ -z "$detail" ]]; then
detail="$(head -c 500 "$response_file" 2>/dev/null || true)"
fi
printf '%s' "${detail:-unknown error}"
}
_remote_provider_read_secret() {
local use_stdin="$1" file="$2" env_name="$3" api_key=""
if [[ "$use_stdin" == "true" ]]; then
IFS= read -r api_key || true
elif [[ -n "$file" ]]; then
[[ -f "$file" ]] || error "Provider API key file not found: $file"
api_key="$(cat "$file")"
else
[[ "$env_name" =~ ^[A-Za-z_][A-Za-z0-9_]*$ ]] || \
error "--api-key-env must be a valid environment variable name"
api_key="${!env_name:-}"
fi
api_key="$(_strip_outer_quotes "$api_key")"
api_key="${api_key%$'\n'}"
api_key="${api_key%$'\r'}"
[[ -n "$api_key" ]] || error "Provider API key is required; use --api-key-stdin, --api-key-file, or --api-key-env"
[[ "$api_key" != *$'\n'* && "$api_key" != *$'\r'* ]] || \
error "Provider API key must be a single-line secret"
printf '%s' "$api_key"
}
_remote_provider_read_multiline_secret() {
local label="$1" file="$2" env_name="$3" file_option="$4" env_option="$5" value=""
if [[ -n "$file" ]]; then
[[ -f "$file" ]] || error "$label file not found: $file"
value="$(cat "$file")"
else
[[ "$env_name" =~ ^[A-Za-z_][A-Za-z0-9_]*$ ]] || \
error "$env_option must be a valid environment variable name"
value="${!env_name:-}"
fi
value="$(_strip_outer_quotes "$value")"
[[ -n "$value" ]] || error "$label is required; use $file_option or $env_option"
printf '%s' "$value"
}
_remote_provider_write_payload() {
local action="$1" payload_file="$2"
shift 2
local transport="direct" base_url="" model="" json_mode="false"
local context_length="32768" max_tokens="" max_tokens_explicit="false" reasoning="false"
local api_key_env="REMOTE_LLM_API_KEY" api_key_env_explicit="false" api_key_file="" api_key_stdin="false"
local ssh_host="" ssh_user="" ssh_port="22" ssh_inference_host="" ssh_inference_port=""
local ssh_control_host="" ssh_control_port="" ssh_option_seen="false"
local ssh_private_key_env="REMOTE_LLM_SSH_PRIVATE_KEY" ssh_private_key_env_explicit="false" ssh_private_key_file=""
local ssh_known_hosts_env="REMOTE_LLM_SSH_KNOWN_HOSTS" ssh_known_hosts_env_explicit="false" ssh_known_hosts_file=""
local provider_option_seen="false" secret_option_seen="false"
while [[ $# -gt 0 ]]; do
case "$1" in
--transport)
[[ $# -ge 2 ]] || error "--transport requires a value"
provider_option_seen="true"
transport="${2:-}"; shift 2 ;;
--base-url)
[[ $# -ge 2 ]] || error "--base-url requires a value"
provider_option_seen="true"
base_url="${2:-}"; shift 2 ;;
--model)
[[ $# -ge 2 ]] || error "--model requires a value"
provider_option_seen="true"
model="${2:-}"; shift 2 ;;
--context-length)
[[ $# -ge 2 ]] || error "--context-length requires a value"
provider_option_seen="true"
context_length="${2:-}"; shift 2 ;;
--max-tokens)
[[ $# -ge 2 ]] || error "--max-tokens requires a value"
provider_option_seen="true"
max_tokens="${2:-}"; max_tokens_explicit="true"; shift 2 ;;
--reasoning)
[[ $# -ge 2 ]] || error "--reasoning requires true or false"
provider_option_seen="true"
reasoning="${2:-}"; shift 2 ;;
--ssh-host)
[[ $# -ge 2 ]] || error "--ssh-host requires a value"
provider_option_seen="true"; ssh_option_seen="true"
ssh_host="${2:-}"; shift 2 ;;
--ssh-user)
[[ $# -ge 2 ]] || error "--ssh-user requires a value"
provider_option_seen="true"; ssh_option_seen="true"
ssh_user="${2:-}"; shift 2 ;;
--ssh-port)
[[ $# -ge 2 ]] || error "--ssh-port requires a value"
provider_option_seen="true"; ssh_option_seen="true"
ssh_port="${2:-}"; shift 2 ;;
--ssh-inference-host)
[[ $# -ge 2 ]] || error "--ssh-inference-host requires a value"
provider_option_seen="true"; ssh_option_seen="true"
ssh_inference_host="${2:-}"; shift 2 ;;
--ssh-inference-port)
[[ $# -ge 2 ]] || error "--ssh-inference-port requires a value"
provider_option_seen="true"; ssh_option_seen="true"
ssh_inference_port="${2:-}"; shift 2 ;;
--ssh-control-host)
[[ $# -ge 2 ]] || error "--ssh-control-host requires a value"
provider_option_seen="true"; ssh_option_seen="true"
ssh_control_host="${2:-}"; shift 2 ;;
--ssh-control-port)
[[ $# -ge 2 ]] || error "--ssh-control-port requires a value"
provider_option_seen="true"; ssh_option_seen="true"
ssh_control_port="${2:-}"; shift 2 ;;
--api-key-stdin)
secret_option_seen="true"
api_key_stdin="true"; shift ;;
--api-key-file)
[[ $# -ge 2 ]] || error "--api-key-file requires a value"
secret_option_seen="true"
api_key_file="$(_caller_path "${2:-}")"; shift 2 ;;
--api-key-env)
[[ $# -ge 2 ]] || error "--api-key-env requires a value"
secret_option_seen="true"
api_key_env="${2:-}"; api_key_env_explicit="true"; shift 2 ;;
--api-key)
error "Raw --api-key is not supported; use --api-key-stdin, --api-key-file, or --api-key-env" ;;
--ssh-private-key-file)
[[ $# -ge 2 ]] || error "--ssh-private-key-file requires a value"
secret_option_seen="true"; ssh_option_seen="true"
ssh_private_key_file="$(_caller_path "${2:-}")"; shift 2 ;;
--ssh-private-key-env)
[[ $# -ge 2 ]] || error "--ssh-private-key-env requires a value"
secret_option_seen="true"; ssh_option_seen="true"
ssh_private_key_env="${2:-}"; ssh_private_key_env_explicit="true"; shift 2 ;;
--ssh-known-hosts-file)
[[ $# -ge 2 ]] || error "--ssh-known-hosts-file requires a value"
secret_option_seen="true"; ssh_option_seen="true"
ssh_known_hosts_file="$(_caller_path "${2:-}")"; shift 2 ;;
--ssh-known-hosts-env)
[[ $# -ge 2 ]] || error "--ssh-known-hosts-env requires a value"
secret_option_seen="true"; ssh_option_seen="true"
ssh_known_hosts_env="${2:-}"; ssh_known_hosts_env_explicit="true"; shift 2 ;;
--ssh-private-key)
error "Raw --ssh-private-key is not supported; use --ssh-private-key-file or --ssh-private-key-env" ;;
--ssh-known-hosts)
error "Raw --ssh-known-hosts is not supported; use --ssh-known-hosts-file or --ssh-known-hosts-env" ;;
--json)
json_mode="true"; shift ;;
--help|-h)
_remote_provider_usage; exit 0 ;;
*)
error "Unknown remote-provider option: $1" ;;
esac
done
REMOTE_PROVIDER_JSON_MODE="$json_mode"
if [[ "$action" == "enable" || "$action" == "disable" || "$action" == "remove" ]]; then
[[ "$provider_option_seen" == "false" && "$secret_option_seen" == "false" ]] || \
error "remote-provider $action does not accept provider or secret options"
jq -nc --arg action "$action" '{action: $action}' > "$payload_file" || \
error "Could not build remote-provider lifecycle request"
return 0
fi
transport="$(printf '%s' "$transport" | tr '[:upper:]' '[:lower:]')"
case "$transport" in
direct|ssh) ;;
*) error "--transport must be direct or ssh" ;;
esac
[[ -n "$base_url" ]] || error "--base-url is required"
[[ -n "$model" ]] || error "--model is required"
[[ "$context_length" =~ ^[1-9][0-9]{0,7}$ ]] || \
error "--context-length must be an integer from 16384 to 10000000"
(( context_length >= 16384 && context_length <= 10000000 )) || \
error "--context-length must be an integer from 16384 to 10000000"
# Portal writes each file in one reply; a 4096 default cut off ordinary
# game files. Match bin/remote_provider/lifecycle.py.
if [[ "$max_tokens_explicit" == "false" ]]; then
max_tokens=$(( context_length / 4 < 32768 ? context_length / 4 : 32768 ))
fi
[[ "$max_tokens" =~ ^[1-9][0-9]{0,7}$ ]] || \
error "--max-tokens must be a positive integer within the context window"
(( max_tokens <= context_length )) || \
error "--max-tokens must be a positive integer within the context window"
reasoning="$(printf '%s' "$reasoning" | tr '[:upper:]' '[:lower:]')"
case "$reasoning" in
true|false) ;;
*) error "--reasoning must be true or false" ;;
esac
if [[ "$transport" == "direct" && "$ssh_option_seen" == "true" ]]; then
error "direct remote-provider transport does not accept SSH options"
fi
if [[ "$transport" == "ssh" ]]; then
[[ -n "$ssh_host" ]] || error "--ssh-host is required for SSH remote-provider transport"
[[ -n "$ssh_user" ]] || error "--ssh-user is required for SSH remote-provider transport"
[[ -n "$ssh_port" ]] || error "--ssh-port is required for SSH remote-provider transport"
[[ -n "$ssh_inference_host" ]] || error "--ssh-inference-host is required for SSH remote-provider transport"
[[ -n "$ssh_inference_port" ]] || error "--ssh-inference-port is required for SSH remote-provider transport"
fi
local secret_sources=0 api_key
[[ "$api_key_stdin" == "true" ]] && secret_sources=$((secret_sources + 1))
[[ -n "$api_key_file" ]] && secret_sources=$((secret_sources + 1))
[[ "$api_key_env_explicit" == "true" ]] && secret_sources=$((secret_sources + 1))
(( secret_sources > 1 )) && error "Choose only one provider API key source"
api_key="$(_remote_provider_read_secret "$api_key_stdin" "$api_key_file" "$api_key_env")"
if [[ "$transport" == "ssh" ]]; then
local ssh_key_sources=0 ssh_known_hosts_sources=0 ssh_private_key ssh_known_hosts
[[ -n "$ssh_private_key_file" ]] && ssh_key_sources=$((ssh_key_sources + 1))
[[ "$ssh_private_key_env_explicit" == "true" ]] && ssh_key_sources=$((ssh_key_sources + 1))
[[ -n "$ssh_known_hosts_file" ]] && ssh_known_hosts_sources=$((ssh_known_hosts_sources + 1))
[[ "$ssh_known_hosts_env_explicit" == "true" ]] && ssh_known_hosts_sources=$((ssh_known_hosts_sources + 1))
(( ssh_key_sources > 1 )) && error "Choose only one SSH private key source"
(( ssh_known_hosts_sources > 1 )) && error "Choose only one SSH known_hosts source"
ssh_private_key="$(_remote_provider_read_multiline_secret \
"SSH private key" "$ssh_private_key_file" "$ssh_private_key_env" \
"--ssh-private-key-file" "--ssh-private-key-env")"
ssh_known_hosts="$(_remote_provider_read_multiline_secret \
"SSH known_hosts" "$ssh_known_hosts_file" "$ssh_known_hosts_env" \
"--ssh-known-hosts-file" "--ssh-known-hosts-env")"
printf '%s\0%s\0%s' "$api_key" "$ssh_private_key" "$ssh_known_hosts" | jq -Rs \
--arg action "$action" \
--arg transport "$transport" \
--arg base_url "$base_url" \
--arg model "$model" \
--arg context_length "$context_length" \
--arg max_tokens "$max_tokens" \
--argjson reasoning "$reasoning" \
--arg ssh_host "$ssh_host" \
--arg ssh_user "$ssh_user" \
--arg ssh_port "$ssh_port" \
--arg ssh_inference_host "$ssh_inference_host" \
--arg ssh_inference_port "$ssh_inference_port" \
--arg ssh_control_host "$ssh_control_host" \
--arg ssh_control_port "$ssh_control_port" \
'split("\u0000") as $secrets |
{
action: $action,
provider: {
transport: $transport,
baseUrl: $base_url,
model: $model,
contextLength: ($context_length | tonumber),
maxTokens: ($max_tokens | tonumber),
reasoning: $reasoning
},
ssh: {
host: $ssh_host,
user: $ssh_user,
port: $ssh_port,
inferenceHost: $ssh_inference_host,
inferencePort: $ssh_inference_port
},
secrets: {
apiKey: $secrets[0],
sshPrivateKey: $secrets[1],
sshKnownHosts: $secrets[2]
}
}
| if ($ssh_control_host != "" or $ssh_control_port != "") then
.ssh += {
controlHost: $ssh_control_host,
controlPort: $ssh_control_port
}
else . end' > "$payload_file" || error "Could not build remote-provider lifecycle request"
return 0
fi
printf '%s' "$api_key" | jq -Rs \
--arg action "$action" \
--arg transport "$transport" \
--arg base_url "$base_url" \
--arg model "$model" \
--arg context_length "$context_length" \
--arg max_tokens "$max_tokens" \
--argjson reasoning "$reasoning" \
'{
action: $action,
provider: {
transport: $transport,
baseUrl: $base_url,
model: $model,
contextLength: ($context_length | tonumber),
maxTokens: ($max_tokens | tonumber),
reasoning: $reasoning
},
secrets: {
apiKey: .
}
}' > "$payload_file" || error "Could not build remote-provider lifecycle request"
}
_remote_provider_print_status() {
local response_file="$1"
jq -r '
"Remote provider: \(.status // "unknown")",
(if .status == "ready" then
"Ready means set up and proven" +
(if (.routeState.status.lastProbe.verifiedAt // "") != "" then " at \(.routeState.status.lastProbe.verifiedAt)" else "" end) +
"; check that the API answers now with: ods remote-provider test"
else empty end),
(if .status == "paused" then
"An update or a mode change paused it; ODS uses the model on this computer. Use it again with: ods remote-provider enable"
else empty end),
"Route: " + (if .routeState.enabled == true then "enabled" else "disabled" end),
(if .routeState.enabled == true then empty else
"Saved route: " + (if .routeState.resumeAvailable == true then "available (resume it with: ods remote-provider enable)" else "none" end)
end),
(if .routeState.enabled == true and .routeState.provider then
"Provider: \(.routeState.provider.model // "unknown") via \(.routeState.provider.transport // "unknown") at \(.routeState.provider.baseUrl // "unknown")"
else empty end),
"Egress: \(.egress.status // "unknown")" +
(if (.egress.reason // "") != "" then " (\(.egress.reason))" else "" end),
"Secret: " + (if .egress.secret.configured == true then "configured" else "missing" end),
"Actions: " + (
[.availableActions | to_entries[] | select(.value == true) | .key] | join(", ")
)
' "$response_file"
}
_remote_provider_print_apply_result() {
local response_file="$1"
jq -r '
"Remote provider \(.action // "operation"): " +
(if .applied == true then "applied" else "completed" end),
"Mutated state: \(.mutated // false)",
(if .probe then
"Probe: HTTP \(.probe.httpStatus // .probe.status // "unknown") at \(.probe.endpoint // "/v1/models")" +
(if (.probe.modelCount // null) != null then " (\(.probe.modelCount) models)" else "" end)
else empty end),
(if .rollback.attempted == true then
"Rollback: " + (if .rollback.ok == true then "ok" else "failed" end)
else empty end)
' "$response_file"
}
_remote_provider_print_probe_result() {
local response_file="$1"
jq -r '
"Remote provider probe: " + (if .ok == true then "ok" else "failed" end),
"Transport: \(.transport // "unknown")",
(if .probe then
"Probe: HTTP \(.probe.httpStatus // "unknown") at \(.probe.endpoint // "/v1/models")" +
(if (.probe.modelCount // null) != null then " (\(.probe.modelCount) models)" else "" end)
else empty end),
(if .tunnel then
"Tunnel: \(.tunnel.status // "unknown")" +
(if (.tunnel.reason // "") != "" then " (\(.tunnel.reason))" else "" end)
else empty end),
(if .routeProof then
"Route proof: " +
(if .routeProof.recorded == true then
"recorded" +
(if (.routeProof.status.reason // "") != "" then " (\(.routeProof.status.reason))" else "" end)
else
"not recorded" +
(if (.routeProof.reason // "") != "" then " (\(.routeProof.reason))" else "" end)
end)
else empty end)
' "$response_file"
}
_remote_provider_peer_models_usage() {
cat <<'EOF'
Usage: ods remote-provider peer-models <command> [options]
Commands:
list [--json]
List models from the authenticated remote ODS peer.
download-status [--json]
Show remote peer model download status.
download MODEL [--json]
Start a model download on the remote ODS peer.
load MODEL [--json]
Load a downloaded model on the remote ODS peer.
cancel-download [--json]
Cancel an active remote peer model download.
delete MODEL --yes [--json]
Delete a downloaded model from the remote ODS peer.
The CLI talks only to the local Dashboard API. Peer credentials remain in ODS
secret custody and are never accepted as command arguments.
EOF
}
_remote_provider_urlencode() {
local value="$1"
jq -rn --arg value "$value" '$value | @uri' || \
error "Could not encode remote peer model id"
}
_remote_provider_peer_model_path() {
local model_id="$1" action="${2:-}" encoded
[[ -n "$model_id" ]] || error "Model id is required"
[[ "$model_id" != *$'\n'* && "$model_id" != *$'\r'* ]] || \
error "Model id contains invalid newline characters"
encoded="$(_remote_provider_urlencode "$model_id")"
[[ -n "$encoded" ]] || error "Model id is required"
if [[ -n "$action" ]]; then
printf '/api/remote-provider/peer/models/%s/%s' "$encoded" "$action"
else
printf '/api/remote-provider/peer/models/%s' "$encoded"
fi
}
_remote_provider_peer_call() {
local method="$1" path="$2" timeout="$3" response_file http_code curl_status detail
response_file=$(mktemp "${TMPDIR:-/tmp}/ods-remote-provider-peer.XXXXXX") || \
error "Could not create a remote-provider peer response file"
chmod 600 "$response_file"
trap 'rm -f "$response_file"' INT TERM HUP
if http_code="$(_remote_provider_request "$method" "$path" "$response_file" "" "$timeout")"; then
curl_status=0
else
curl_status=$?
fi
if [[ $curl_status -ne 0 ]]; then
rm -f "$response_file"; trap - INT TERM HUP
_remote_provider_fail "Remote-provider peer model request failed before Dashboard API completed ($(_remote_provider_transport_reason "$curl_status"))"
fi
if [[ "$http_code" != "200" ]]; then
detail="$(_remote_provider_response_error "$response_file")"
rm -f "$response_file"; trap - INT TERM HUP
_remote_provider_fail "Remote-provider peer model request failed (HTTP $http_code): $detail"
fi
printf '%s' "$response_file"
trap - INT TERM HUP
}
_remote_provider_print_peer_models() {
local response_file="$1"
jq -r '
(.models // []) as $models |
"Remote peer models: \($models | length)",
(if (.currentModel // "") != "" then "Current: \(.currentModel)" else empty end),
($models[]? |
"- " + (.name // .id // "unknown") +
" [" + (.status // "unknown") + "]" +
(if (.size // "") != "" then " " + .size
elif (.sizeGb // null) != null then " " + ((.sizeGb | tostring) + " GB")
else "" end) +
(if (.id // "") != "" and (.name // "") != "" and .id != .name then " id=" + .id else "" end)
)
' "$response_file"
}
_remote_provider_print_peer_download_status() {
local response_file="$1"
jq -r '
"Remote peer download: \(.status // "unknown")",
(if (.model // .modelId // .activeModelId // "") != "" then
"Model: \(.model // .modelId // .activeModelId)"
else empty end),
(if (.percent // null) != null then "Progress: \(.percent)%" else empty end),
(if (.active // .isDownloading // null) != null then
"Active: " + (if (.active == true or .isDownloading == true) then "yes" else "no" end)
else empty end)
' "$response_file"
}
_remote_provider_print_peer_action_result() {
local label="$1" response_file="$2"
jq -r --arg label "$label" '
"Remote peer " + $label + ": " +
(.status // .message // (if .ok == true then "ok" else "completed" end)),
(if (.modelId // .model // "") != "" then "Model: \(.modelId // .model)" else empty end)
' "$response_file"
}
_remote_provider_probe_configured() {
local json_mode="false"
while [[ $# -gt 0 ]]; do
case "$1" in
--json) json_mode="true"; shift ;;
--help|-h) _remote_provider_usage; return 0 ;;
*) error "Unknown remote-provider test option for configured route: $1" ;;
esac
done
local response_file http_code curl_status
response_file=$(mktemp "${TMPDIR:-/tmp}/ods-remote-provider-probe.XXXXXX") || \
error "Could not create a remote-provider response file"
chmod 600 "$response_file"
trap 'rm -f "$response_file"' INT TERM HUP
# A configured probe can activate and reconcile all downstream consumers.
# Stay beyond the Dashboard API's 1800-second lifecycle deadline instead
# of reporting a false failure while the host transaction is still live.
if http_code="$(_remote_provider_request POST /api/remote-provider/probe "$response_file" "" 1860)"; then
curl_status=0
else
curl_status=$?
fi
if [[ $curl_status -ne 0 ]]; then
rm -f "$response_file"; trap - INT TERM HUP
_remote_provider_fail "Remote-provider test request failed before Dashboard API completed ($(_remote_provider_transport_reason "$curl_status"))"
fi
if [[ "$http_code" != "200" ]]; then
local detail
detail="$(_remote_provider_response_error "$response_file")"
rm -f "$response_file"; trap - INT TERM HUP
_remote_provider_fail "Remote-provider test failed (HTTP $http_code): $detail"
fi
if [[ "$json_mode" == "true" ]]; then
jq . "$response_file"
else
_remote_provider_print_probe_result "$response_file"
fi
local not_serving
not_serving="$(_remote_provider_not_serving_reason "$response_file")"
rm -f "$response_file"; trap - INT TERM HUP
if [[ -n "$not_serving" ]]; then
_remote_provider_fail "The remote provider is not answering chats ($not_serving). ODS kept its settings. Check the provider, then run 'ods remote-provider test' again; meanwhile 'ods remote-provider disable' switches ODS to the model on this computer."
fi
}
# The provider listed its models, but the active route served no chat: the
# provider's own answer (fleet 2026-10-18: an outage read "probe: ok").
_remote_provider_not_serving_reason() {
# The provider wrote the message; _remote_provider_fail prints with echo -e,
# so no backslash may reach it.
jq -r 'if .routeProof.reason == "provider_not_serving" then
"HTTP \(.routeProof.providerStatus // "error")" +
(if (.routeProof.providerMessage // "") != "" then ": \(.routeProof.providerMessage | gsub("\\\\"; ""))" else "" end)
else empty end' "$1"
}
cmd_remote_provider_peer_models() {
local subcmd="${1:-list}"
shift || true
case "$subcmd" in
help|--help|-h)
_remote_provider_peer_models_usage
return 0
;;
list)
local json_mode="false"
while [[ $# -gt 0 ]]; do
case "$1" in
--json) json_mode="true"; shift ;;
--help|-h) _remote_provider_peer_models_usage; return 0 ;;
*) error "Unknown remote-provider peer-models list option: $1" ;;
esac
done
local response_file
response_file="$(_remote_provider_peer_call GET /api/remote-provider/peer/models 30)"
if [[ "$json_mode" == "true" ]]; then
jq . "$response_file"
else
_remote_provider_print_peer_models "$response_file"
fi
rm -f "$response_file"
;;
download-status|status)
local json_mode="false"
while [[ $# -gt 0 ]]; do
case "$1" in
--json) json_mode="true"; shift ;;
--help|-h) _remote_provider_peer_models_usage; return 0 ;;
*) error "Unknown remote-provider peer-models download-status option: $1" ;;
esac
done
local response_file
response_file="$(_remote_provider_peer_call GET /api/remote-provider/peer/models/download-status 30)"
if [[ "$json_mode" == "true" ]]; then
jq . "$response_file"
else
_remote_provider_print_peer_download_status "$response_file"
fi
rm -f "$response_file"
;;
cancel-download|cancel)
local json_mode="false"
while [[ $# -gt 0 ]]; do
case "$1" in
--json) json_mode="true"; shift ;;
--help|-h) _remote_provider_peer_models_usage; return 0 ;;
*) error "Unknown remote-provider peer-models cancel-download option: $1" ;;
esac
done
local response_file
response_file="$(_remote_provider_peer_call POST /api/remote-provider/peer/models/download/cancel 30)"
if [[ "$json_mode" == "true" ]]; then
jq . "$response_file"
else
_remote_provider_print_peer_action_result "cancel download" "$response_file"
fi
rm -f "$response_file"
;;
download|load|delete)
local json_mode="false" yes_mode="false" model_id=""
while [[ $# -gt 0 ]]; do
case "$1" in
--json) json_mode="true"; shift ;;
--yes) yes_mode="true"; shift ;;
--help|-h) _remote_provider_peer_models_usage; return 0 ;;
--*) error "Unknown remote-provider peer-models $subcmd option: $1" ;;
*)
[[ -z "$model_id" ]] || error "Only one model id may be supplied"
model_id="$1"; shift ;;
esac
done
[[ -n "$model_id" ]] || error "Usage: ods remote-provider peer-models $subcmd MODEL [--json]"
if [[ "$subcmd" != "delete" && "$yes_mode" == "true" ]]; then
error "--yes is only valid for remote-provider peer-models delete"
fi
if [[ "$subcmd" == "delete" && "$yes_mode" != "true" ]]; then
error "Use --yes to confirm remote peer model deletion"
fi
local path method timeout response_file label
method="POST"
timeout="30"
label="$subcmd"
case "$subcmd" in
download)
path="$(_remote_provider_peer_model_path "$model_id" download)"
label="download"
;;
load)
path="$(_remote_provider_peer_model_path "$model_id" load)"
timeout="2705"
label="load"
;;
delete)
path="$(_remote_provider_peer_model_path "$model_id")"
method="DELETE"
label="delete"
;;
esac
response_file="$(_remote_provider_peer_call "$method" "$path" "$timeout")"
if [[ "$json_mode" == "true" ]]; then
jq . "$response_file"
else
_remote_provider_print_peer_action_result "$label" "$response_file"
fi
rm -f "$response_file"
;;
*)
error "Usage: ods remote-provider peer-models <list|download-status|download|load|cancel-download|delete>"
;;
esac
}
cmd_remote_provider() {
local subcmd="${1:-status}"
shift || true
case "$subcmd" in
help|--help|-h)
_remote_provider_usage
return 0
;;
esac
check_install
cd "$INSTALL_DIR"
load_env
_remote_provider_require_tools
case "$subcmd" in
peer-models|peer-model)
cmd_remote_provider_peer_models "$@"
;;
status)
local json_mode="false"
while [[ $# -gt 0 ]]; do
case "$1" in
--json) json_mode="true"; shift ;;
--help|-h) _remote_provider_usage; return 0 ;;
*) error "Unknown remote-provider status option: $1" ;;
esac
done
local response_file http_code curl_status
response_file=$(mktemp "${TMPDIR:-/tmp}/ods-remote-provider-status.XXXXXX") || \
error "Could not create a remote-provider response file"
chmod 600 "$response_file"
trap 'rm -f "$response_file"' INT TERM HUP
if http_code="$(_remote_provider_request GET /api/remote-provider/status "$response_file" "" 15)"; then
curl_status=0
else
curl_status=$?
fi
if [[ $curl_status -ne 0 ]]; then
rm -f "$response_file"; trap - INT TERM HUP
_remote_provider_fail "Remote-provider status request failed before Dashboard API completed ($(_remote_provider_transport_reason "$curl_status"))"
fi
if [[ "$http_code" != "200" ]]; then
local detail
detail="$(_remote_provider_response_error "$response_file")"
rm -f "$response_file"; trap - INT TERM HUP
_remote_provider_fail "Remote-provider status failed (HTTP $http_code): $detail"
fi
if [[ "$json_mode" == "true" ]]; then
jq . "$response_file"
else
_remote_provider_print_status "$response_file"
fi
rm -f "$response_file"; trap - INT TERM HUP
;;
plan)
local action="${1:-}"
[[ -n "$action" ]] || error "Usage: ods remote-provider plan <configure|test|enable|disable|remove> [options]"
shift || true
case "$action" in
configure|test|enable|disable|remove) ;;
*) error "Usage: ods remote-provider plan <configure|test|enable|disable|remove> [options]" ;;
esac
local payload_file response_file http_code curl_status
payload_file=$(mktemp "${TMPDIR:-/tmp}/ods-remote-provider-payload.XXXXXX") || \
error "Could not create a remote-provider request file"
response_file=$(mktemp "${TMPDIR:-/tmp}/ods-remote-provider-plan.XXXXXX") || \
error "Could not create a remote-provider response file"
chmod 600 "$payload_file" "$response_file"
trap 'rm -f "$payload_file" "$response_file"' INT TERM HUP
_remote_provider_write_payload "$action" "$payload_file" "$@"
if http_code="$(_remote_provider_request POST /api/remote-provider/plan "$response_file" "$payload_file" 15)"; then
curl_status=0
else
curl_status=$?
fi
rm -f "$payload_file"
if [[ $curl_status -ne 0 ]]; then
rm -f "$response_file"; trap - INT TERM HUP
_remote_provider_fail "Remote-provider plan request failed before Dashboard API completed ($(_remote_provider_transport_reason "$curl_status"))"
fi
if [[ "$http_code" != "200" ]]; then
local detail
detail="$(_remote_provider_response_error "$response_file")"
rm -f "$response_file"; trap - INT TERM HUP
_remote_provider_fail "Remote-provider plan failed (HTTP $http_code): $detail"
fi
jq . "$response_file"
rm -f "$response_file"; trap - INT TERM HUP
;;
enable)
local json_mode="false" response_file http_code curl_status
while [[ $# -gt 0 ]]; do
case "$1" in
--json) json_mode="true"; shift ;;
--help|-h) _remote_provider_usage; return 0 ;;
*) error "Unknown remote-provider enable option: $1" ;;
esac
done
response_file=$(mktemp "${TMPDIR:-/tmp}/ods-remote-provider-enable.XXXXXX") || \
error "Could not create a remote-provider response file"
chmod 600 "$response_file"
trap 'rm -f "$response_file"' INT TERM HUP
if http_code="$(_remote_provider_request POST /api/remote-provider/enable "$response_file" "" 1860)"; then
curl_status=0
else
curl_status=$?
fi
if [[ $curl_status -ne 0 ]]; then
rm -f "$response_file"; trap - INT TERM HUP
_remote_provider_fail "Remote-provider enable request failed before Dashboard API completed ($(_remote_provider_transport_reason "$curl_status"))"
fi
if [[ "$http_code" != "200" ]]; then
local detail
detail="$(_remote_provider_response_error "$response_file")"
rm -f "$response_file"; trap - INT TERM HUP
_remote_provider_fail "Remote-provider enable failed (HTTP $http_code): $detail"
fi
if [[ "$json_mode" == "true" ]]; then
jq . "$response_file"
else
_remote_provider_print_apply_result "$response_file"
fi
rm -f "$response_file"; trap - INT TERM HUP
;;
configure|test|disable|remove)
if [[ "$subcmd" == "test" ]]; then
local use_configured_probe="true" arg
for arg in "$@"; do
case "$arg" in
--transport|--base-url|--model|--context-length|--max-tokens|--reasoning)
use_configured_probe="false"
break
;;
--api-key|--api-key-stdin|--api-key-file|--api-key-env)
use_configured_probe="false"
break
;;
--ssh-host|--ssh-user|--ssh-port|--ssh-inference-host|--ssh-inference-port)
use_configured_probe="false"
break
;;
--ssh-control-host|--ssh-control-port|--ssh-private-key|--ssh-private-key-file)
use_configured_probe="false"
break
;;
--ssh-private-key-env|--ssh-known-hosts|--ssh-known-hosts-file|--ssh-known-hosts-env)
use_configured_probe="false"
break
;;
esac
done
if [[ "$use_configured_probe" == "true" ]]; then
_remote_provider_probe_configured "$@"
return 0
fi
fi
local payload_file response_file http_code curl_status
payload_file=$(mktemp "${TMPDIR:-/tmp}/ods-remote-provider-payload.XXXXXX") || \
error "Could not create a remote-provider request file"
response_file=$(mktemp "${TMPDIR:-/tmp}/ods-remote-provider-apply.XXXXXX") || \
error "Could not create a remote-provider response file"
chmod 600 "$payload_file" "$response_file"
trap 'rm -f "$payload_file" "$response_file"' INT TERM HUP
REMOTE_PROVIDER_JSON_MODE="false"
_remote_provider_write_payload "$subcmd" "$payload_file" "$@"
if http_code="$(_remote_provider_request POST /api/remote-provider/apply "$response_file" "$payload_file" 1860)"; then
curl_status=0
else
curl_status=$?
fi
rm -f "$payload_file"
if [[ $curl_status -ne 0 ]]; then
rm -f "$response_file"; trap - INT TERM HUP
_remote_provider_fail "Remote-provider $subcmd request failed before Dashboard API completed ($(_remote_provider_transport_reason "$curl_status"))"
fi
if [[ "$http_code" != "200" ]]; then
local detail
detail="$(_remote_provider_response_error "$response_file")"
rm -f "$response_file"; trap - INT TERM HUP
_remote_provider_fail "Remote-provider $subcmd failed (HTTP $http_code): $detail"
fi
if [[ "${REMOTE_PROVIDER_JSON_MODE:-false}" == "true" ]]; then
jq . "$response_file"
else
_remote_provider_print_apply_result "$response_file"
fi
rm -f "$response_file"; trap - INT TERM HUP
;;
help|--help|-h)
_remote_provider_usage
;;
*)
error "Usage: ods remote-provider <status|plan|configure|test|enable|disable|remove|peer-models>"
;;
esac
}
cmd_stt() {
check_install; cd "$INSTALL_DIR"
local subcmd="${1:-status}"
# Resolve model and port from .env (with fallback for older installs).
local model port model_encoded url
# These settings are dotenv values, including quotes and inline comments.
# Keep missing-file/key defaults independent of the caller's environment.
local AUDIO_STT_MODEL="" WHISPER_PORT=""
if [[ -f "$INSTALL_DIR/.env" ]]; then
load_env
fi
model="${AUDIO_STT_MODEL:-Systran/faster-whisper-base}"
port="${WHISPER_PORT:-9000}"
model_encoded="${model//\//%2F}"
url="http://127.0.0.1:${port}"
case "$subcmd" in
current)
echo "STT model: ${model}"
echo "Whisper URL: ${url}"
return 0
;;
status)
if ! curl -sf --max-time 3 "${url}/v1/models" >/dev/null 2>&1; then
warn "Whisper service not reachable at ${url}"
echo " Is voice enabled and the stack running?"
return 1
fi
local target_encoded="$model_encoded"
local target_model="$model"
if [[ -n "${2:-}" ]]; then
target_model="$2"
target_encoded="${target_model//\//%2F}"
fi
if curl -sf --max-time 5 "${url}/v1/models/${target_encoded}" >/dev/null 2>&1; then
success "Cached: ${target_model}"
else
warn "Not cached: ${target_model}"
echo " Run: ods stt download${2:+ $2}"
fi
;;
download)
local target_model="${2:-$model}"
local target_encoded="${target_model//\//%2F}"
# Wait briefly for the models API to be ready (max 15s).
local ready=false
for _i in $(seq 1 15); do
if curl -sf --max-time 2 "${url}/v1/models" >/dev/null 2>&1; then
ready=true
break
fi
sleep 1
done
if ! $ready; then
error "Whisper models API not reachable at ${url}. Is voice enabled and the stack running?"
fi
# Skip if already cached.
if curl -sf --max-time 5 "${url}/v1/models/${target_encoded}" >/dev/null 2>&1; then
success "Already cached: ${target_model}"
return 0
fi
echo "Downloading ${target_model}..."
if ! curl -s --max-time 3600 -X POST "${url}/v1/models/${target_encoded}"; then
error "Download request failed. Check Whisper logs: ods logs whisper"
fi
# Verify the download actually cached.
if curl -sf --max-time 10 "${url}/v1/models/${target_encoded}" >/dev/null 2>&1; then
success "Downloaded and cached: ${target_model}"
else
error "Download returned but model is not cached. Check Whisper logs: ods logs whisper"
fi
;;
*)
error "Usage: ods stt <current|status|download> [MODEL]"
;;
esac
}
cmd_backup() {
check_install
cd "$INSTALL_DIR"
if [[ ! -x "$INSTALL_DIR/ods-backup.sh" ]]; then
error "ods-backup.sh not found or not executable"
fi
local action="${1:-}"
if [[ "$action" == "verify" ]]; then
shift
local id="${1:-}"
[[ -z "$id" ]] && error "Usage: ods backup verify <backup_id|backup_id.tar.gz>"
"$INSTALL_DIR/ods-backup.sh" verify "$id"
return
fi
# Default: create backup (pass all args through, output dir resolved)
local -a backup_args=()
while [[ $# -gt 0 ]]; do
case "$1" in
-o|--output)
backup_args+=("$1")
[[ $# -ge 2 ]] && { backup_args+=("$(_caller_path "$2")"); shift; }
;;
*) backup_args+=("$1") ;;
esac
shift
done
"$INSTALL_DIR/ods-backup.sh" ${backup_args[@]+"${backup_args[@]}"}
}
cmd_restore() {
check_install
cd "$INSTALL_DIR"
if [[ ! -x "$INSTALL_DIR/ods-restore.sh" ]]; then
error "ods-restore.sh not found or not executable"
fi
# Pass all arguments to ods-restore.sh
"$INSTALL_DIR/ods-restore.sh" "$@"
}
cmd_rollback() {
check_install
cd "$INSTALL_DIR"
if [[ ! -x "$INSTALL_DIR/ods-update.sh" ]]; then
error "ods-update.sh not found or not executable"
fi
local target="${1:-}"
log "Rolling back to pre-update state${target:+ (snapshot: $target)}..."
echo ""
warn "This will restore configuration from before the last update."
read -p "Continue with rollback? [y/N] " -n 1 -r || REPLY=""
echo ""
if [[ ! $REPLY =~ ^[Yy]$ ]]; then
log "Rollback cancelled"
return 0
fi
# ods-update.sh owns pre-update snapshot discovery, integrity verification,
# compose-stack restoration, restart, and health proof. Keeping that
# transaction in one implementation avoids diverging backup roots and stale
# in-memory compose flags in this CLI wrapper.
bash "$INSTALL_DIR/ods-update.sh" rollback ${target:+"$target"}
}
_agent_mode_snapshot() {
local key port host payload
key="$(_env_get_raw ODS_AGENT_KEY)"
[[ -n "$key" ]] || key="$(_env_get_raw DASHBOARD_API_KEY)"
case "$key" in
\"*\") key="${key:1:${#key}-2}" ;;
\'*\') key="${key:1:${#key}-2}" ;;
esac
[[ -n "$key" && "$key" != *$'\n'* && "$key" != *$'\r'* ]] || return 1
port="$(_env_get_raw ODS_AGENT_PORT)"
port="${port#\"}"; port="${port%\"}"
port="${port#\'}"; port="${port%\'}"
[[ "$port" =~ ^[0-9]+$ ]] || port=7710
host="$(_agent_probe_host)"
# Keep credentials off argv and out of diagnostics, including on failure.
payload=$(printf 'Authorization: Bearer %s\n' "$key" | \
curl --silent --fail --max-time 3 --header @- \
"http://${host}:${port}/v1/model/config" 2>/dev/null) || return 1
printf '%s' "$payload" | jq -ers 'select(length == 1) | .[0] |
select(.configuredMode == "local" or .configuredMode == "cloud" or .configuredMode == "hybrid") |
select(.effectiveMode == "local" or .effectiveMode == "cloud" or .effectiveMode == "hybrid" or .effectiveMode == "unknown") |
[.effectiveMode, .configuredMode] | join(" ")' 2>/dev/null
}
# Print what is holding the host agent's model lifecycle, or nothing when it is
# idle. `ods update` recreates the stack and restarts the agent, which cuts a
# model switch or Portal access check off half-done (the dashboard's update
# already claims this boundary). Fails when the agent cannot be asked.
_agent_model_lifecycle_busy() {
local key port host status recovery
key="$(_env_get_raw ODS_AGENT_KEY)"
[[ -n "$key" ]] || key="$(_env_get_raw DASHBOARD_API_KEY)"
case "$key" in
\"*\") key="${key:1:${#key}-2}" ;;
\'*\') key="${key:1:${#key}-2}" ;;
esac
[[ -n "$key" && "$key" != *$'\n'* && "$key" != *$'\r'* ]] || return 1
port="$(_env_get_raw ODS_AGENT_PORT)"
port="${port#\"}"; port="${port%\"}"
port="${port#\'}"; port="${port%\'}"
[[ "$port" =~ ^[0-9]+$ ]] || port=7710
host="$(_agent_probe_host)"
# Keep credentials off argv and out of diagnostics, including on failure.
status=$(printf 'Authorization: Bearer %s\n' "$key" | \
curl --silent --fail --max-time 5 --header @- \
"http://${host}:${port}/v1/model/status" 2>/dev/null) || return 1
# A known active operation is enough to refuse, whatever recovery would
# say; a switch in progress also reports its recovery as pending.
if printf '%s' "$status" | jq -e '.lifecycleActive == true' >/dev/null; then
printf '%s' "$status" | jq -r '"\(.activeOperation // "a model operation")\(if .activeTarget then " for \(.activeTarget)" else "" end) is in progress"'
return
fi
recovery=$(printf 'Authorization: Bearer %s\n' "$key" | \
curl --silent --fail --max-time 5 --header @- \
"http://${host}:${port}/v1/model/recovery" 2>/dev/null) || return 1
printf '%s' "$recovery" | jq -er 'if .pending == true then
"an interrupted model switch is waiting for recovery (ods model recover)" else "" end' || return 1
}
# Refuse $1 (a CLI action that recreates the stack or restarts the agent or
# llama-server) while the agent's model lifecycle is busy; warn and continue
# when the agent cannot be asked.
_ods_cli_refuse_under_model_lifecycle() {
local action="$1" label lifecycle_busy=""
case "$action" in
update) label="Update" ;;
restart) label="Restart" ;;
*) label="ods $action" ;;
esac
if lifecycle_busy="$(_agent_model_lifecycle_busy)"; then
lifecycle_busy="$(printf '%s\n' "$lifecycle_busy" | sed '/^$/d' | paste -sd ';' -)"
if [[ -n "$lifecycle_busy" ]]; then
error "$label not started: ${lifecycle_busy//;/; }. Let it finish (or recover it), then run ods ${action} again."
fi
else
warn "Could not ask the host agent whether a model change is in progress; continuing."
fi
}
_agent_refresh_mode() {
local snapshot effective configured expected attempt
expected="${1:-}"
expected="${expected#\"}"; expected="${expected%\"}"
expected="${expected#\'}"; expected="${expected%\'}"
expected="$(printf '%s' "$expected" | tr '[:upper:]' '[:lower:]')"
[[ "$expected" != lemonade ]] || expected=local
case "$expected" in
local|cloud|hybrid) ;;
*) log_error "The restarted stack's ODS mode is unknown. Check .env and run 'ods restart' before changing models."; return 1 ;;
esac
if ! snapshot="$(_agent_mode_snapshot)"; then
log_error "Services restarted, but the host-agent runtime mode could not be verified. Run 'ods agent restart', then 'ods restart' before changing models."
return 1
fi
read -r effective configured <<< "$snapshot"
if [[ "$configured" != "$expected" ]]; then
log_error "ODS mode changed during the stack restart. Run 'ods restart' to apply the current configuration."
return 1
fi
[[ "$effective" != "$configured" ]] || return 0
# Unknown startup mode means this process started without a valid mode.
# A fresh authenticated configured mode plus the completed stack restart
# authorizes restarting it; it does not authorize bypassing the swap gate.
log "Refreshing host agent for $configured mode (startup mode: $effective)..."
if ! cmd_agent restart; then
log_error "Services restarted, but the host agent did not restart. Run 'ods agent restart', then 'ods restart' before changing models."
return 1
fi
for attempt in {1..10}; do
if snapshot="$(_agent_mode_snapshot)"; then
read -r effective configured <<< "$snapshot"
if [[ "$configured" != "$expected" ]]; then
log_error "ODS mode changed again during restart. Run 'ods restart' to apply the current configuration."
return 1
fi
if [[ "$effective" == "$configured" ]]; then
success "Host agent is running in $configured mode"
return 0
fi
fi
sleep 0.5
done
log_error "The restarted host agent has not confirmed $expected mode. Check 'ods agent logs', then run 'ods restart' before changing models."
return 1
}
cmd_agent() {
check_install
load_env 2>/dev/null || true
local action="${1:-status}"
local port="${ODS_AGENT_PORT:-7710}"
local pid_file="$INSTALL_DIR/data/ods-host-agent.pid"
local log_file="$INSTALL_DIR/data/ods-host-agent.log"
local agent_script="$INSTALL_DIR/bin/ods-host-agent.py"
_agent_process_owned() {
local candidate_pid="${1:-}" command_line=""
[[ "$candidate_pid" =~ ^[0-9]+$ ]] || return 1
kill -0 "$candidate_pid" 2>/dev/null || return 1
command_line=$(ps -p "$candidate_pid" -o command= 2>/dev/null || true)
[[ -n "$command_line" && "$command_line" == *"$agent_script"* ]]
}
_agent_health_ready() {
local bind_addr health_payload
bind_addr="$(_agent_probe_host)"
health_payload=$(curl -sf --max-time 2 "http://${bind_addr}:${port}/health" 2>/dev/null) || return 1
grep -Eq '"status"[[:space:]]*:[[:space:]]*"ok"' <<<"$health_payload" && \
grep -Eq '"version"[[:space:]]*:' <<<"$health_payload"
}
# Installer phases can explicitly request the per-session fallback when
# sudo is unavailable, even if an older system unit remains on disk.
local daemon_type="none"
if [[ "${ODS_AGENT_FORCE_SESSION:-false}" != "true" ]]; then
case "$(uname -s)" in
Darwin)
if [[ -f "$HOME/Library/LaunchAgents/com.ods.host-agent.plist" ]]; then
daemon_type="launchd"
fi
;;
Linux)
if command -v systemctl >/dev/null 2>&1 && \
systemctl cat ods-host-agent.service >/dev/null 2>&1; then
daemon_type="systemd"
fi
;;
esac
fi
case "$action" in
refresh-mode)
_agent_refresh_mode "${2:-}"
;;
status)
if _agent_health_ready; then
success "ODS host agent: running (port ${port}, ${daemon_type})"
else
warn "ODS host agent: not responding (port ${port})"
fi
;;
start)
case "$daemon_type" in
launchd)
launchctl bootstrap "gui/$(id -u)" \
"$HOME/Library/LaunchAgents/com.ods.host-agent.plist" 2>/dev/null && \
success "Agent started (LaunchAgent)" || warn "Agent start failed"
;;
systemd)
if ! sudo systemctl start ods-host-agent.service 2>/dev/null; then
log_error "Agent start failed"
return 1
fi
# The unit is Type=simple: systemctl returns once the
# process is forked, even if it then fails to bind.
local attempt
for attempt in {1..20}; do
if _agent_health_ready; then
success "Agent started (systemd)"
return 0
fi
sleep 0.5
done
log_error "Agent did not become healthy on port ${port}; check: journalctl -u ods-host-agent.service"
return 1
;;
*)
# Fallback: nohup + PID file
if _agent_health_ready; then
success "ODS host agent: already running (port ${port})"
return 0
fi
if [[ -f "$pid_file" ]]; then
local stale_pid
stale_pid=$(tr -d '[:space:]' < "$pid_file")
if _agent_process_owned "$stale_pid"; then
kill "$stale_pid" 2>/dev/null || true
elif [[ -n "$stale_pid" ]]; then
warn "Ignoring stale host-agent PID file; process $stale_pid is not owned by ODS"
fi
rm -f "$pid_file"
fi
# Use log_error (not error): callers such as cmd_update run
# this under `cmd_agent restart || warn "...non-fatal"`, and
# error() exits the whole CLI — which would abort an already
# successful update instead of returning to the guard.
if ! command -v python3 &>/dev/null; then
log_error "python3 not found in PATH"
return 1
fi
if [[ ! -f "$agent_script" ]]; then
log_error "ODS host agent script not found: $agent_script"
return 1
fi
nohup python3 "$agent_script" --pid-file "$pid_file" \
>> "$log_file" 2>&1 &
local agent_pid=$!
disown "$agent_pid" 2>/dev/null || true
local attempt
for attempt in {1..20}; do
if _agent_health_ready; then
success "Agent started (background, PID $agent_pid)"
return 0
fi
kill -0 "$agent_pid" 2>/dev/null || break
sleep 0.5
done
_agent_process_owned "$agent_pid" && kill "$agent_pid" 2>/dev/null || true
rm -f "$pid_file"
log_error "Agent did not become healthy on port ${port}; check $log_file"
return 1
;;
esac
;;
stop)
case "$daemon_type" in
launchd)
launchctl bootout "gui/$(id -u)/com.ods.host-agent" 2>/dev/null && \
success "Agent stopped" || warn "Agent not running"
;;
systemd)
if sudo systemctl stop ods-host-agent.service 2>/dev/null; then
success "Agent stopped"
else
log_error "Agent stop failed"
return 1
fi
;;
*)
if [[ -f "$pid_file" ]]; then
local agent_pid
agent_pid=$(tr -d '[:space:]' < "$pid_file")
if _agent_process_owned "$agent_pid"; then
kill "$agent_pid" 2>/dev/null && \
success "Agent stopped" || warn "Agent process not found"
elif [[ -n "$agent_pid" ]]; then
warn "Refusing to stop process $agent_pid because it is not owned by ODS"
else
warn "Agent PID file is empty"
fi
rm -f "$pid_file"
else
warn "Agent not running (no PID file)"
fi
;;
esac
;;
restart)
cmd_agent stop || return 1
sleep 1
cmd_agent start
;;
logs)
if [[ -f "$log_file" ]]; then
tail -f "$log_file"
else
warn "No log file at $log_file"
return 1
fi
;;
*)
log "Usage: ods agent [status|start|stop|restart|logs]"
;;
esac
}
#=============================================================================
# cmd_gpu — Multi-GPU inspection and management
#=============================================================================
_gpu_status() {
check_install
load_env
if [[ "${GPU_BACKEND:-}" == "apple" ]]; then
echo -e "${BLUE}━━━ GPU Status (1 integrated GPU) ━━━${NC}"
echo ""
else
local gpu_count=0
if [[ "${GPU_BACKEND:-}" == "amd" ]]; then
local card_dir vendor
for card_dir in /sys/class/drm/card*/device; do
[[ -r "$card_dir/vendor" ]] || continue
# A device may disappear during enumeration; skip unreadable vendors.
vendor=$(cat "$card_dir/vendor" 2>/dev/null) || continue
[[ "$vendor" == "0x1002" ]] && gpu_count=$((gpu_count + 1))
done
elif [[ "${GPU_BACKEND:-nvidia}" == "nvidia" ]] && command -v nvidia-smi &>/dev/null; then
gpu_count=$(nvidia-smi --list-gpus 2>/dev/null | wc -l | tr -d ' ') || gpu_count=0
fi
echo -e "${BLUE}━━━ GPU Status (${gpu_count} GPU$([ "$gpu_count" -ne 1 ] && echo s)) ━━━${NC}"
echo ""
fi
if [[ "${GPU_BACKEND:-nvidia}" == "nvidia" ]] && command -v nvidia-smi &>/dev/null && [ "$gpu_count" -gt 0 ]; then
local output
output=$(nvidia-smi \
--query-gpu=index,name,memory.used,memory.total,utilization.gpu,temperature.gpu,power.draw \
--format=csv,noheader,nounits 2>/dev/null) || { warn "nvidia-smi failed"; return; }
[[ -z "$output" ]] && { warn "No NVIDIA GPU data returned"; return; }
echo "$output" | awk -F', ' -v blue="${BLUE}" -v nc="${NC}" '
BEGIN {
printf " %-4s %-22s %-22s %-7s %-7s %s\n", \
"#", "Name", "VRAM Used/Total", "Util", "Temp", "Power"
printf " %-4s %-22s %-22s %-7s %-7s %s\n", \
"─", "──────────────────────", "──────────────────────", "───────", "───────", "─────"
n=0; total_u=0; total_t=0; util_sum=0; max_temp=0; pw_sum=0; pw_count=0
}
{
idx=$1; name=$2; mem_used=$3; mem_total=$4; util=$5; temp=$6; pw=$7
gsub(/^ +| +$/, "", idx); gsub(/^ +| +$/, "", name)
gsub(/^ +| +$/, "", mem_used); gsub(/^ +| +$/, "", mem_total)
gsub(/^ +| +$/, "", util); gsub(/^ +| +$/, "", temp); gsub(/^ +| +$/, "", pw)
vram_str = sprintf("%.1f / %.1f GB", mem_used/1024, mem_total/1024)
if (pw ~ /^[0-9.]+$/) {
pw_str = sprintf("%.0fW", pw); pw_sum += pw; pw_count++
} else {
pw_str = "N/A"
}
printf " %-4s %-22s %-22s %3d%% %3d°C %s\n", \
idx, substr(name,1,22), vram_str, util, temp, pw_str
total_u += mem_used; total_t += mem_total
util_sum += util
if (temp+0 > max_temp+0) max_temp = temp
n++
}
END {
if (n > 1) {
printf " ──────────────────────\n"
pw_total_str = (pw_count > 0) ? sprintf("%.0fW", pw_sum) : "N/A"
vram_str = sprintf("%.1f / %.1f GB", total_u/1024, total_t/1024)
printf " %-4s %-22s %-22s %3d%% %3d°C %s\n", \
"Σ", "", vram_str, int(util_sum/n), max_temp, pw_total_str
}
}'
echo ""
# Compact assignment summary (if configured)
local assignment_b64="${GPU_ASSIGNMENT_JSON_B64:-}"
if [[ -n "$assignment_b64" ]] && command -v jq &>/dev/null; then
assignment_b64=$(echo "$assignment_b64" | tr -d '\r' | tr -d '[:space:]')
local assignment_json
assignment_json=$(echo "$assignment_b64" | base64 -d 2>/dev/null) || assignment_json=""
if [[ -n "$assignment_json" ]]; then
local uuid_map
uuid_map=$(nvidia-smi --query-gpu=index,uuid --format=csv,noheader,nounits 2>/dev/null) || uuid_map=""
echo " GPU Assignments:"
echo "$assignment_json" | jq -r '.gpu_assignment.services | to_entries[] | [.key, (.value.gpus | join(","))] | @tsv' \
| while IFS=$'\t' read -r svc gpus; do
local labels=""
while IFS= read -r uuid; do
[[ -z "$uuid" ]] && continue
local idx
idx=$(echo "$uuid_map" | awk -F', ' -v u="$uuid" '$2==u{print $1; exit}' | tr -d ' ')
labels="${labels:+$labels, }${idx:+GPU${idx}}"
done < <(echo "$gpus" | tr ',' '\n')
printf " %-20s %s\n" "$svc" "${labels:-$gpus}"
done
echo ""
fi
fi
elif [[ "${GPU_BACKEND:-}" == "amd" ]]; then
printf " %-4s %-22s %-22s %-7s %-7s %s\n" \
"#" "Name" "VRAM Used/Total" "Util" "Temp" "Power"
printf " %-4s %-22s %-22s %-7s %-7s %s\n" \
"─" "──────────────────────" "──────────────────────" "───────" "───────" "─────"
local _amd_idx=0 _amd_total_u=0 _amd_total_t=0 _amd_util_sum=0 _amd_max_temp=0 _amd_pw_sum=0
for card_dir in /sys/class/drm/card*/device; do
[[ -f "$card_dir/vendor" ]] || continue
local vendor
vendor=$(cat "$card_dir/vendor" 2>/dev/null) || continue
[[ "$vendor" == "0x1002" ]] || continue
local name vram_total vram_used busy temp_c pw_w
name=$(cat "$card_dir/product_name" 2>/dev/null || echo "AMD Radeon")
[[ -z "$name" || "$name" == "(null)" ]] && name="AMD Radeon"
vram_total=$(cat "$card_dir/mem_info_vram_total" 2>/dev/null || echo "0")
vram_used=$(cat "$card_dir/mem_info_vram_used" 2>/dev/null || echo "0")
busy=$(cat "$card_dir/gpu_busy_percent" 2>/dev/null || echo "0")
# Temperature: find junction sensor via hwmon labels
temp_c="N/A"
for hwmon_dir in "$card_dir"/hwmon/hwmon*; do
[[ -d "$hwmon_dir" ]] || continue
for label_file in "$hwmon_dir"/temp*_label; do
[[ -f "$label_file" ]] || continue
local label_val
label_val=$(cat "$label_file" 2>/dev/null) || continue
if [[ "$label_val" == "junction" || "$label_val" == "edge" ]]; then
local input_file="${label_file/_label/_input}"
if [[ -f "$input_file" ]]; then
local millic
millic=$(cat "$input_file" 2>/dev/null) || millic=0
temp_c=$((millic / 1000))
break 2
fi
fi
done
# Fallback: try temp1_input if no labels found
if [[ "$temp_c" == "N/A" && -f "$hwmon_dir/temp1_input" ]]; then
local millic
millic=$(cat "$hwmon_dir/temp1_input" 2>/dev/null) || millic=0
temp_c=$((millic / 1000))
fi
done
# Power: try power1_average then power1_input (microwatts)
pw_w="N/A"
for hwmon_dir in "$card_dir"/hwmon/hwmon*; do
[[ -d "$hwmon_dir" ]] || continue
local pw_uw=0
if [[ -f "$hwmon_dir/power1_average" ]]; then
pw_uw=$(cat "$hwmon_dir/power1_average" 2>/dev/null) || pw_uw=0
fi
if [[ ! "$pw_uw" =~ ^[0-9]+$ || "$pw_uw" -eq 0 ]] && [[ -f "$hwmon_dir/power1_input" ]]; then
pw_uw=$(cat "$hwmon_dir/power1_input" 2>/dev/null) || pw_uw=0
fi
if [[ "$pw_uw" =~ ^[0-9]+$ && "$pw_uw" -gt 0 ]]; then
pw_w=$((pw_uw / 1000000))
break
fi
done
local vram_str
vram_str=$(awk "BEGIN{printf \"%.1f / %.1f GB\", $vram_used/1073741824, $vram_total/1073741824}")
local temp_str pw_str
[[ "$temp_c" != "N/A" ]] && temp_str="${temp_c}°C" || temp_str="N/A"
[[ "$pw_w" != "N/A" ]] && pw_str="${pw_w}W" || pw_str="N/A"
printf " %-4s %-22s %-22s %3s%% %-7s %s\n" \
"$_amd_idx" "${name:0:22}" "$vram_str" "$busy" "$temp_str" "$pw_str"
_amd_total_u=$((vram_used + _amd_total_u))
_amd_total_t=$((vram_total + _amd_total_t))
_amd_util_sum=$((busy + _amd_util_sum))
[[ "$temp_c" != "N/A" && "$temp_c" -gt "$_amd_max_temp" ]] && _amd_max_temp=$temp_c
[[ "$pw_w" != "N/A" ]] && _amd_pw_sum=$((_amd_pw_sum + pw_w))
_amd_idx=$((_amd_idx + 1))
done
if [[ $_amd_idx -gt 1 ]]; then
printf " ──────────────────────\n"
local vram_str
vram_str=$(awk "BEGIN{printf \"%.1f / %.1f GB\", $_amd_total_u/1073741824, $_amd_total_t/1073741824}")
printf " %-4s %-22s %-22s %3d%% %3d°C %dW\n" \
"Σ" "" "$vram_str" $((_amd_util_sum / _amd_idx)) "$_amd_max_temp" "$_amd_pw_sum"
fi
echo ""
# Assignment summary (same logic as NVIDIA, but map UUIDs via topology JSON)
local assignment_b64="${GPU_ASSIGNMENT_JSON_B64:-}"
if [[ -n "$assignment_b64" ]] && command -v jq &>/dev/null; then
assignment_b64=$(echo "$assignment_b64" | tr -d '\r' | tr -d '[:space:]')
local assignment_json
assignment_json=$(echo "$assignment_b64" | base64 -d 2>/dev/null) || assignment_json=""
if [[ -n "$assignment_json" ]]; then
local topo_file="$INSTALL_DIR/config/gpu-topology.json"
echo " GPU Assignments:"
echo "$assignment_json" | jq -r '.gpu_assignment.services | to_entries[] | [.key, (.value.gpus | join(","))] | @tsv' \
| while IFS=$'\t' read -r svc gpus; do
local labels=""
while IFS= read -r uuid; do
[[ -z "$uuid" ]] && continue
local idx=""
# Look up UUID in topology JSON for index
if [[ -f "$topo_file" ]]; then
idx=$(jq -r --arg u "$uuid" '.gpus[] | select(.uuid == $u) | .index' "$topo_file" 2>/dev/null)
fi
labels="${labels:+$labels, }${idx:+GPU${idx}}"
done < <(echo "$gpus" | tr ',' '\n')
printf " %-20s %s\n" "$svc" "${labels:-$gpus}"
done
echo ""
fi
fi
elif [[ "${GPU_BACKEND:-}" == "apple" ]]; then
local _chip _total_mem_gb _gpu_cores
_chip="$(sysctl -n machdep.cpu.brand_string 2>/dev/null || echo 'Apple Silicon')"
_total_mem_gb=$(( $(sysctl -n hw.memsize 2>/dev/null || echo 0) / 1024 / 1024 / 1024 ))
if command -v jq >/dev/null 2>&1; then
_gpu_cores=$(system_profiler SPDisplaysDataType -json 2>/dev/null \
| jq -r '.SPDisplaysDataType[0].sppci_cores // "?"' 2>/dev/null) || _gpu_cores="?"
[[ -n "$_gpu_cores" ]] || _gpu_cores="?"
else
_gpu_cores="?"
fi
echo ""
echo " Chip: $_chip"
echo " Unified memory: ${_total_mem_gb} GB"
echo " GPU cores: $_gpu_cores"
echo " (Apple Silicon integrated GPU — unified memory shared with CPU)"
else
warn "GPU status unavailable: nvidia-smi not found and GPU_BACKEND is not amd"
fi
}
_gpu_topology() {
local force=0
while [[ $# -gt 0 ]]; do
case "$1" in --force|-f) force=1 ;; esac
shift
done
check_install
load_env
echo -e "${BLUE}━━━ GPU Topology ━━━${NC}"
echo ""
if [[ "${GPU_BACKEND:-}" == "apple" ]]; then
echo " Single integrated GPU (Apple Silicon, unified memory) — no multi-GPU topology to display."
return 0
fi
if ! command -v jq &>/dev/null; then
warn "jq not found — required for topology display"
return
fi
local backend="${GPU_BACKEND:-nvidia}"
local topo_lib topo_detect_fn
if [[ "$backend" == "amd" ]]; then
topo_lib="$SCRIPT_DIR/installers/lib/amd-topo.sh"
topo_detect_fn="detect_amd_topo"
else
topo_lib="$SCRIPT_DIR/installers/lib/nvidia-topo.sh"
topo_detect_fn="detect_nvidia_topo"
if ! command -v nvidia-smi &>/dev/null; then
warn "nvidia-smi not found — topology unavailable"
return
fi
fi
if [[ ! -f "$topo_lib" ]]; then
warn "Topology library not found: $topo_lib"
return
fi
local topo_file="$INSTALL_DIR/config/gpu-topology.json"
local topo_json
if [[ "$force" -eq 0 && -f "$topo_file" ]]; then
topo_json=$(cat "$topo_file")
else
[[ "$force" -eq 1 && -f "$topo_file" ]] && log "Re-detecting topology (--force)..."
. "$topo_lib"
topo_json=$($topo_detect_fn 2>&1) || { warn "Failed to detect GPU topology"; return; }
echo "$topo_json" > "$topo_file"
chmod 644 "$topo_file"
log "Topology saved to $topo_file"
fi
local gpu_count driver
gpu_count=$(echo "$topo_json" | jq -r '.gpu_count // 0')
driver=$(echo "$topo_json" | jq -r '.driver_version // "unknown"')
if [[ "$backend" == "amd" ]]; then
local vendor_label
vendor_label=$(echo "$topo_json" | jq -r '.vendor // "amd"')
echo " GPUs: ${gpu_count} Driver: ROCm ${driver} Backend: ${vendor_label}"
else
local mig_enabled
mig_enabled=$(echo "$topo_json" | jq -r '.mig_enabled // false')
echo " GPUs: ${gpu_count} Driver: ${driver} MIG: ${mig_enabled}"
fi
echo ""
# Build a fixed-width link_type matrix from the JSON links array
echo "$topo_json" | jq -r '
def pad(w): . + (" " * w) | .[:w];
.gpu_count as $n |
.links as $links |
([" ", ([range($n) | "GPU\(.)" | pad(6)] | .[])] | join("")),
([range($n) | . as $a |
(["GPU\($a)" | pad(6)] + [range($n) | . as $b |
if $a == $b then "X"
else
([$links[] | select(
(.gpu_a == $a and .gpu_b == $b) or
(.gpu_a == $b and .gpu_b == $a)
) | .link_type] | first // "?")
end | pad(6)
] | join(""))
] | .[])
' | sed 's/^/ /'
echo ""
local numa_nodes
numa_nodes=$(echo "$topo_json" | jq -r '.numa.nodes // 1')
echo " NUMA nodes: ${numa_nodes}"
# AMD-specific: show gfx versions and memory types
if [[ "$backend" == "amd" ]]; then
local has_gfx
has_gfx=$(echo "$topo_json" | jq -r '[.gpus[].gfx_version // empty] | length')
if [[ "$has_gfx" -gt 0 ]]; then
echo ""
echo " GPU Details:"
echo "$topo_json" | jq -r '
.gpus[] |
" GPU\(.index): \(.name) — gfx\(.gfx_version // "?") \(.memory_type // "discrete") \(.memory_gb)GB renderD\(.render_node // "?")"
' 2>/dev/null
fi
fi
}
_gpu_assignment() {
check_install
load_env
echo -e "${BLUE}━━━ GPU Assignment ━━━${NC}"
echo ""
local assignment_b64="${GPU_ASSIGNMENT_JSON_B64:-}"
if [[ -z "$assignment_b64" ]]; then
echo " Single GPU — no multi-GPU assignment configured."
return
fi
if ! command -v jq &>/dev/null; then
warn "jq not found — required for assignment display"
return
fi
# Strip CR and trailing whitespace (CRLF .env or editor artifacts break base64 -d)
assignment_b64=$(echo "$assignment_b64" | tr -d '\r' | tr -d '[:space:]')
local assignment_json
assignment_json=$(echo "$assignment_b64" | base64 -d 2>/dev/null) || {
warn "Failed to decode GPU_ASSIGNMENT_JSON_B64 — try running 'ods gpu reassign'"
return
}
local strategy
strategy=$(echo "$assignment_json" | jq -r '.gpu_assignment.strategy // "unknown"')
echo " Strategy: ${strategy}"
echo ""
# Build UUID → index map for readable display
local uuid_map="" backend="${GPU_BACKEND:-nvidia}"
if [[ "$backend" == "amd" ]]; then
# For AMD, use topology JSON which has index + uuid per GPU
local topo_file="$INSTALL_DIR/config/gpu-topology.json"
if [[ -f "$topo_file" ]] && command -v jq &>/dev/null; then
uuid_map=$(jq -r '.gpus[] | "\(.index), \(.uuid)"' "$topo_file" 2>/dev/null) || uuid_map=""
fi
elif command -v nvidia-smi &>/dev/null; then
uuid_map=$(nvidia-smi --query-gpu=index,uuid --format=csv,noheader,nounits 2>/dev/null) || uuid_map=""
fi
printf " %-16s %-24s %-10s %-4s %-4s\n" "Service" "GPUs" "Mode" "TP" "PP"
printf " %-16s %-24s %-10s %-4s %-4s\n" "───────────────" "───────────────────────" "─────────" "──" "──"
echo "$assignment_json" | jq -r '.gpu_assignment.services | to_entries[] |
[.key,
(.value.gpus | join(",")),
(.value.parallelism.mode // "—"),
(.value.parallelism.tensor_parallel_size // "—" | tostring),
(.value.parallelism.pipeline_parallel_size // "—" | tostring)] |
@tsv' | while IFS=$'\t' read -r service gpus mode tp pp; do
# Map UUIDs to GPU indices when possible
local display_gpus="$gpus"
if [[ -n "$uuid_map" ]]; then
local gpu_labels=""
while IFS= read -r uuid; do
[[ -z "$uuid" ]] && continue
local idx
idx=$(echo "$uuid_map" | awk -F', ' -v u="$uuid" '$2==u{print $1; exit}' | tr -d ' ')
if [[ -n "$idx" ]]; then
gpu_labels="${gpu_labels:+$gpu_labels, }GPU${idx}"
fi
done < <(echo "$gpus" | tr ',' '\n')
[[ -n "$gpu_labels" ]] && display_gpus="$gpu_labels"
fi
printf " %-16s %-24s %-10s %-4s %-4s\n" "$service" "${display_gpus:0:24}" "$mode" "$tp" "$pp"
done
}
_gpu_validate() {
check_install
load_env
echo -e "${BLUE}━━━ GPU Validate ━━━${NC}"
echo ""
# Apple Silicon is a single integrated GPU with unified memory —
# GPU_COUNT / multi-GPU assignment / split-mode checks do not apply.
# Report a clean skip rather than emitting false-positive failures.
if [[ "${GPU_BACKEND:-}" == "apple" ]]; then
echo " Apple Silicon: single integrated GPU (unified memory) — no multi-GPU validation needed."
echo ""
echo " Result: 0 check(s) passed, 0 failed"
return 0
fi
local pass=0 fail=0
# Check 1: GPU_COUNT matches actual
local env_count="${GPU_COUNT:-1}"
local actual_count=1
local backend="${GPU_BACKEND:-nvidia}"
if [[ "$backend" == "amd" ]]; then
# Count AMD GPUs via sysfs vendor ID
actual_count=0
for card_dir in /sys/class/drm/card*/device; do
[[ -d "$card_dir" ]] || continue
local vendor
vendor=$(cat "$card_dir/vendor" 2>/dev/null) || continue
[[ "$vendor" == "0x1002" ]] && ((actual_count++)) || true
done
[[ "$actual_count" -eq 0 ]] && actual_count=1
elif command -v nvidia-smi &>/dev/null; then
actual_count=$(nvidia-smi --list-gpus 2>/dev/null | wc -l | tr -d ' ' || true)
actual_count="${actual_count:-0}"
fi
if [[ -z "${GPU_COUNT:-}" ]]; then
warn "GPU_COUNT not set in .env — defaulting to 1 (re-run installer or set manually)"
((fail++)) || true
elif [[ "$env_count" -eq "$actual_count" ]]; then
success "GPU_COUNT=${env_count} matches actual GPU count"
((pass++)) || true
else
warn "GPU_COUNT=${env_count} in .env does not match actual count=${actual_count}"
echo " Fix: set GPU_COUNT=${actual_count} in .env"
((fail++)) || true
fi
# Check 2: Assigned UUIDs still present in system
local assignment_b64="${GPU_ASSIGNMENT_JSON_B64:-}"
if [[ -z "$assignment_b64" ]]; then
echo " (No multi-GPU assignment — single GPU setup)"
elif command -v jq &>/dev/null; then
local assignment_json
if assignment_json=$(echo "$assignment_b64" | base64 -d 2>/dev/null); then
local live_uuids=""
if [[ "$backend" == "amd" ]]; then
# For AMD, rebuild UUID list from topology JSON or sysfs
local topo_file="$INSTALL_DIR/config/gpu-topology.json"
if [[ -f "$topo_file" ]]; then
live_uuids=$(jq -r '.gpus[].uuid' "$topo_file" 2>/dev/null | tr -d ' ' || true)
fi
elif command -v nvidia-smi &>/dev/null; then
live_uuids=$(nvidia-smi --query-gpu=uuid --format=csv,noheader,nounits 2>/dev/null | tr -d ' ' || true)
fi
live_uuids="${live_uuids:-}"
local missing=0
while IFS= read -r uuid; do
[[ -z "$uuid" ]] && continue
if ! echo "$live_uuids" | grep -qF "$uuid"; then
warn "UUID ${uuid} not found in current system"
echo " Fix: run 'ods gpu reassign'"
((missing++)) || true
((fail++)) || true
fi
done < <(echo "$assignment_json" | jq -r '.gpu_assignment.services[].gpus[]' 2>/dev/null)
if [[ "$missing" -eq 0 ]]; then
success "All assigned GPU UUIDs are present in system"
((pass++)) || true
fi
else
warn "Failed to decode GPU_ASSIGNMENT_JSON_B64"
((fail++)) || true
fi
fi
# Check 3: LLAMA_ARG_SPLIT_MODE vs assigned GPU count
local split_mode="${LLAMA_ARG_SPLIT_MODE:-}"
local llama_uuids="${LLAMA_SERVER_GPU_UUIDS:-}"
if [[ -n "$split_mode" && "$split_mode" != "none" ]]; then
local llama_count
llama_count=$(echo "$llama_uuids" | tr ',' '\n' | grep -c . 2>/dev/null) || llama_count=1
if [[ "$llama_count" -gt 1 ]]; then
success "LLAMA_ARG_SPLIT_MODE=${split_mode} is consistent with ${llama_count} llama GPUs"
((pass++)) || true
else
warn "LLAMA_ARG_SPLIT_MODE=${split_mode} is set but only 1 GPU assigned to llama-server"
echo " Fix: run 'ods gpu reassign' or set LLAMA_ARG_SPLIT_MODE=none in .env"
((fail++)) || true
fi
fi
echo ""
echo " Result: ${pass} check(s) passed, ${fail} failed"
[[ "$fail" -eq 0 ]]
}
# Helper: write AMD-specific env vars from topology JSON for manual assignment
_gpu_reassign_write_amd_env() {
local topo_json="$1" indices_csv="$2"
_env_set "LLAMA_SERVER_GPU_INDICES" "$indices_csv"
_env_set "ROCR_VISIBLE_DEVICES" "$indices_csv"
_gpu_reassign_update_amd_arch_env "$topo_json" "$indices_csv"
local video_gid render_gid
video_gid=$(getent group video 2>/dev/null | cut -d: -f3) || video_gid="44"
render_gid=$(getent group render 2>/dev/null | cut -d: -f3) || render_gid="992"
_env_set "VIDEO_GID" "$video_gid"
_env_set "RENDER_GID" "$render_gid"
}
_gpu_reassign_update_amd_arch_env() {
local topo_json="$1" indices_csv="$2"
local unique_gfx gfx_ver
unique_gfx=$(echo "$topo_json" | jq -r --arg csv "$indices_csv" '
($csv | split(",") | map(gsub("^[[:space:]]+|[[:space:]]+$"; "")) | map(select(length > 0))) as $idxs |
[.gpus[] | select((.index | tostring) as $i | $idxs | index($i)) | .gfx_version // empty] |
map(select(. != "" and . != "null" and . != "unknown")) |
unique
' 2>/dev/null) || unique_gfx="[]"
if [[ "$(echo "$unique_gfx" | jq 'length' 2>/dev/null || echo 0)" -eq 1 ]]; then
gfx_ver=$(echo "$unique_gfx" | jq -r '.[0]')
else
gfx_ver=""
fi
# ROCm image only, and only for a GPU it was not built for; the Vulkan
# image never reads it (installers/lib/amd-runtime.sh).
local hsa_override=""
if [[ -f "$INSTALL_DIR/installers/lib/amd-runtime.sh" ]]; then
# shellcheck source=installers/lib/amd-runtime.sh
. "$INSTALL_DIR/installers/lib/amd-runtime.sh"
hsa_override="$(ods_amd_hsa_override_for_target "${AMD_INFERENCE_BACKEND:-vulkan}" "$gfx_ver")"
fi
if [[ -n "$hsa_override" ]]; then
_env_set "HSA_OVERRIDE_GFX_VERSION" "$hsa_override"
else
_env_unset "HSA_OVERRIDE_GFX_VERSION"
fi
}
# VRAM held on each GPU by this installation's own llama-server, printed as
# "<gpu-uuid> <MiB>" lines. Reassignment recreates that container, so its
# allocation is free for the new plan; counting it as used made the loaded
# model fail to fit its own reassignment (#8087). Ownership must be proven:
# the container is this installation's llama-server Compose service and each
# GPU process runs in its cgroup. Anything not proven is not credited.
_gpu_reassign_owned_llama_vram() {
local container="${SERVICE_CONTAINERS[llama-server]:-ods-llama-server}"
local proc_root="${ODS_PROC_ROOT:-/proc}"
local inspected container_id workdir config_files service running install_real
# No such container (or no Docker access) means nothing of ours to credit.
inspected=$(docker inspect -f '{{.Id}}|{{index .Config.Labels "com.docker.compose.project.working_dir"}}|{{index .Config.Labels "com.docker.compose.project.config_files"}}|{{index .Config.Labels "com.docker.compose.service"}}|{{.State.Running}}' \
"$container" 2>/dev/null) || return 0
IFS='|' read -r container_id workdir config_files service running <<< "$inspected"
[[ "$container_id" =~ ^[0-9a-f]{64}$ && "$service" == llama-server && "$running" == true ]] || return 0
install_real=$(cd -P "$INSTALL_DIR" && pwd)
[[ "$workdir" == "$INSTALL_DIR" || "$workdir" == "$install_real" ]] || return 0
[[ ",$config_files," == *",$workdir/docker-compose.base.yml,"* ]] || return 0
local apps pid uuid used
# A driver that cannot list compute processes leaves the budget as it was.
apps=$(nvidia-smi --query-compute-apps=pid,gpu_uuid,used_memory \
--format=csv,noheader,nounits 2>/dev/null) || return 0
while IFS=', ' read -r pid uuid used; do
[[ "$pid" =~ ^[0-9]+$ && "$used" =~ ^[0-9]+$ && -n "$uuid" ]] || continue
# A process that exited since the listing has nothing left to credit.
grep -Fq -- "$container_id" "$proc_root/$pid/cgroup" 2>/dev/null || continue
printf '%s %s\n' "$uuid" "$used"
done <<< "$apps"
}
_gpu_reassign() {
local auto_mode=0 dry_run=0 manual_mode=0
while [[ $# -gt 0 ]]; do
case "$1" in
--auto) auto_mode=1 ;;
--dry-run) dry_run=1 ;;
--manual) manual_mode=1 ;;
esac
shift
done
check_install
load_env
echo -e "${BLUE}━━━ GPU Reassign ━━━${NC}"
echo ""
if [[ "${GPU_BACKEND:-}" == "apple" ]]; then
warn "GPU reassignment is not applicable on Apple Silicon (single integrated GPU)."
return 1
fi
if ! command -v jq &>/dev/null; then
warn "jq not found — required for GPU reassignment"
return 1
fi
local backend="${GPU_BACKEND:-nvidia}"
local topo_lib topo_detect_fn
if [[ "$backend" == "amd" ]]; then
topo_lib="$SCRIPT_DIR/installers/lib/amd-topo.sh"
topo_detect_fn="detect_amd_topo"
else
topo_lib="$SCRIPT_DIR/installers/lib/nvidia-topo.sh"
topo_detect_fn="detect_nvidia_topo"
if ! command -v nvidia-smi &>/dev/null; then
warn "nvidia-smi not found — GPU reassignment unavailable"
return 1
fi
fi
local assign_script="$SCRIPT_DIR/scripts/assign_gpus.py"
[[ -f "$topo_lib" ]] || { warn "Topology library not found: $topo_lib"; return 1; }
[[ -f "$assign_script" ]] || { warn "Assignment script not found: $assign_script"; return 1; }
# warn and err are already defined; source is safe
. "$topo_lib"
log "Detecting GPU topology..."
local topo_json
topo_json=$($topo_detect_fn) || error "Failed to detect GPU topology"
if [[ "$backend" == "nvidia" ]] \
&& [[ "$(echo "$topo_json" | jq -r '.mig_enabled // false')" == "true" ]] \
&& ! echo "$topo_json" | jq -e '
(.gpus | type == "array" and length > 0)
and all(.gpus[];
.mig_instance == true
and (.uuid | type == "string" and startswith("MIG-"))
and (.memory_gb | type == "number" and . > 0)
)
' >/dev/null 2>&1; then
warn "GPU reassignment is disabled on NVIDIA MIG hosts until topology detection exposes assignable MIG instances."
return 1
fi
# Persist topology for the dashboard API
mkdir -p "$INSTALL_DIR/config"
echo "$topo_json" > "$INSTALL_DIR/config/gpu-topology.json"
chmod 644 "$INSTALL_DIR/config/gpu-topology.json"
# Determine model size
local model_size_mb="${LLM_MODEL_SIZE_MB:-}"
if [[ -z "$model_size_mb" ]]; then
local gguf_file="${GGUF_FILE:-}"
local gguf_path="$INSTALL_DIR/data/models/${gguf_file}"
if [[ -n "$gguf_file" && -f "$gguf_path" ]]; then
model_size_mb=$(du -m "$gguf_path" | awk '{print $1}')
log "Estimated model size from file: ${model_size_mb} MB"
else
echo -n " Model size not found in .env. Enter size in MB (e.g. 40000 for a 40 GB model): "
read -r model_size_mb
[[ "$model_size_mb" =~ ^[0-9]+$ ]] || error "Invalid model size: $model_size_mb"
fi
fi
# The assignment budgets each GPU by its free VRAM. Credit back what this
# installation's llama-server holds (capped at the GPU's total) so the
# loaded model can be reassigned; config/gpu-topology.json keeps the
# driver's figures.
local assign_topo_json="$topo_json" reclaimed=""
if [[ "$backend" == "nvidia" ]]; then
reclaimed=$(_gpu_reassign_owned_llama_vram)
fi
if [[ -n "$reclaimed" ]]; then
assign_topo_json=$(jq --arg reclaimed "$reclaimed" '
($reclaimed | split("\n") | map(select(length > 0) | split(" "))
| reduce .[] as $row ({}; .[$row[0]] += ($row[1] | tonumber))) as $credit
| .gpus |= map(
if ($credit[.uuid] // 0) > 0 and .memory_free_gb != null then
.memory_free_gb = ([.memory_free_gb + $credit[.uuid] / 1024, .memory_gb]
| min | . * 10 | round / 10)
else . end)' <<< "$topo_json")
log "Counting $(awk '{ total += $2 } END { print total }' <<< "$reclaimed") MiB held by this installation's llama-server as available; reassignment recreates it."
fi
# Write topology to tmpfile and run assignment
local tmpdir
tmpdir=$(mktemp -d)
trap "rm -rf '$tmpdir'" RETURN
echo "$assign_topo_json" > "$tmpdir/topo.json"
local env_backup="$tmpdir/env.before"
cp "$INSTALL_DIR/.env" "$env_backup"
local enabled_services="${ENABLED_SERVICES:-llama_server,whisper,comfyui,embeddings}"
_gpu_reassign_reload_env() {
unset GPU_ASSIGNMENT_JSON_B64
unset LLAMA_SERVER_GPU_UUIDS LLAMA_SERVER_GPU_INDICES
unset LLAMA_ARG_SPLIT_MODE LLAMA_ARG_TENSOR_SPLIT
unset WHISPER_GPU_UUID COMFYUI_GPU_UUID EMBEDDINGS_GPU_UUID
unset WHISPER_GPU_INDEX COMFYUI_GPU_INDEX EMBEDDINGS_GPU_INDEX
unset ROCR_VISIBLE_DEVICES HSA_OVERRIDE_GFX_VERSION
unset VIDEO_GID RENDER_GID
load_env
}
_gpu_reassign_stack_ready() {
local -a compose_flags=("$@")
local configured_services
configured_services=$(docker compose "${compose_flags[@]}" config --services 2>/dev/null) \
|| return 1
local required_service container_id state status health
for required_service in dashboard-api llama-server; do
grep -qxF "$required_service" <<<"$configured_services" || return 1
container_id=$(docker compose "${compose_flags[@]}" ps -q "$required_service" 2>/dev/null) \
|| return 1
[[ -n "$container_id" ]] || return 1
state=$(docker inspect \
--format '{{.State.Status}} {{if .State.Health}}{{.State.Health.Status}}{{end}}' \
"$container_id" 2>/dev/null) || return 1
read -r status health <<<"$state"
[[ "$status" == "running" ]] || return 1
[[ -z "$health" || "$health" == "healthy" ]] || return 1
done
local dashboard_port="${DASHBOARD_API_PORT:-3002}"
curl --silent --show-error --fail --max-time 5 \
"http://127.0.0.1:${dashboard_port}/health" >/dev/null 2>&1 \
|| return 1
local llm_port="${OLLAMA_PORT:-${LLAMA_SERVER_PORT:-11434}}"
local llm_base_path="${LLM_API_BASE_PATH:-/v1}"
llm_base_path="/${llm_base_path#/}"
llm_base_path="${llm_base_path%/}"
local models_response model_id completion_payload completion_response
models_response=$(curl --silent --show-error --fail --max-time 10 \
"http://127.0.0.1:${llm_port}${llm_base_path}/models" 2>/dev/null) \
|| return 1
model_id=$(printf '%s' "$models_response" | jq -er '.data[0].id') || return 1
completion_payload=$(jq -cn --arg model "$model_id" '{
model: $model,
messages: [{role: "user", content: "Reply with OK."}],
max_tokens: 1,
temperature: 0
}') || return 1
completion_response=$(curl --silent --show-error --fail --max-time 30 \
"http://127.0.0.1:${llm_port}${llm_base_path}/chat/completions" \
-H "Content-Type: application/json" \
-d "$completion_payload" 2>/dev/null) || return 1
printf '%s' "$completion_response" \
| jq -e '.choices[0].message.content != null' >/dev/null 2>&1
}
_gpu_reassign_wait_for_stack() {
local -a compose_flags=("$@")
local attempts="${ODS_GPU_REASSIGN_HEALTH_ATTEMPTS:-30}"
local interval="${ODS_GPU_REASSIGN_HEALTH_INTERVAL_SECONDS:-3}"
[[ "$attempts" =~ ^[1-9][0-9]*$ ]] || attempts=30
[[ "$interval" =~ ^[0-9]+([.][0-9]+)?$ ]] || interval=3
local attempt
for ((attempt = 1; attempt <= attempts; attempt++)); do
if _gpu_reassign_stack_ready "${compose_flags[@]}"; then
return 0
fi
(( attempt < attempts )) && sleep "$interval"
done
return 1
}
_gpu_reassign_apply_with_rollback() {
local backup_file="$1"
shift
# Values exported by the initial load_env take precedence over .env in
# Compose. Reload after mutation so the first recreate receives the
# assignment that was just persisted.
_gpu_reassign_reload_env
if docker compose "$@" up -d --force-recreate \
&& _gpu_reassign_wait_for_stack "$@"; then
return 0
fi
warn "GPU assignment did not become healthy; restoring the previous .env"
cp "$backup_file" "$INSTALL_DIR/.env"
_gpu_reassign_reload_env
if docker compose "$@" up -d --force-recreate \
&& _gpu_reassign_wait_for_stack "$@"; then
return 1
fi
return 2
}
# ── Manual assignment mode ──
if [[ "$manual_mode" -eq 1 ]]; then
echo ""
echo " Available GPUs:"
if [[ "$backend" == "amd" ]]; then
# List AMD GPUs from topology JSON
echo "$topo_json" | jq -r '.gpus[] |
" GPU\(.index): \(.name) (\(.memory_gb) GB \(.memory_type // "discrete"))"
' 2>/dev/null
else
local gpu_list_smi
gpu_list_smi=$(nvidia-smi --query-gpu=index,name,memory.total \
--format=csv,noheader,nounits 2>/dev/null) || { warn "nvidia-smi failed"; return; }
while IFS= read -r gline; do
[[ -z "$gline" ]] && continue
local idx gname gmem
idx=$(echo "$gline" | awk -F', ' '{gsub(/ /,"",$1); print $1}')
gname=$(echo "$gline" | awk -F', ' '{gsub(/^ +/,"",$2); print $2}')
gmem=$(echo "$gline" | awk -F', ' '{gsub(/ /,"",$3); printf "%.0f GB", $3/1024}')
echo " GPU${idx}: ${gname} (${gmem})"
done <<<"$gpu_list_smi"
fi
echo ""
local _manual_llama _manual_whisper _manual_comfyui _manual_embeddings
echo -n " GPU(s) for llama-server (comma-separated indices, e.g. 0,1,2,3): "
read -r _manual_llama
echo -n " GPU for whisper (index, blank keeps current): "
read -r _manual_whisper
echo -n " GPU for comfyui (index, blank keeps current): "
read -r _manual_comfyui
echo -n " GPU for embeddings (index, blank keeps current): "
read -r _manual_embeddings
local current_assignment_json=""
local current_assignment_b64="${GPU_ASSIGNMENT_JSON_B64:-}"
if [[ -n "$current_assignment_b64" ]]; then
current_assignment_json=$(echo "$current_assignment_b64" | tr -d '\r' | tr -d '[:space:]' \
| base64 -d 2>/dev/null || true)
echo "$current_assignment_json" | jq -e \
'.gpu_assignment.services | type == "object"' >/dev/null 2>&1 \
|| current_assignment_json=""
fi
_current_manual_service_index() {
local service="$1" env_index_key="$2" env_uuid_key="$3"
local current=""
if [[ -n "$current_assignment_json" ]]; then
current=$(echo "$current_assignment_json" | jq -r --arg service "$service" \
'.gpu_assignment.services[$service].gpu_indices[0] // empty')
fi
if [[ -z "$current" && "$backend" == "amd" && -n "$env_index_key" ]]; then
current="${!env_index_key:-}"
fi
if [[ -z "$current" && -n "$env_uuid_key" ]]; then
local current_uuid="${!env_uuid_key:-}"
if [[ -n "$current_uuid" ]]; then
current=$(echo "$topo_json" | jq -r --arg uuid "$current_uuid" \
'.gpus[] | select(.uuid == $uuid) | .index')
fi
fi
local normalized_services=",${enabled_services//[[:space:]]/},"
if [[ -z "$current" \
&& ( "$normalized_services" == *",$service,"* \
|| "$normalized_services" == *",all,"* ) ]]; then
current=$(echo "$topo_json" | jq -r '.gpus[0].index // empty')
fi
echo "$current"
}
[[ -n "$(echo "$_manual_whisper" | tr -d '[:space:]')" ]] \
|| _manual_whisper=$(_current_manual_service_index \
"whisper" "WHISPER_GPU_INDEX" "WHISPER_GPU_UUID")
[[ -n "$(echo "$_manual_comfyui" | tr -d '[:space:]')" ]] \
|| _manual_comfyui=$(_current_manual_service_index \
"comfyui" "COMFYUI_GPU_INDEX" "COMFYUI_GPU_UUID")
[[ -n "$(echo "$_manual_embeddings" | tr -d '[:space:]')" ]] \
|| _manual_embeddings=$(_current_manual_service_index \
"embeddings" "EMBEDDINGS_GPU_INDEX" "EMBEDDINGS_GPU_UUID")
_normalize_manual_gpu_indices() {
local raw="$1" allow_blank="${2:-false}" allow_multiple="${3:-true}" normalized idx
normalized=$(echo "$raw" | tr -d '[:space:]')
if [[ -z "$normalized" ]]; then
[[ "$allow_blank" == "true" ]] && return 0
return 1
fi
[[ "$normalized" =~ ^[0-9]+(,[0-9]+)*$ ]] || return 1
[[ "$allow_multiple" == "true" || "$normalized" != *,* ]] || return 1
local -A seen=()
local validated=() requested=()
IFS=',' read -ra requested <<< "$normalized"
for idx in "${requested[@]}"; do
[[ -z "${seen[$idx]+x}" ]] || return 1
echo "$topo_json" | jq -e --argjson idx "$idx" \
'.gpus | any(.index == $idx)' >/dev/null || return 1
seen[$idx]=1
validated+=("$idx")
done
local IFS=,
echo "${validated[*]}"
}
_manual_llama=$(_normalize_manual_gpu_indices "$_manual_llama") \
|| error "Invalid llama-server GPU list. Use unique indices shown above."
_manual_whisper=$(_normalize_manual_gpu_indices "$_manual_whisper" true false) \
|| error "Invalid Whisper GPU index."
_manual_comfyui=$(_normalize_manual_gpu_indices "$_manual_comfyui" true false) \
|| error "Invalid ComfyUI GPU index."
_manual_embeddings=$(_normalize_manual_gpu_indices "$_manual_embeddings" true false) \
|| error "Invalid embeddings GPU index."
_get_uuid() {
echo "$topo_json" | jq -r --argjson idx "$1" \
'.gpus[] | select(.index == $idx) | .uuid'
}
local llama_uuid_list=""
for _idx in $(echo "$_manual_llama" | tr ',' ' '); do
_idx=$(echo "$_idx" | tr -d ' ')
local _u; _u=$(_get_uuid "$_idx")
[[ -n "$_u" ]] && llama_uuid_list="${llama_uuid_list:+$llama_uuid_list,}$_u"
done
local whisper_uuid_m="" comfyui_uuid_m="" embeddings_uuid_m=""
[[ -n "$_manual_whisper" ]] && whisper_uuid_m=$(_get_uuid "$(echo "$_manual_whisper" | tr -d ' ')")
[[ -n "$_manual_comfyui" ]] && comfyui_uuid_m=$(_get_uuid "$(echo "$_manual_comfyui" | tr -d ' ')")
[[ -n "$_manual_embeddings" ]] && embeddings_uuid_m=$(_get_uuid "$(echo "$_manual_embeddings" | tr -d ' ')")
# How many llama GPUs?
local llama_gpu_count
llama_gpu_count=$(echo "$_manual_llama" | tr ',' '\n' | grep -c '[0-9]' || true)
local split_mode_m="none" parallelism_mode_m="none" tensor_split_m=""
if [[ "$llama_gpu_count" -gt 1 ]]; then
echo -n " Parallelism mode for llama-server (tensor/pipeline/none) [tensor]: "
read -r _para
case "${_para:-tensor}" in
tensor|hybrid)
# Layer split on every GPU: CUDA row split fails at model
# load from llama.cpp b9890, Vulkan has no row split, and
# the HIP backend shares CUDA's split code.
split_mode_m="layer"
parallelism_mode_m="tensor"
tensor_split_m=$(printf '1,%.0s' $(seq 1 "$llama_gpu_count"))
tensor_split_m="${tensor_split_m%,}"
;;
pipeline)
split_mode_m="layer"
parallelism_mode_m="pipeline"
;;
none)
split_mode_m="none"
parallelism_mode_m="none"
;;
*) error "Invalid parallelism mode. Choose tensor, pipeline, or none." ;;
esac
fi
_manual_service_json() {
local indices_csv="$1"
[[ -n "$indices_csv" ]] || { echo "null"; return; }
echo "$topo_json" | jq -c --arg csv "$indices_csv" '
($csv | split(",") | map(tonumber)) as $indices |
{
gpus: [
$indices[] as $idx |
.gpus[] |
select(.index == $idx) |
.uuid
],
gpu_indices: $indices
}
'
}
local llama_service_json whisper_service_json comfyui_service_json embeddings_service_json
llama_service_json=$(_manual_service_json "$_manual_llama")
whisper_service_json=$(_manual_service_json "$_manual_whisper")
comfyui_service_json=$(_manual_service_json "$_manual_comfyui")
embeddings_service_json=$(_manual_service_json "$_manual_embeddings")
local manual_assignment_json
manual_assignment_json=$(jq -cn \
--argjson llama "$llama_service_json" \
--argjson whisper "$whisper_service_json" \
--argjson comfyui "$comfyui_service_json" \
--argjson embeddings "$embeddings_service_json" \
--arg mode "$parallelism_mode_m" \
--argjson count "$llama_gpu_count" \
--arg tensor_split "$tensor_split_m" '
{
gpu_assignment: {
version: "1.0",
strategy: "manual",
services: (
{
llama_server: (
$llama + {
parallelism: (
{
mode: $mode,
tensor_parallel_size: (
if $mode == "tensor" then $count else 1 end
),
pipeline_parallel_size: (
if $mode == "pipeline" then $count else 1 end
),
gpu_memory_utilization: (
if $mode == "tensor" then 0.93 else 0.95 end
)
} + (
if $tensor_split == "" then {}
else {
tensor_split: (
$tensor_split |
split(",") |
map(tonumber)
)
}
end
)
)
}
)
}
+ (if $whisper == null then {} else {whisper: $whisper} end)
+ (if $comfyui == null then {} else {comfyui: $comfyui} end)
+ (if $embeddings == null then {} else {embeddings: $embeddings} end)
)
}
}
') || error "Failed to build manual GPU assignment"
if [[ "$dry_run" -eq 1 ]]; then
echo ""
echo " Dry run — manual assignment:"
echo "$manual_assignment_json" | jq '.gpu_assignment'
return
fi
local manual_assignment_b64
if [[ "$(uname)" == "Linux" ]]; then
manual_assignment_b64=$(echo "$manual_assignment_json" | base64 -w0)
else
manual_assignment_b64=$(echo "$manual_assignment_json" | base64 | tr -d '\r\n')
fi
log "Updating .env with manual assignment..."
_env_set "GPU_ASSIGNMENT_JSON_B64" "$manual_assignment_b64"
_env_set "LLAMA_SERVER_GPU_UUIDS" "$llama_uuid_list"
_env_set "LLAMA_SERVER_GPU_INDICES" "$_manual_llama"
_env_set "LLAMA_ARG_SPLIT_MODE" "$split_mode_m"
_env_set "LLAMA_ARG_TENSOR_SPLIT" "$tensor_split_m"
_env_set "WHISPER_GPU_UUID" "$whisper_uuid_m"
_env_set "COMFYUI_GPU_UUID" "$comfyui_uuid_m"
_env_set "EMBEDDINGS_GPU_UUID" "$embeddings_uuid_m"
# AMD-specific: write render node and ROCR env vars
if [[ "$backend" == "amd" ]]; then
_gpu_reassign_write_amd_env "$topo_json" "$_manual_llama"
_env_set "WHISPER_GPU_INDEX" "$_manual_whisper"
_env_set "COMFYUI_GPU_INDEX" "$_manual_comfyui"
_env_set "EMBEDDINGS_GPU_INDEX" "$_manual_embeddings"
fi
success "Manual GPU assignment saved"
echo ""
# Without a terminal (a script, cron, ssh), take the documented default
# instead of dying on EOF after .env has already been rewritten.
read -p " Apply changes now? [Y/n] " -r || REPLY=""
case "${REPLY:-y}" in
y|Y|"")
local _flags_str _flags=()
_flags_str=$(get_compose_flags)
read -ra _flags <<< "$_flags_str"
cd "$INSTALL_DIR"
log "Recreating all containers with new GPU assignment..."
local apply_rc=0
_gpu_reassign_apply_with_rollback "$env_backup" "${_flags[@]}" \
|| apply_rc=$?
case "$apply_rc" in
0) success "All services recreated with new GPU assignment" ;;
1) error "GPU assignment failed to apply; the previous configuration and containers were restored" ;;
*) error "GPU assignment failed and automatic rollback could not recreate the previous stack" ;;
esac
;;
*) echo " Run 'ods restart' when ready." ;;
esac
return
fi
log "Running assignment algorithm (model: ${model_size_mb} MB)..."
local assignment_json
assignment_json=$(python3 "$assign_script" \
--topology "$tmpdir/topo.json" \
--model-size "$model_size_mb" \
--enabled-services "$enabled_services") || error "GPU assignment failed"
if [[ "$dry_run" -eq 1 ]]; then
echo ""
echo " Dry run — proposed assignment:"
echo "$assignment_json" | jq '.gpu_assignment' 2>/dev/null || echo "$assignment_json"
return
fi
# Extract individual env vars from assignment JSON
local strategy llama_uuids llama_indices split_mode tensor_split
local whisper_uuid comfyui_uuid embeddings_uuid
strategy=$(echo "$assignment_json" | jq -r '.gpu_assignment.strategy // "unknown"')
llama_uuids=$(echo "$assignment_json" | jq -r '(.gpu_assignment.services.llama_server.gpus // []) | join(",")' 2>/dev/null || echo "")
llama_indices=$(echo "$assignment_json" | jq -r '(.gpu_assignment.services.llama_server.gpu_indices // []) | map(tostring) | join(",")' 2>/dev/null || echo "")
[[ -n "$llama_uuids" && -n "$llama_indices" ]] \
|| error "GPU assignment did not contain a usable llama-server mapping"
local _para_mode
_para_mode=$(echo "$assignment_json" | jq -r '.gpu_assignment.services.llama_server.parallelism.mode // "none"')
# Layer split for every multi-GPU mode: CUDA row split fails at model load
# from llama.cpp b9890, and Vulkan has no row split.
case "$_para_mode" in
tensor|hybrid) split_mode="layer" ;;
pipeline) split_mode="layer" ;;
*) split_mode="none" ;;
esac
tensor_split=$(echo "$assignment_json" | jq -r '
(.gpu_assignment.services.llama_server.parallelism.tensor_split // []) as $ts |
if ($ts | length) > 0 then $ts | map(tostring) | join(",")
else ""
end' 2>/dev/null || echo "")
whisper_uuid=$(echo "$assignment_json" | jq -r '.gpu_assignment.services.whisper.gpus[0]? // ""' 2>/dev/null || echo "")
comfyui_uuid=$(echo "$assignment_json" | jq -r '.gpu_assignment.services.comfyui.gpus[0]? // ""' 2>/dev/null || echo "")
embeddings_uuid=$(echo "$assignment_json" | jq -r '.gpu_assignment.services.embeddings.gpus[0]? // ""' 2>/dev/null || echo "")
# base64-encode assignment JSON for .env storage (cross-platform)
local assignment_b64
if [[ "$(uname)" == "Linux" ]]; then
assignment_b64=$(echo "$assignment_json" | jq -c '.' | base64 -w0)
else
assignment_b64=$(echo "$assignment_json" | jq -c '.' | base64)
fi
# Write to .env
log "Updating .env..."
_env_set "LLAMA_SERVER_GPU_UUIDS" "$llama_uuids"
_env_set "LLAMA_SERVER_GPU_INDICES" "$llama_indices"
_env_set "LLAMA_ARG_SPLIT_MODE" "$split_mode"
_env_set "LLAMA_ARG_TENSOR_SPLIT" "$tensor_split"
_env_set "WHISPER_GPU_UUID" "$whisper_uuid"
_env_set "COMFYUI_GPU_UUID" "$comfyui_uuid"
_env_set "EMBEDDINGS_GPU_UUID" "$embeddings_uuid"
_env_set "GPU_ASSIGNMENT_JSON_B64" "$assignment_b64"
# AMD-specific: write render node, ROCR_VISIBLE_DEVICES, gfx overrides
if [[ "$backend" == "amd" ]]; then
# Extract llama GPU indices from assignment by matching UUIDs to topology
local llama_idx_csv=""
while IFS= read -r _uuid; do
[[ -z "$_uuid" ]] && continue
local _idx
_idx=$(echo "$topo_json" | jq -r --arg u "$_uuid" '.gpus[] | select(.uuid == $u) | .index')
llama_idx_csv="${llama_idx_csv:+$llama_idx_csv,}${_idx}"
done < <(echo "$assignment_json" | jq -r '.gpu_assignment.services.llama_server.gpus[]' 2>/dev/null)
_env_set "LLAMA_SERVER_GPU_INDICES" "$llama_idx_csv"
_env_set "ROCR_VISIBLE_DEVICES" "$llama_idx_csv"
_gpu_reassign_update_amd_arch_env "$topo_json" "$llama_idx_csv"
# Write GPU index for auxiliary services (whisper, comfyui, embeddings)
_amd_svc_env() {
local svc_prefix="$1" svc_uuid="$2"
local _si=""
if [[ -n "$svc_uuid" ]]; then
_si=$(echo "$topo_json" | jq -r --arg u "$svc_uuid" '.gpus[] | select(.uuid == $u) | .index')
[[ "$_si" != "null" ]] || _si=""
fi
_env_set "${svc_prefix}_GPU_INDEX" "$_si"
}
_amd_svc_env "WHISPER" "$whisper_uuid"
_amd_svc_env "COMFYUI" "$comfyui_uuid"
_amd_svc_env "EMBEDDINGS" "$embeddings_uuid"
# Detect and persist GID values for AMD container group_add
local video_gid render_gid
video_gid=$(getent group video 2>/dev/null | cut -d: -f3) || video_gid="44"
render_gid=$(getent group render 2>/dev/null | cut -d: -f3) || render_gid="992"
_env_set "VIDEO_GID" "$video_gid"
_env_set "RENDER_GID" "$render_gid"
fi
success "GPU assignment updated (strategy: ${strategy})"
echo ""
# Without a terminal (a script, cron, ssh), take the documented default
# instead of dying on EOF after .env has already been rewritten.
read -p " Apply changes now? [Y/n] " -r || REPLY=""
case "${REPLY:-y}" in
y|Y|"")
local _flags_str _flags=()
_flags_str=$(get_compose_flags)
read -ra _flags <<< "$_flags_str"
cd "$INSTALL_DIR"
log "Recreating all containers with new GPU assignment..."
local apply_rc=0
_gpu_reassign_apply_with_rollback "$env_backup" "${_flags[@]}" \
|| apply_rc=$?
case "$apply_rc" in
0) success "All services recreated with new GPU assignment" ;;
1) error "GPU assignment failed to apply; the previous configuration and containers were restored" ;;
*) error "GPU assignment failed and automatic rollback could not recreate the previous stack" ;;
esac
;;
*) echo " Run 'ods restart' when ready." ;;
esac
}
cmd_gpu() {
local subcommand="${1:-status}"
shift 2>/dev/null || true
case "$subcommand" in
status|s) _gpu_status "$@" ;;
topology|topo|t) _gpu_topology "$@" ;;
assignment|assign|a) _gpu_assignment "$@" ;;
validate|v) _gpu_validate "$@" ;;
reassign) _gpu_reassign "$@" ;;
help|--help|-h)
echo "Usage: ods gpu [subcommand]"
echo ""
echo "Subcommands:"
echo " status Per-GPU metrics table with VRAM, util, temp, power"
echo " topology Show GPU interconnect topology (NVLink, PCIe, NUMA)"
echo " assignment Show current service→GPU mapping from .env"
echo " validate Check GPU config is consistent with live system"
echo " reassign Re-run GPU assignment algorithm and update .env"
echo ""
echo "Options for reassign:"
echo " --auto Run automatic assignment without interactive prompts"
echo " --dry-run Show proposed assignment without writing .env"
echo " --manual Manually specify GPU assignment interactively"
;;
*) error "Unknown gpu subcommand: '${subcommand}'. Run 'ods gpu help'" ;;
esac
}
cmd_repair() {
check_install
cd "$INSTALL_DIR"
load_env
sr_load
local target="${1:-voice}"
case "$target" in
hermes-workers|slash-workers)
local script="$INSTALL_DIR/scripts/prune-hermes-slash-workers.sh"
[[ -x "$script" ]] || error "Hermes slash worker repair script not found or not executable: $script"
"$script" --force
;;
rootless-ownership|rootless)
local script="$INSTALL_DIR/lib/rootless-ownership.sh"
[[ -f "$script" ]] || error "Rootless ownership helper not found: $script"
# shellcheck source=lib/rootless-ownership.sh
source "$script"
ods_fix_rootless_ownership "$INSTALL_DIR"
;;
voice|stt|tts)
local flags_str
flags_str=$(get_compose_flags)
local -a flags
read -ra flags <<< "$flags_str"
local services
services=$(docker compose "${flags[@]}" config --services 2>/dev/null || true)
local missing=()
grep -qx "whisper" <<< "$services" || missing+=("whisper")
grep -qx "tts" <<< "$services" || missing+=("tts")
if (( ${#missing[@]} > 0 )); then
log_error "Voice services are not in this compose stack: ${missing[*]}"
echo " Enable voice, or add the whisper/tts extension compose files, then retry."
return 1
fi
_compose_run_with_summary "Starting voice services" "${flags[@]}" up -d whisper tts
local model port url tts_port tts_url
model=$(_env_get_raw AUDIO_STT_MODEL)
[[ -z "$model" ]] && model="Systran/faster-whisper-base"
port=$(_env_get_raw WHISPER_PORT)
[[ -z "$port" ]] && port="9000"
url="http://127.0.0.1:${port}"
tts_port=$(_env_get_raw TTS_PORT)
[[ -z "$tts_port" ]] && tts_port="8880"
tts_url="http://127.0.0.1:${tts_port}"
local ready=false
for _i in $(seq 1 45); do
if curl -sf --max-time 2 "${url}/health" >/dev/null 2>&1; then
ready=true
break
fi
sleep 2
done
if ! $ready; then
log_error "Whisper STT is still not responding. Check: ods logs whisper"
return 1
fi
cmd_stt download "$model"
local tts_ready=false
for _i in $(seq 1 45); do
if curl -sf --max-time 2 "${tts_url}/health" >/dev/null 2>&1; then
tts_ready=true
break
fi
sleep 2
done
if ! $tts_ready; then
log_error "Kokoro TTS is still not responding. Check: ods logs tts"
return 1
fi
success "Voice repair complete"
;;
*)
log "Usage: ods repair [voice|hermes-workers|rootless-ownership]"
log_error "Unknown repair target: $target"
return 1
;;
esac
}
#=============================================================================
# Templates
#=============================================================================
_template_list() {
local templates_dir="$INSTALL_DIR/templates"
if [[ ! -d "$templates_dir" ]]; then
warn "No templates directory found at $templates_dir"
return 0
fi
# First pass: collect template rows and compute max ID width so the
# column fits IDs like "personal-knowledge-base" (23) without overflow.
local -a rows=()
local max_id_len=2 # at minimum, wide enough for the "ID" header
for f in "$templates_dir"/*.yaml "$templates_dir"/*.yml; do
[[ -f "$f" ]] || continue
local info
info=$(python3 - "$f" <<'PYEOF'
import yaml, sys
with open(sys.argv[1]) as fh:
d = yaml.safe_load(fh)
if not isinstance(d, dict) or d.get("schema_version") != "ods.templates.v1":
sys.exit(0)
t = d.get("template", {})
tid = t.get("id", "")
name = t.get("name", "")
tier = t.get("tier_minimum", "-")
svcs = ", ".join(t.get("services", []))
if tid:
print(f"{tid}\t{name}\t{tier}\t{svcs}")
PYEOF
) || continue
[[ -z "$info" ]] && continue
rows+=("$info")
local this_id="${info%%$'\t'*}"
(( ${#this_id} > max_id_len )) && max_id_len=${#this_id}
done
if [[ ${#rows[@]} -eq 0 ]]; then
log "No templates found."
return 0
fi
# Second pass: emit header, full-width separator, and rows using the
# dynamic ID column width. `hr` produces separators that span each
# column exactly, replacing the old hard-coded "----" dashes that
# left visible gaps under %-Ns padding.
printf "${CYAN}%-*s %-30s %-6s %s${NC}\n" "$max_id_len" "ID" "NAME" "TIER" "SERVICES"
printf "%-*s %-30s %-6s %s\n" \
"$max_id_len" "$(hr "$max_id_len")" "$(hr 30)" "$(hr 6)" "$(hr 8)"
local row tid tname ttier tsvcs
for row in "${rows[@]}"; do
IFS=$'\t' read -r tid tname ttier tsvcs <<< "$row"
printf "%-*s %-30s %-6s %s\n" "$max_id_len" "$tid" "$tname" "$ttier" "$tsvcs"
done
}
_template_preview() {
local template_id="${1:-}"
[[ -z "$template_id" ]] && { log "Usage: ods template preview <template-id>"; exit 1; }
local templates_dir="$INSTALL_DIR/templates"
local tmpl_file=""
for f in "$templates_dir"/*.yaml "$templates_dir"/*.yml; do
[[ -f "$f" ]] || continue
local tid
tid=$(python3 - "$f" <<'PYEOF'
import yaml, sys
with open(sys.argv[1]) as fh:
d = yaml.safe_load(fh)
if not isinstance(d, dict) or d.get("schema_version") != "ods.templates.v1":
sys.exit(0)
t = d.get("template", {})
print(t.get("id", ""))
PYEOF
) || continue
if [[ "$tid" == "$template_id" ]]; then
tmpl_file="$f"
break
fi
done
[[ -z "$tmpl_file" ]] && error "Template not found: $template_id"
python3 - "$tmpl_file" "$INSTALL_DIR" <<'PYEOF'
import yaml, sys
from pathlib import Path
with open(sys.argv[1]) as fh:
d = yaml.safe_load(fh)
t = d.get("template", {})
install_dir = Path(sys.argv[2])
print(f"Template: {t.get('name', t.get('id', ''))}")
print(f"Description: {t.get('description', '-')}")
if t.get("estimated_disk_gb"):
print(f"Estimated disk: ~{t['estimated_disk_gb']}GB")
print()
services = t.get("services", [])
ext_dir = install_dir / "extensions" / "services"
user_ext_dir = install_dir / "data" / "user-extensions"
to_enable = []
already = []
for svc in services:
cf = ext_dir / svc / "compose.yaml"
ucf = user_ext_dir / svc / "compose.yaml"
if cf.exists() or ucf.exists():
already.append(svc)
else:
to_enable.append(svc)
if already:
print(f"Already enabled: {', '.join(already)}")
if to_enable:
print(f"Will enable: {', '.join(to_enable)}")
if not to_enable:
print("Nothing to change — all services already enabled.")
PYEOF
}
_template_apply() {
local template_id="${1:-}"
[[ -z "$template_id" ]] && { log "Usage: ods template apply <template-id>"; exit 1; }
local templates_dir="$INSTALL_DIR/templates"
local services
services=$(python3 - "$templates_dir" "$template_id" <<'PYEOF'
import yaml, sys
from pathlib import Path
templates_dir = Path(sys.argv[1])
target_id = sys.argv[2]
for f in sorted(templates_dir.glob("*.yaml")) + sorted(templates_dir.glob("*.yml")):
with open(f) as fh:
d = yaml.safe_load(fh)
if not isinstance(d, dict) or d.get("schema_version") != "ods.templates.v1":
continue
t = d.get("template", {})
if t.get("id") == target_id:
print(" ".join(t.get("services", [])))
sys.exit(0)
print("", file=sys.stderr)
sys.exit(1)
PYEOF
) || error "Template not found: $template_id"
[[ -z "$services" ]] && { warn "Template has no services."; return 0; }
log "Applying template: $template_id"
local svc
local -a failed=() not_installed=()
for svc in $services; do
# Skip core services (no compose toggle needed)
local cat="${SERVICE_CATEGORIES[$svc]:-optional}"
[[ "$cat" == "core" ]] && continue
local cf="$INSTALL_DIR/extensions/services/$svc/compose.yaml"
local ucf="$INSTALL_DIR/data/user-extensions/$svc/compose.yaml"
if [[ -f "$cf" || -f "$ucf" ]]; then
log " $svc — already enabled"
continue
fi
# The CLI cannot install Library extensions; the dashboard's template
# apply does. Name them instead of reporting an unknown service.
if [[ ! -d "$INSTALL_DIR/extensions/services/$svc" && ! -d "$INSTALL_DIR/data/user-extensions/$svc" \
&& ( -d "$INSTALL_DIR/data/extensions-library/$svc" \
|| -d "$INSTALL_DIR/extensions/library/services/$svc" ) ]]; then
warn " $svc is a Library extension that is not installed"
not_installed+=("$svc")
continue
fi
log " Enabling $svc..."
if ! ( cmd_enable "$svc" ); then
warn " Failed to enable $svc (continuing)"
failed+=("$svc")
fi
done
if [[ ${#failed[@]} -eq 0 && ${#not_installed[@]} -eq 0 ]]; then
success "Template applied: $template_id"
return 0
fi
# Additive: services enabled above stay enabled, but the template is not
# in effect until the rest are, so do not report success.
if [[ ${#not_installed[@]} -gt 0 ]]; then
warn "Not installed: ${not_installed[*]}. Apply '$template_id' from the dashboard's Extensions page, which installs Library extensions."
fi
if [[ ${#failed[@]} -gt 0 ]]; then
warn "Could not enable: ${failed[*]} (see the errors above)."
fi
error "Template $template_id was only partly applied."
}
cmd_template() {
check_install
sr_load
load_env 2>/dev/null || true
local subcmd="${1:-list}"
shift || true
case "$subcmd" in
list) _template_list ;;
preview) _template_preview "$@" ;;
apply) _template_apply "$@" ;;
*) log "Usage: ods template [list|preview|apply] [template-id]"; exit 1 ;;
esac
}
cmd_help() {
sr_load
cat << EOF
${BLUE}ODS CLI v${VERSION}${NC}
Usage: ods <command> [options]
${CYAN}Commands:${NC}
gpu [status|topology|assignment|validate|reassign]
Inspect and manage multi-GPU configuration
status [--json] Show service health and GPU status (--json = machine-readable)
status-json Alias for 'status --json' (kept for back-compat)
list [--json] List all services and their status (--json = machine-readable)
enable <service> Enable an extension service
disable <service> Disable an extension service
purge <service> Permanently delete service data
preset <action> Save/load/list/delete/export/import presets
mode [local|cloud|hybrid]
Switch between local/cloud/hybrid modes
model [current|list|swap|recover]
View or change the local LLM model tier
remote-provider [status|plan|configure|test|enable|disable|remove|peer-models]
Configure, test, disable, or inspect remote GPU provider routing
stt [current|status|download] [MODEL]
View Whisper STT model, check cache, or trigger download
backup [options] Create a backup of user data and config
backup verify <id> Verify checksum integrity for a backup
restore [backup_id] Restore from a backup
rollback [snapshot] Rollback to pre-update state (after failed update)
logs <service> Tail logs for a service
restart [service] [--rebuild-images]
Restart services (all if no service specified)
start [service] [--rebuild-images]
Start services
stop [service] Stop services
update [--force] [--rebuild-images]
Pull latest images and restart (--force skips version-compat confirmation;
--rebuild-images rebuilds locally-built images so contributor edits deploy)
shell <service> Open shell in container
config [show|edit|validate]
View, edit, or validate configuration
chat "<message>" Quick chat with the LLM
benchmark Run a quick performance test
doctor [report|--json] Run diagnostics (--json writes JSON to stdout)
repair|fix [voice|hermes-workers]
Repair voice services or prune leaked Hermes slash workers
template [action] Apply pre-built service templates (list|preview|apply)
audit [extensions] Audit extension manifests and compose contracts
agent [action] Manage ods host agent (status|start|stop|restart|logs)
help Show this help
${CYAN}Preset Commands:${NC}
preset save <name> Snapshot current config (env, mode, extensions)
preset load <name> Restore a saved preset
preset list Show all saved presets
preset delete <name> Delete a saved preset
preset export <name> <file.tar.gz>
Export preset to shareable archive
preset import <file.tar.gz>
Import preset from archive
${CYAN}Mode Commands:${NC}
mode Show current mode
mode local Switch to local mode (llama-server)
mode cloud Switch to cloud mode (LiteLLM + API keys)
mode hybrid Switch to hybrid mode (local + cloud fallback)
${CYAN}Model Commands:${NC}
model current Show current model
model list List available tiers
model swap <tier> Switch to a different model tier
model recover Finish an interrupted Portal model switch
${CYAN}Dashboard Sign-in:${NC}
dashboard-login Set up or recover your dashboard password with a one-time link
(http://localhost on this machine never asks)
${CYAN}Remote Provider Commands:${NC}
remote-provider status [--json]
Show remote GPU route and egress status
remote-provider plan <action>
Preview configure/test/disable/remove as redacted JSON
remote-provider configure --base-url URL --model MODEL --api-key-stdin
Persist a direct OpenAI-compatible remote GPU provider
remote-provider test [--json]
Probe the configured provider through egress
remote-provider test --base-url URL --model MODEL --api-key-stdin
Probe a provider without writing state or secrets
remote-provider peer-models list [--json]
List authenticated remote ODS peer models
remote-provider peer-models load MODEL
Load a downloaded model on the remote ODS peer
remote-provider peer-models delete MODEL --yes
Delete a downloaded model from the remote ODS peer
${CYAN}Service aliases:${NC}
EOF
# Dynamic alias listing from registry
for sid in "${SERVICE_IDS[@]}"; do
local aliases=""
# Collect aliases for this service
for alias in "${!SERVICE_ALIASES[@]}"; do
if [[ "${SERVICE_ALIASES[$alias]}" == "$sid" && "$alias" != "$sid" ]]; then
[[ -n "$aliases" ]] && aliases="$aliases, "
aliases="$aliases$alias"
fi
done
if [[ -n "$aliases" ]]; then
printf " %-24s%s\n" "$sid" "also: $aliases"
fi
done
cat << EOF
${CYAN}Examples:${NC}
ods gpu status # Per-GPU metrics (VRAM, util, temp, power)
ods gpu topology # Show GPU interconnect topology
ods gpu assignment # Show service→GPU mapping
ods gpu validate # Validate GPU configuration
ods gpu reassign --auto # Auto-reassign GPUs after hardware change
ods status # Check all services
ods status-json # JSON summary (mode/tier/model + services)
ods list # See all available services
ods enable n8n # Enable the n8n extension
ods disable whisper # Disable Whisper STT
ods mode local # Switch to local mode
ods remote-provider test # Probe the configured remote provider route
printf '%s\n' "\$REMOTE_LLM_API_KEY" | ods remote-provider test --base-url https://gpu.example/v1 --model qwen/remote:latest --api-key-stdin
# Test a remote provider without persisting secrets
ods remote-provider peer-models list
# List models on the authenticated remote ODS peer
ods preset save my-setup # Snapshot your config
ods preset load my-setup # Restore it later
ods preset export my-setup my-setup.tar.gz
# Export preset for sharing
ods preset import shared.tar.gz
# Import preset from file
ods update --dry-run # Preview changes without applying
ods backup # Create a backup
ods backup -c # Create compressed backup
ods backup -l # List all backups
ods backup verify <id> # Verify backup integrity
ods restore # Interactive restore
ods restore 20260309-120000 # Restore specific backup
ods rollback # Rollback after failed update
ods logs llm # Watch llama-server logs (via alias)
ods restart stt # Restart Whisper (via alias)
ods chat "What is 2+2?" # Quick LLM test
ods config edit # Edit .env file
ods template list # List available templates
ods template preview creative-studio
# Preview what a template will change
ods template apply chat-playground
# Apply a template (enables services)
ods audit # Audit every extension contract
ods audit --json whisper # Audit one service as JSON
ods dashboard-login # Sign in to the dashboard from another device
ods agent status # Check host agent health
ods agent restart # Restart host agent
ods repair voice # Start voice services and cache STT model
ods repair rootless-ownership # Repair active bind mounts for rootless Docker
ods repair hermes-workers # Prune leaked Hermes slash_worker children
${CYAN}Environment:${NC}
INSTALL_DIR Installation directory (highest precedence)
ODS_HOME Legacy installation directory override
ODS_SCRIPT_HINT Populated install hint (must contain .env)
ODS_INSTALL_DIR Legacy macOS installation directory override
Without an override, ods-cli uses the install beside its resolved script or
symlink target when compose metadata is present, then falls back to ~/ods.
EOF
}
#=============================================================================
# Dashboard sign-in
#=============================================================================
# A browser on this machine (http://localhost) uses the dashboard without
# signing in. Any other route - LAN mode, ODS proxy, a reverse proxy or
# Tailscale Serve - needs a dashboard session. This prints a one-time link
# that signs a browser in; the token is only valid for 10 minutes and once.
_dashboard_lan_ip() {
if [[ "$(uname -s)" == "Darwin" ]]; then
ipconfig getifaddr en0 || ipconfig getifaddr en1
else
hostname -I | awk '{print $1}'
fi
}
cmd_dashboard_login() {
[[ $# -eq 0 ]] || error "Usage: ods dashboard-login"
local response_file http_code token port remote_port bind device fragment lan_ip
response_file=$(mktemp "${TMPDIR:-/tmp}/ods-dashboard-login.XXXXXX") \
|| error "Could not create a temporary response file"
chmod 600 "$response_file"
# _remote_provider_request is the CLI's generic authenticated Dashboard
# API call (API key from .env, never on the command line).
if ! http_code="$(_remote_provider_request POST /api/auth/dashboard-session/link "$response_file" "" 15)"; then
rm -f "$response_file"
error "The Dashboard API is not reachable. Check that ODS is running: ods status"
fi
if [[ "$http_code" != "200" ]]; then
rm -f "$response_file"
error "The Dashboard API refused the sign-in link request (HTTP $http_code)."
fi
token="$(jq -r '.token // empty' "$response_file")"
rm -f "$response_file"
[[ "$token" =~ ^[A-Za-z0-9_-]{16,128}$ ]] || error "The Dashboard API returned an unexpected sign-in token."
fragment="#ods-login=${token}"
port="$(_env_get_raw DASHBOARD_PORT)"
[[ "$port" =~ ^[0-9]+$ ]] || port="3001"
remote_port="$(_env_get_raw DASHBOARD_REMOTE_PORT)"
[[ "$remote_port" =~ ^[0-9]+$ ]] || remote_port="3011"
bind="$(_env_get_raw BIND_ADDRESS)"
device="$(_env_get_raw ODS_DEVICE_NAME)"
[[ "$device" =~ ^[A-Za-z0-9-]+$ ]] || device="ods"
echo "One-time dashboard recovery link (works once, expires in 10 minutes):"
echo "Open the link to choose your own password. No old password is required."
echo " http://localhost:${port}/${fragment}"
if _ods_cli_proxy_enabled; then
echo " http://dashboard.${device}.local/${fragment}"
fi
case "$bind" in
""|127.*|localhost|::1) ;;
0.0.0.0|::)
if ! lan_ip="$(_dashboard_lan_ip)"; then
warn "Could not detect this machine's LAN address; use its IP address below."
lan_ip=""
fi
echo " http://${lan_ip:-<this-machine-ip>}:${remote_port}/${fragment}"
;;
*) echo " http://${bind}:${remote_port}/${fragment}" ;;
esac
echo " Any other address for this ODS: add ${fragment} to the end of the URL."
echo ""
echo "On this machine, http://localhost:${port} never asks you to sign in."
echo "Network dashboard addresses require sign-in once per browser (30 days)."
}
#=============================================================================
# Main
#=============================================================================
case "${1:-help}" in
gpu|g) shift; cmd_gpu "$@" ;;
status|s) shift; cmd_status "$@" ;;
status-json) cmd_status_json ;;
list|ls) shift; cmd_list "$@" ;;
enable) shift; cmd_enable "$@" ;;
disable) shift; cmd_disable "$@" ;;
purge) shift; cmd_purge "$@" ;;
preset|p) shift; cmd_preset "$@" ;;
mode|m) shift; cmd_mode "$@" ;;
model) shift; cmd_model "$@" ;;
remote-provider) shift; cmd_remote_provider "$@" ;;
stt) shift; cmd_stt "$@" ;;
backup) shift; cmd_backup "$@" ;;
restore) shift; cmd_restore "$@" ;;
rollback) shift; cmd_rollback "$@" ;;
logs|log|l) shift; cmd_logs "$@" ;;
restart|r) shift; cmd_restart "$@" ;;
repair|fix) shift; cmd_repair "$@" ;;
start) shift; cmd_start "$@" ;;
stop) shift; cmd_stop "$@" ;;
update|u) shift; cmd_update "$@" ;;
shell|sh) shift; cmd_shell "$@" ;;
config|cfg) shift; cmd_config "$@" ;;
chat|c) shift; cmd_chat "$@" ;;
benchmark|bench|b) cmd_benchmark ;;
doctor|diag|d) shift; cmd_doctor "$@" ;;
audit) shift; cmd_audit "$@" ;;
template|tmpl) shift; cmd_template "$@" ;;
agent) shift; cmd_agent "$@" ;;
dashboard-login) shift; cmd_dashboard_login "$@" ;;
help|h|--help|-h) cmd_help ;;
version|v|--version|-v) echo "ods-cli v${VERSION}" ;;
*) error "Unknown command: $1. Run 'ods help' for usage." ;;
esac