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
"""Security-focused tests for the Settings environment editor."""
import hashlib
import json
from pathlib import Path
import pytest
def test_settings_parser_strips_one_pair_and_preserves_unmatched_quotes():
from settings import _parse_env_text
values, issues = _parse_env_text(
"PAIRED='value'\n"
"UNMATCHED=value'\n"
"REPEATED=''value''\n"
)
assert issues == []
assert values == {
"PAIRED": "value",
"UNMATCHED": "value'",
"REPEATED": "'value'",
}
@pytest.fixture()
def settings_env_fixture(tmp_path, monkeypatch):
install_root = tmp_path / "ods"
install_root.mkdir()
data_root = tmp_path / "data"
data_root.mkdir()
env_path = install_root / ".env"
example_path = install_root / ".env.example"
schema_path = install_root / ".env.schema.json"
env_path.write_text(
"OPENAI_API_KEY=sk-live-secret\n"
"RAG_OPENAI_API_KEY=rag-live-secret\n"
"LLM_BACKEND=local\n"
"WEBUI_AUTH=true\n",
encoding="utf-8",
)
example_path.write_text(
"# ════════════════════════════════\n"
"# LLM Settings\n"
"# ════════════════════════════════\n"
"OPENAI_API_KEY=\n"
"RAG_OPENAI_API_KEY=\n"
"LLM_BACKEND=local\n"
"WEBUI_AUTH=true\n"
"# LLAMA_ARG_N_CPU_MOE=25\n",
encoding="utf-8",
)
schema_path.write_text(
json.dumps(
{
"type": "object",
"properties": {
"OPENAI_API_KEY": {
"type": "string",
"description": "Key used for cloud LLM providers.",
"secret": True,
},
"RAG_OPENAI_API_KEY": {
"type": "string",
"description": "Optional RAG provider credential.",
"secret": True,
"clearable": True,
},
"LLM_BACKEND": {
"type": "string",
"description": "Primary LLM backend mode.",
"enum": ["local", "cloud"],
"default": "local",
},
"WEBUI_AUTH": {
"type": "boolean",
"description": "Require login for the WebUI.",
"default": True,
},
"LLAMA_ARG_N_CPU_MOE": {
"type": "integer",
"description": "Optional llama.cpp MoE tuning knob.",
"minimum": 0,
},
},
}
),
encoding="utf-8",
)
monkeypatch.setattr("main._resolve_install_root", lambda: install_root)
monkeypatch.setattr("main._resolve_runtime_env_path", lambda: env_path)
monkeypatch.setattr("main.DATA_DIR", str(data_root))
monkeypatch.setattr(
"settings.request_agent_json",
lambda method, path, *, timeout: {"status": "ok"},
)
def fake_env_update(raw_text):
backup_dir = data_root / "config-backups"
backup_dir.mkdir(parents=True, exist_ok=True)
backup_path = backup_dir / ".env.backup.test"
if env_path.exists():
backup_path.write_bytes(env_path.read_bytes())
payload = raw_text if raw_text.endswith("\n") else raw_text + "\n"
env_path.write_text(payload, encoding="utf-8")
return {"backup_path": "data/config-backups/.env.backup.test", "env_revision": hashlib.sha256(env_path.read_bytes()).hexdigest()}
monkeypatch.setattr("main._call_agent_env_update", fake_env_update)
def fake_resolve_template(name: str):
if name == ".env.example":
return example_path
if name == ".env.schema.json":
return schema_path
return install_root / name
monkeypatch.setattr("main._resolve_template_path", fake_resolve_template)
from main import _cache
_cache.clear()
return {
"install_root": install_root,
"data_root": data_root,
"env_path": env_path,
"example_path": example_path,
"schema_path": schema_path,
}
@pytest.fixture()
def constrained_settings(settings_env_fixture):
"""Use the shipped constraints, through the real Settings save boundary."""
schema_path = settings_env_fixture["schema_path"]
schema = json.loads(schema_path.read_text(encoding="utf-8"))
shipped = json.loads((Path(__file__).resolve().parents[4] / ".env.schema.json").read_text())
for key in ("REMOTE_LLM_SSH_PORT", "LLAMA_ARG_N_CPU_MOE", "N8N_PASS",
"PIXEL_OPENWEBUI_KEY", "TS_HOSTNAME"):
schema["properties"][key] = shipped["properties"][key]
schema_path.write_text(json.dumps(schema), encoding="utf-8")
return settings_env_fixture
@pytest.mark.parametrize("key,value", [
("REMOTE_LLM_SSH_PORT", "0"),
("REMOTE_LLM_SSH_PORT", "65536"),
("LLAMA_ARG_N_CPU_MOE", "-1"),
("N8N_PASS", "tiny-pass"),
("PIXEL_OPENWEBUI_KEY", "a" * 65),
("PIXEL_OPENWEBUI_KEY", "g" * 64),
("TS_HOSTNAME", "invalid/hostname"),
])
def test_settings_rejects_shipped_schema_violations_before_host_write(
test_client, constrained_settings, monkeypatch, key, value,
):
from unittest.mock import Mock
import main
write = Mock(wraps=main._call_agent_env_update)
monkeypatch.setattr("main._call_agent_env_update", write)
env_path = constrained_settings["env_path"]
original = env_path.read_bytes()
response = test_client.put("/api/settings/env", headers=test_client.auth_headers,
json={"mode": "form", "values": {key: value}})
assert response.status_code == 400, response.text
assert any(issue["key"] == key for issue in response.json()["detail"]["issues"])
if key in {"N8N_PASS", "PIXEL_OPENWEBUI_KEY"}:
assert value not in response.text
write.assert_not_called()
assert env_path.read_bytes() == original
assert not (constrained_settings["data_root"] / "config-backups").exists()
@pytest.mark.parametrize("port", ["1", "65535"])
def test_settings_saves_valid_schema_boundaries_and_keeps_blank_secret(
test_client, constrained_settings, port,
):
values = {"REMOTE_LLM_SSH_PORT": port, "LLAMA_ARG_N_CPU_MOE": "0",
"N8N_PASS": "a" * 10, "PIXEL_OPENWEBUI_KEY": "a" * 64,
"TS_HOSTNAME": "ods-local"}
response = test_client.put("/api/settings/env", headers=test_client.auth_headers,
json={"mode": "form", "values": values})
assert response.status_code == 200, response.text
response = test_client.put("/api/settings/env", headers=test_client.auth_headers,
json={"mode": "form", "values": {"N8N_PASS": ""}})
assert response.status_code == 200, response.text
from settings import _parse_env_text
persisted, issues = _parse_env_text(constrained_settings["env_path"].read_text())
assert issues == []
assert {key: persisted[key] for key in values} == values
assert (constrained_settings["data_root"] / "config-backups/.env.backup.test").exists()
def test_api_settings_env_masks_secret_values(test_client, settings_env_fixture):
response = test_client.get("/api/settings/env", headers=test_client.auth_headers)
assert response.status_code == 200
payload = response.json()
assert payload["path"] == ".env"
assert payload["raw"] == ""
assert payload["values"]["OPENAI_API_KEY"] == ""
assert payload["fields"]["OPENAI_API_KEY"]["value"] == ""
assert payload["fields"]["OPENAI_API_KEY"]["hasValue"] is True
assert payload["fields"]["OPENAI_API_KEY"]["secret"] is True
assert payload["values"]["LLM_BACKEND"] == "local"
assert payload["fields"]["LLM_BACKEND"]["value"] == "local"
assert payload["agentAvailable"] is True
def test_api_settings_env_recognizes_library_ports_and_keeps_library_secrets_masked(
test_client, settings_env_fixture,
):
schema = Path(__file__).resolve().parents[4] / ".env.schema.json"
settings_env_fixture["schema_path"].write_bytes(schema.read_bytes())
settings_env_fixture["env_path"].write_text(
"DIFY_PORT=18002\nFLOWISE_PASSWORD=library-secret-fixture\nMINIFLUX_ADMIN_PASSWORD=miniflux-secret-fixture\n", encoding="utf-8",
)
response = test_client.get("/api/settings/env", headers=test_client.auth_headers)
assert response.status_code == 200
fields = response.json()["fields"]
assert fields["DIFY_PORT"]["type"] == "integer"
assert fields["DIFY_PORT"]["value"] == "18002"
assert fields["FLOWISE_PASSWORD"]["secret"] is True
assert fields["FLOWISE_PASSWORD"]["hasValue"] is True
assert "library-secret-fixture" not in response.text
assert fields["MINIFLUX_ADMIN_PASSWORD"]["secret"] is True
assert fields["MINIFLUX_ADMIN_PASSWORD"]["hasValue"] is True
assert "miniflux-secret-fixture" not in response.text
def test_api_settings_env_does_not_treat_plural_tokens_as_a_secret(
test_client,
settings_env_fixture,
):
env_path = settings_env_fixture["env_path"]
env_path.write_text(
env_path.read_text(encoding="utf-8")
+ "LLAMA_ARG_CHECKPOINT_EVERY_N_TOKENS=-1\n",
encoding="utf-8",
)
schema_path = settings_env_fixture["schema_path"]
schema = json.loads(schema_path.read_text(encoding="utf-8"))
schema["properties"]["LLAMA_ARG_CHECKPOINT_EVERY_N_TOKENS"] = {
"type": "integer",
}
schema_path.write_text(json.dumps(schema), encoding="utf-8")
response = test_client.get(
"/api/settings/env",
headers=test_client.auth_headers,
)
assert response.status_code == 200
payload = response.json()
assert payload["fields"]["LLAMA_ARG_CHECKPOINT_EVERY_N_TOKENS"]["secret"] is False
assert payload["values"]["LLAMA_ARG_CHECKPOINT_EVERY_N_TOKENS"] == "-1"
def test_api_settings_env_masks_saves_and_live_reads_hf_token(
test_client, settings_env_fixture,
):
env_path = settings_env_fixture["env_path"]
example_path = settings_env_fixture["example_path"]
schema_path = settings_env_fixture["schema_path"]
env_path.write_text(
env_path.read_text(encoding="utf-8") + "HF_TOKEN=hf_existing_read_token\n",
encoding="utf-8",
)
example_path.write_text(
example_path.read_text(encoding="utf-8")
+ "# ════════════════════════════════\n"
+ "# Provider and Hub Credentials\n"
+ "# ════════════════════════════════\n"
+ "HF_TOKEN=\n",
encoding="utf-8",
)
schema = json.loads(schema_path.read_text(encoding="utf-8"))
schema["properties"]["HF_TOKEN"] = {
"type": "string",
"description": "Optional read token for private or gated Hugging Face repositories.",
"secret": True,
}
schema_path.write_text(json.dumps(schema), encoding="utf-8")
read_response = test_client.get(
"/api/settings/env",
headers=test_client.auth_headers,
)
assert read_response.status_code == 200
read_payload = read_response.json()
assert read_payload["values"]["HF_TOKEN"] == ""
assert read_payload["fields"]["HF_TOKEN"]["value"] == ""
assert read_payload["fields"]["HF_TOKEN"]["hasValue"] is True
assert read_payload["fields"]["HF_TOKEN"]["secret"] is True
credentials = next(
section
for section in read_payload["sections"]
if section["title"] == "Provider and Hub Credentials"
)
assert "HF_TOKEN" in credentials["keys"]
save_response = test_client.put(
"/api/settings/env",
headers=test_client.auth_headers,
json={"mode": "form", "values": {"HF_TOKEN": "hf_replaced_read_token"}},
)
assert save_response.status_code == 200
save_payload = save_response.json()
assert "HF_TOKEN=hf_replaced_read_token" in env_path.read_text(encoding="utf-8")
assert save_payload["values"]["HF_TOKEN"] == ""
assert save_payload["fields"]["HF_TOKEN"]["hasValue"] is True
assert save_payload["applyPlan"]["status"] == "none"
assert save_payload["applyPlan"]["services"] == []
preserve_response = test_client.put(
"/api/settings/env",
headers=test_client.auth_headers,
json={"mode": "form", "values": {"HF_TOKEN": ""}},
)
assert preserve_response.status_code == 200
assert "HF_TOKEN=hf_replaced_read_token" in env_path.read_text(encoding="utf-8")
def test_api_settings_env_marks_runtime_mode_read_only(test_client, settings_env_fixture):
env_path = settings_env_fixture["env_path"]
env_path.write_text(
env_path.read_text(encoding="utf-8") + "ODS_MODE=local\n",
encoding="utf-8",
)
response = test_client.get("/api/settings/env", headers=test_client.auth_headers)
assert response.status_code == 200
field = response.json()["fields"]["ODS_MODE"]
assert field["readOnly"] is True
assert "installer" in field["readOnlyReason"].lower()
def test_api_settings_env_marks_model_context_and_recommendation_read_only(
test_client,
settings_env_fixture,
):
keys = (
"CTX_SIZE",
"MAX_CONTEXT",
"MODEL_RECOMMENDED_MODEL",
"MODEL_RECOMMENDED_GGUF",
"MODEL_RECOMMENDED_CONTEXT",
"MODEL_RECOMMENDATION_SOURCE",
"MODEL_RECOMMENDATION_POLICY",
"MODEL_RECOMMENDATION_CONFIDENCE",
"MODEL_RECOMMENDATION_REASON",
"MODEL_RECOMMENDED_ALTERNATIVES",
)
schema_path = settings_env_fixture["schema_path"]
schema = json.loads(schema_path.read_text(encoding="utf-8"))
schema["properties"].update({
key: {"type": "integer" if "CONTEXT" in key else "string"}
for key in keys
})
schema_path.write_text(json.dumps(schema), encoding="utf-8")
response = test_client.get(
"/api/settings/env",
headers=test_client.auth_headers,
)
assert response.status_code == 200
fields = response.json()["fields"]
for key in keys:
assert fields[key]["readOnly"] is True
assert fields[key]["readOnlyReason"]
def test_api_settings_env_rejects_direct_context_override(
test_client,
settings_env_fixture,
):
env_path = settings_env_fixture["env_path"]
env_path.write_text(
env_path.read_text(encoding="utf-8") + "CTX_SIZE=8192\n",
encoding="utf-8",
)
schema_path = settings_env_fixture["schema_path"]
schema = json.loads(schema_path.read_text(encoding="utf-8"))
schema["properties"]["CTX_SIZE"] = {"type": "integer"}
schema_path.write_text(json.dumps(schema), encoding="utf-8")
current = test_client.get(
"/api/settings/env",
headers=test_client.auth_headers,
).json()["values"]
response = test_client.put(
"/api/settings/env",
headers=test_client.auth_headers,
json={
"mode": "form",
"values": {**current, "CTX_SIZE": "65536"},
},
)
assert response.status_code == 400
detail = response.json()["detail"]
assert detail["issues"] == [{
"key": "CTX_SIZE",
"message": (
"The active context is managed by Model Manager so the runtime "
"and every model consumer remain synchronized."
),
}]
assert "CTX_SIZE=65536" not in env_path.read_text(encoding="utf-8")
def test_api_settings_env_rejects_runtime_mode_change(test_client, settings_env_fixture):
env_path = settings_env_fixture["env_path"]
env_path.write_text(
env_path.read_text(encoding="utf-8") + "ODS_MODE=cloud\n",
encoding="utf-8",
)
response = test_client.put(
"/api/settings/env",
headers=test_client.auth_headers,
json={"mode": "form", "values": {"ODS_MODE": "local"}},
)
assert response.status_code == 400
assert response.json()["detail"]["issues"] == [{
"key": "ODS_MODE",
"message": "Runtime mode is selected by the installer and cannot be changed from the dashboard.",
}]
assert "ODS_MODE=cloud" in env_path.read_text(encoding="utf-8")
def test_api_settings_env_allows_unchanged_runtime_mode(test_client, settings_env_fixture):
env_path = settings_env_fixture["env_path"]
env_path.write_text(
env_path.read_text(encoding="utf-8") + "ODS_MODE=local\n",
encoding="utf-8",
)
response = test_client.put(
"/api/settings/env",
headers=test_client.auth_headers,
json={
"mode": "form",
"values": {"ODS_MODE": "local", "WEBUI_AUTH": "false"},
},
)
assert response.status_code == 200
updated_env = env_path.read_text(encoding="utf-8")
assert "ODS_MODE=local" in updated_env
assert "WEBUI_AUTH=false" in updated_env
def test_api_settings_env_preserves_existing_secret_when_blank(test_client, settings_env_fixture):
env_path = settings_env_fixture["env_path"]
response = test_client.put(
"/api/settings/env",
headers=test_client.auth_headers,
json={
"mode": "form",
"values": {
"OPENAI_API_KEY": "",
"LLM_BACKEND": "cloud",
"WEBUI_AUTH": "false",
},
},
)
assert response.status_code == 200
payload = response.json()
updated_env = env_path.read_text(encoding="utf-8")
assert "OPENAI_API_KEY=sk-live-secret" in updated_env
assert "LLM_BACKEND=cloud" in updated_env
assert "WEBUI_AUTH=false" in updated_env
assert payload["values"]["OPENAI_API_KEY"] == ""
assert payload["fields"]["OPENAI_API_KEY"]["hasValue"] is True
assert payload["backupPath"].startswith("data/config-backups/.env.backup.")
assert payload["applyPlan"]["status"] == "ready"
assert payload["applyPlan"]["services"] == ["llama-server", "open-webui"]
def test_api_settings_env_explicitly_clears_clearable_rag_secret(test_client, settings_env_fixture):
env_path = settings_env_fixture["env_path"]
response = test_client.put(
"/api/settings/env",
headers=test_client.auth_headers,
json={
"mode": "form",
"values": {"RAG_OPENAI_API_KEY": ""},
"clearSecrets": ["RAG_OPENAI_API_KEY"],
},
)
assert response.status_code == 200
payload = response.json()
updated_env = env_path.read_text(encoding="utf-8")
assert "RAG_OPENAI_API_KEY=\n" in updated_env
assert "RAG_OPENAI_API_KEY=rag-live-secret" not in updated_env
assert "OPENAI_API_KEY=sk-live-secret" in updated_env
assert payload["fields"]["RAG_OPENAI_API_KEY"]["hasValue"] is False
assert payload["applyPlan"]["services"] == ["open-webui"]
assert [action["id"] for action in payload["applyPlan"]["postApplyActions"]] == [
"open-webui-rag-sync",
]
def test_api_settings_env_rejects_clearing_non_clearable_secret(test_client, settings_env_fixture):
env_path = settings_env_fixture["env_path"]
response = test_client.put(
"/api/settings/env",
headers=test_client.auth_headers,
json={
"mode": "form",
"values": {"OPENAI_API_KEY": ""},
"clearSecrets": ["OPENAI_API_KEY"],
},
)
assert response.status_code == 400
assert response.json()["detail"]["issues"] == [{
"key": "OPENAI_API_KEY",
"message": "This secret cannot be cleared from the dashboard.",
}]
assert "OPENAI_API_KEY=sk-live-secret" in env_path.read_text(encoding="utf-8")
def test_api_settings_env_rejects_raw_mode(test_client, settings_env_fixture):
response = test_client.put(
"/api/settings/env",
headers=test_client.auth_headers,
json={"mode": "raw", "raw": "OPENAI_API_KEY=oops\n"},
)
assert response.status_code == 400
payload = response.json()
assert payload["detail"]["message"] == "Only form-based editing is supported for security reasons."
def test_api_settings_env_rejects_model_identity_bypass(
test_client, settings_env_fixture,
):
env_path = settings_env_fixture["env_path"]
env_path.write_text(
env_path.read_text(encoding="utf-8") + "LLM_MODEL=old-model\n",
encoding="utf-8",
)
response = test_client.put(
"/api/settings/env",
headers=test_client.auth_headers,
json={"mode": "form", "values": {"LLM_MODEL": "new-model"}},
)
assert response.status_code == 400
assert response.json()["detail"]["issues"] == [{
"key": "LLM_MODEL",
"message": "The active model is managed by Model Manager so model consumers stay synchronized.",
}]
assert "LLM_MODEL=old-model" in env_path.read_text(encoding="utf-8")
def test_api_settings_env_rejects_new_unknown_keys(test_client, settings_env_fixture):
response = test_client.put(
"/api/settings/env",
headers=test_client.auth_headers,
json={
"mode": "form",
"values": {
"OPENAI_API_KEY": "",
"INJECTED_FLAG": "true",
},
},
)
assert response.status_code == 400
payload = response.json()
assert payload["detail"]["message"] == "Configuration validation failed."
assert payload["detail"]["issues"] == [
{
"key": "INJECTED_FLAG",
"message": "Field is not editable from the dashboard. Only schema-backed fields and existing local overrides can be changed here.",
}
]
def test_api_settings_env_allows_existing_local_override(test_client, settings_env_fixture):
env_path = settings_env_fixture["env_path"]
env_path.write_text(
env_path.read_text(encoding="utf-8") + "LOCAL_OVERRIDE=keep-me\n",
encoding="utf-8",
)
response = test_client.put(
"/api/settings/env",
headers=test_client.auth_headers,
json={
"mode": "form",
"values": {
"LOCAL_OVERRIDE": "updated",
},
},
)
assert response.status_code == 200
updated_env = env_path.read_text(encoding="utf-8")
assert "LOCAL_OVERRIDE=updated" in updated_env
def test_api_settings_env_rejects_newline_in_value(test_client, settings_env_fixture):
response = test_client.put(
"/api/settings/env",
headers=test_client.auth_headers,
json={
"mode": "form",
"values": {
"LLM_BACKEND": "local\nINJECTED_KEY=malicious",
},
},
)
assert response.status_code == 400
assert "invalid characters" in response.json()["detail"]
def test_api_settings_env_rejects_null_byte_in_value(test_client, settings_env_fixture):
response = test_client.put(
"/api/settings/env",
headers=test_client.auth_headers,
json={
"mode": "form",
"values": {
"LLM_BACKEND": "local\x00injected",
},
},
)
assert response.status_code == 400
assert "invalid characters" in response.json()["detail"]
def test_api_settings_env_save_returns_llama_apply_plan(test_client, settings_env_fixture):
env_path = settings_env_fixture["env_path"]
env_path.write_text(
env_path.read_text(encoding="utf-8") + "LLAMA_BATCH_SIZE=1024\n",
encoding="utf-8",
)
response = test_client.put(
"/api/settings/env",
headers=test_client.auth_headers,
json={
"mode": "form",
"values": {
"LLAMA_BATCH_SIZE": "2048",
},
},
)
assert response.status_code == 200
payload = response.json()
assert payload["applyPlan"]["status"] == "ready"
assert payload["applyPlan"]["services"] == ["llama-server"]
assert "llama-server" in payload["applyPlan"]["summary"]
def test_api_settings_env_gpu_layer_change_recreates_llama_server(
test_client, settings_env_fixture,
):
env_path = settings_env_fixture["env_path"]
env_path.write_text(
env_path.read_text(encoding="utf-8") + "N_GPU_LAYERS=99\n",
encoding="utf-8",
)
response = test_client.put(
"/api/settings/env",
headers=test_client.auth_headers,
json={
"mode": "form",
"values": {
"N_GPU_LAYERS": "auto",
},
},
)
assert response.status_code == 200
payload = response.json()
assert payload["values"]["N_GPU_LAYERS"] == "auto"
assert payload["applyPlan"]["status"] == "ready"
assert payload["applyPlan"]["services"] == ["llama-server"]
def test_api_settings_env_save_uses_host_agent_canonical_value(
test_client, settings_env_fixture, monkeypatch,
):
def fake_env_update(raw_text):
return {
"backup_path": "data/config-backups/.env.backup.test",
"enforced_values": {"WEBUI_AUTH": "true"},
}
monkeypatch.setattr("main._call_agent_env_update", fake_env_update)
response = test_client.put(
"/api/settings/env",
headers=test_client.auth_headers,
json={
"mode": "form",
"values": {
"WEBUI_AUTH": "false",
},
},
)
assert response.status_code == 200
payload = response.json()
assert payload["values"]["WEBUI_AUTH"] == "true"
assert payload["fields"]["WEBUI_AUTH"]["value"] == "true"
def test_api_settings_env_preserves_commented_empty_llama_args(test_client, settings_env_fixture):
env_path = settings_env_fixture["env_path"]
response = test_client.put(
"/api/settings/env",
headers=test_client.auth_headers,
json={
"mode": "form",
"values": {
"LLM_BACKEND": "cloud",
},
},
)
assert response.status_code == 200
updated_lines = env_path.read_text(encoding="utf-8").splitlines()
assert "# LLAMA_ARG_N_CPU_MOE=25" in updated_lines
assert not any(line.startswith("LLAMA_ARG_N_CPU_MOE=") for line in updated_lines)
def test_api_settings_env_unsets_empty_existing_llama_arg(test_client, settings_env_fixture):
env_path = settings_env_fixture["env_path"]
env_path.write_text(
env_path.read_text(encoding="utf-8") + "LLAMA_ARG_N_CPU_MOE=30\n",
encoding="utf-8",
)
response = test_client.put(
"/api/settings/env",
headers=test_client.auth_headers,
json={
"mode": "form",
"values": {
"LLAMA_ARG_N_CPU_MOE": "",
},
},
)
assert response.status_code == 200
updated_lines = env_path.read_text(encoding="utf-8").splitlines()
assert "# LLAMA_ARG_N_CPU_MOE=25" in updated_lines
assert not any(line.startswith("LLAMA_ARG_N_CPU_MOE=") for line in updated_lines)
def test_api_settings_env_apply_calls_host_agent(test_client, monkeypatch):
captured = {}
def fake_call(service_ids):
captured["service_ids"] = service_ids
return {"status": "ok"}
monkeypatch.setattr("main._call_agent_core_recreate", fake_call)
response = test_client.post(
"/api/settings/env/apply",
headers=test_client.auth_headers,
json={"service_ids": ["llama-server"]},
)
assert response.status_code == 200
assert response.json()["success"] is True
assert captured["service_ids"] == ["llama-server"]
def test_api_settings_env_apply_allows_hermes_services(test_client, monkeypatch):
captured = {}
def fake_call(service_ids):
captured["service_ids"] = service_ids
return {"status": "ok"}
monkeypatch.setattr("main._call_agent_core_recreate", fake_call)
response = test_client.post(
"/api/settings/env/apply",
headers=test_client.auth_headers,
json={"service_ids": ["hermes-proxy", "hermes"]},
)
assert response.status_code == 200
assert response.json()["success"] is True
assert captured["service_ids"] == ["hermes", "hermes-proxy"]
def test_api_settings_env_apply_allows_model_router(test_client, monkeypatch):
captured = {}
def fake_call(service_ids):
captured["service_ids"] = service_ids
return {"status": "ok"}
monkeypatch.setattr("main._call_agent_core_recreate", fake_call)
response = test_client.post(
"/api/settings/env/apply",
headers=test_client.auth_headers,
json={"service_ids": ["model-router"]},
)
assert response.status_code == 200
assert response.json()["success"] is True
assert captured["service_ids"] == ["model-router"]
def test_api_settings_env_apply_returns_structured_409_for_model_lifecycle_busy(test_client, monkeypatch):
from host_agent_client import AgentHTTPError
def fake_call(service_ids):
raise AgentHTTPError(
409,
"model lifecycle busy",
json.dumps({"code": "model_lifecycle_busy", "message": "busy"}),
)
monkeypatch.setattr("main._call_agent_core_recreate", fake_call)
response = test_client.post(
"/api/settings/env/apply",
headers=test_client.auth_headers,
json={"service_ids": ["llama-server"]},
)
assert response.status_code == 409
detail = response.json()["detail"]
assert detail["code"] == "model_lifecycle_busy"
assert detail["message"] == (
"ODS is finishing another operation. Wait for it to finish, then choose Apply changes again. "
"If settings changed, ODS will ask you to review them."
)
def test_api_settings_env_apply_keeps_503_for_unrelated_409(test_client, monkeypatch):
from host_agent_client import AgentHTTPError
def fake_call(service_ids):
raise AgentHTTPError(
409,
"conflict",
json.dumps({"code": "other_conflict", "message": "conflict"}),
)
monkeypatch.setattr("main._call_agent_core_recreate", fake_call)
response = test_client.post(
"/api/settings/env/apply",
headers=test_client.auth_headers,
json={"service_ids": ["llama-server"]},
)
assert response.status_code == 503
assert response.json()["detail"]["message"] == "conflict"
def test_api_settings_env_apply_keeps_503_for_malformed_409(test_client, monkeypatch):
from host_agent_client import AgentHTTPError
def fake_call(service_ids):
raise AgentHTTPError(409, "not json", "not-json")
monkeypatch.setattr("main._call_agent_core_recreate", fake_call)
response = test_client.post(
"/api/settings/env/apply",
headers=test_client.auth_headers,
json={"service_ids": ["llama-server"]},
)
assert response.status_code == 503
assert response.json()["detail"]["message"] == "not json"
def test_api_settings_env_apply_rejects_disallowed_service(test_client):
response = test_client.post(
"/api/settings/env/apply",
headers=test_client.auth_headers,
json={"service_ids": ["dashboard-api"]},
)
assert response.status_code == 400
assert "not eligible" in response.json()["detail"]["message"].lower()
def test_active_settings_apply_services_excludes_disabled_compose(monkeypatch, tmp_path):
import main
install_root = tmp_path / "ods"
embeddings_dir = install_root / "extensions" / "services" / "embeddings"
embeddings_dir.mkdir(parents=True)
disabled = embeddings_dir / "compose.yaml.disabled"
disabled.write_text("services:\n embeddings:\n image: test\n", encoding="utf-8")
monkeypatch.setattr(main, "_resolve_install_root", lambda: install_root)
monkeypatch.setattr(main, "ALWAYS_ON_SERVICES", frozenset({"open-webui"}))
assert "embeddings" not in main._active_settings_apply_services()
disabled.rename(embeddings_dir / "compose.yaml")
assert "embeddings" in main._active_settings_apply_services()
def test_check_host_agent_available_uses_shared_transport(monkeypatch):
import settings
calls = []
def fake_request(method, path, *, timeout):
calls.append((method, path, timeout))
return {"status": "ok"}
monkeypatch.setattr(settings, "request_agent_json", fake_request)
assert settings._check_host_agent_available() is True
assert calls == [("GET", "/health", 3)]
@pytest.mark.parametrize(
"error",
[
pytest.param("unavailable", id="unavailable"),
pytest.param("http-error", id="http-error"),
pytest.param("protocol-error", id="protocol-error"),
],
)
def test_check_host_agent_available_handles_typed_transport_errors(monkeypatch, error):
import settings
from host_agent_client import AgentHTTPError, AgentProtocolError, AgentUnavailable
failures = {
"unavailable": AgentUnavailable("connection refused"),
"http-error": AgentHTTPError(503, "not ready"),
"protocol-error": AgentProtocolError("invalid JSON"),
}
def fail(*args, **kwargs):
raise failures[error]
monkeypatch.setattr(settings, "request_agent_json", fail)
assert settings._check_host_agent_available() is False
def test_settings_apply_plan_maps_hermes_env_keys():
from settings import _compute_env_apply_plan
previous = {
"HERMES_LANGUAGE": "en",
"HERMES_PROXY_PORT": "9120",
"ODS_AUTH_UPSTREAM": "ods-dashboard-api:3002",
"WHATSAPP_ENABLED": "false",
"SEARXNG_URL": "http://searxng:8080",
}
updated = {
"HERMES_LANGUAGE": "pt",
"HERMES_PROXY_PORT": "9121",
"ODS_AUTH_UPSTREAM": "dashboard-api:3002",
"WHATSAPP_ENABLED": "true",
"SEARXNG_URL": "http://search:8080",
}
plan = _compute_env_apply_plan(previous, updated)
assert plan["status"] == "ready"
assert plan["services"] == ["hermes", "hermes-proxy"]
assert plan["manualKeys"] == []
def test_settings_apply_plan_restarts_hermes_for_dashboard_token_rotation():
from settings import _compute_env_apply_plan
plan = _compute_env_apply_plan(
{"HERMES_DASHBOARD_SESSION_TOKEN": "old-token"},
{"HERMES_DASHBOARD_SESSION_TOKEN": "new-token"},
)
assert plan["status"] == "ready"
assert plan["services"] == ["hermes"]
assert plan["manualKeys"] == []
def test_settings_apply_plan_treats_public_urls_as_manual_restart():
from settings import _compute_env_apply_plan
previous = {
"OPEN_WEBUI_PUBLIC_URL": "",
"N8N_PUBLIC_URL": "",
"HERMES_PROXY_PUBLIC_URL": "",
"ODS_SERVICE_PUBLIC_URLS": "",
}
updated = {
"OPEN_WEBUI_PUBLIC_URL": "https://chat.example.test",
"N8N_PUBLIC_URL": "https://n8n.example.test",
"HERMES_PROXY_PUBLIC_URL": "https://hermes.example.test",
"ODS_SERVICE_PUBLIC_URLS": '{"comfyui":"https://comfy.example.test"}',
}
plan = _compute_env_apply_plan(previous, updated)
assert plan["status"] == "manual"
assert plan["services"] == []
assert plan["manualKeys"] == [
"HERMES_PROXY_PUBLIC_URL",
"N8N_PUBLIC_URL",
"ODS_SERVICE_PUBLIC_URLS",
"OPEN_WEBUI_PUBLIC_URL",
]
def test_settings_apply_plan_maps_agent_and_proxy_env_keys():
from settings import _compute_env_apply_plan
previous = {
"APE_STRICT_MODE": "false",
"ODS_PROXY_PORT": "80",
}
updated = {
"APE_STRICT_MODE": "true",
"ODS_PROXY_PORT": "8080",
}
plan = _compute_env_apply_plan(previous, updated)
assert plan["status"] == "ready"
assert plan["services"] == ["ape", "ods-proxy"]
assert plan["manualKeys"] == []
def test_settings_apply_plan_ignores_retired_legacy_openclaw_keys():
"""Nothing reads the removed extension's keys, so editing one restarts nothing."""
from settings import _compute_env_apply_plan
previous = {
"OPENCLAW_DANGEROUSLY_DISABLE_DEVICE_AUTH": "",
"OPENCLAW_TOKEN": "old-token-value",
"HOST_LAN_IP": "",
}
updated = {
"OPENCLAW_DANGEROUSLY_DISABLE_DEVICE_AUTH": "true",
"OPENCLAW_TOKEN": "new-token-value",
"HOST_LAN_IP": "192.0.2.10",
}
plan = _compute_env_apply_plan(previous, updated)
assert plan["services"] == []
assert plan["manualKeys"] == []
def test_retired_env_keys_match_schema_retired_properties():
"""Keys nothing reads any more stay in the schema as "Retired:" entries.
Older .env files keep validating, a change restarts nothing, and an owner
can remove each one. Other deprecated keys may still be read during a
migration window, so they are not tied to this list.
"""
from settings import _RETIRED_ENV_KEYS
schema_path = Path(__file__).resolve().parents[4] / ".env.schema.json"
schema = json.loads(schema_path.read_text(encoding="utf-8"))
properties = schema["properties"]
retired = {
key for key, definition in properties.items()
if definition.get("description", "").startswith("Retired:")
}
assert retired == set(_RETIRED_ENV_KEYS)
assert not retired & set(schema["required"])
for key in retired:
assert properties[key].get("deprecated") is True, key
if properties[key].get("secret"):
assert properties[key].get("clearable") is True, key
def test_api_settings_env_removes_retired_keys(test_client, settings_env_fixture):
"""Clearing a retired key removes its line; a retired secret is clearable."""
env_path = settings_env_fixture["env_path"]
schema_path = settings_env_fixture["schema_path"]
retired = "Retired: the legacy OpenClaw extension was removed; ignored if present."
schema = json.loads(schema_path.read_text(encoding="utf-8"))
schema["properties"].update({
"OPENCLAW_TOKEN": {
"type": "string", "description": retired,
"secret": True, "clearable": True, "deprecated": True,
},
"HOST_LAN_IP": {"type": "string", "description": retired, "deprecated": True},
"OPENCLAW_PORT": {"type": "integer", "description": retired, "deprecated": True},
})
schema_path.write_text(json.dumps(schema), encoding="utf-8")
env_path.write_text(
env_path.read_text(encoding="utf-8")
+ "OPENCLAW_TOKEN=retired-token-value\nHOST_LAN_IP=192.0.2.10\nOPENCLAW_PORT=7860\n",
encoding="utf-8",
)
from main import _cache
_cache.clear()
response = test_client.put(
"/api/settings/env",
headers=test_client.auth_headers,
json={
"mode": "form",
"values": {"HOST_LAN_IP": "", "OPENCLAW_PORT": ""},
"clearSecrets": ["OPENCLAW_TOKEN"],
},
)
assert response.status_code == 200, response.text
payload = response.json()
updated_env = env_path.read_text(encoding="utf-8")
for key in ("OPENCLAW_TOKEN", "HOST_LAN_IP", "OPENCLAW_PORT"):
assert f"{key}=" not in updated_env
assert key not in payload["fields"]
assert "OPENAI_API_KEY=sk-live-secret" in updated_env
assert "RAG_OPENAI_API_KEY=rag-live-secret" in updated_env
assert payload["applyPlan"]["services"] == []
def test_settings_fields_show_retired_keys_only_when_present():
"""Retired schema keys stay hidden unless this .env still carries them."""
from settings import _build_env_fields
schema = {
"OPENCLAW_TOKEN": {"type": "string", "secret": True, "deprecated": True},
"LLM_MODEL": {"type": "string"},
}
fresh = _build_env_fields(schema, set(), {"LLM_MODEL": "qwen"})
assert "OPENCLAW_TOKEN" not in fresh
assert fresh["LLM_MODEL"]["value"] == "qwen"
upgraded = _build_env_fields(schema, set(), {"OPENCLAW_TOKEN": "kept-token"})
assert upgraded["OPENCLAW_TOKEN"]["secret"] is True
assert upgraded["OPENCLAW_TOKEN"]["hasValue"] is True
def test_settings_apply_plan_recreates_bundled_embedding_consumers():
from settings import _compute_env_apply_plan
plan = _compute_env_apply_plan(
{"EMBEDDING_MODEL": "BAAI/bge-base-en-v1.5"},
{"EMBEDDING_MODEL": "BAAI/bge-m3"},
)
assert plan["status"] == "ready"
assert plan["services"] == ["embeddings", "open-webui"]
assert plan["manualKeys"] == []
assert [action["id"] for action in plan["postApplyActions"]] == [
"open-webui-rag-sync",
"open-webui-rag-reindex",
]
def test_settings_apply_plan_preserves_external_rag_override():
from settings import _compute_env_apply_plan
previous = {
"EMBEDDING_MODEL": "BAAI/bge-base-en-v1.5",
"RAG_EMBEDDING_MODEL": "external-v1",
"RAG_OPENAI_API_BASE_URL": "https://embeddings.example.test/v1",
}
updated = {**previous, "EMBEDDING_MODEL": "BAAI/bge-m3"}
plan = _compute_env_apply_plan(previous, updated)
assert plan["services"] == ["embeddings"]
assert plan["postApplyActions"] == []
def test_settings_apply_plan_recreates_external_rag_consumer_when_model_is_inherited():
from settings import _compute_env_apply_plan
previous = {
"EMBEDDING_MODEL": "BAAI/bge-base-en-v1.5",
"RAG_OPENAI_API_BASE_URL": "https://embeddings.example.test/v1",
}
updated = {**previous, "EMBEDDING_MODEL": "BAAI/bge-m3"}
plan = _compute_env_apply_plan(previous, updated)
assert plan["services"] == ["embeddings", "open-webui"]
assert [action["id"] for action in plan["postApplyActions"]] == [
"open-webui-rag-sync",
"open-webui-rag-reindex",
]
def test_settings_apply_plan_updates_consumer_and_stages_disabled_embeddings():
from settings import _compute_env_apply_plan
previous = {"EMBEDDING_MODEL": "BAAI/bge-base-en-v1.5"}
updated = {"EMBEDDING_MODEL": "BAAI/bge-m3"}
plan = _compute_env_apply_plan(previous, updated, active_services={"open-webui"})
assert plan["status"] == "partial"
assert plan["services"] == ["open-webui"]
assert plan["inactiveServices"] == ["embeddings"]
assert [action["id"] for action in plan["postApplyActions"]] == [
"open-webui-rag-sync",
"open-webui-rag-reindex",
]
assert "will apply when they are enabled: embeddings" in plan["summary"]
def test_settings_apply_plan_updates_external_consumer_when_bundled_embeddings_are_disabled():
from settings import _compute_env_apply_plan
previous = {
"EMBEDDING_MODEL": "BAAI/bge-base-en-v1.5",
"RAG_OPENAI_API_BASE_URL": "https://embeddings.example.test/v1",
}
updated = {**previous, "EMBEDDING_MODEL": "BAAI/bge-m3"}
plan = _compute_env_apply_plan(previous, updated, active_services={"open-webui"})
assert plan["status"] == "partial"
assert plan["services"] == ["open-webui"]
assert plan["inactiveServices"] == ["embeddings"]
assert [action["id"] for action in plan["postApplyActions"]] == [
"open-webui-rag-sync",
"open-webui-rag-reindex",
]
def test_settings_apply_plan_reindexes_explicit_rag_provider_change():
from settings import _compute_env_apply_plan
previous = {
"RAG_EMBEDDING_MODEL": "external-v1",
"RAG_OPENAI_API_BASE_URL": "https://embeddings.example.test/v1",
}
updated = {
"RAG_EMBEDDING_MODEL": "external-v2",
"RAG_OPENAI_API_BASE_URL": "https://embeddings.example.test/v2",
}
plan = _compute_env_apply_plan(previous, updated)
assert plan["services"] == ["open-webui"]
assert [action["id"] for action in plan["postApplyActions"]] == [
"open-webui-rag-sync",
"open-webui-rag-reindex",
]
def test_settings_apply_plan_returns_to_bundled_rag_after_clearing_overrides():
from settings import _compute_env_apply_plan, _empty_value_unsets_env_key
previous = {
"EMBEDDING_MODEL": "BAAI/bge-m3",
"RAG_EMBEDDING_MODEL": "external-v2",
"RAG_OPENAI_API_BASE_URL": "https://embeddings.example.test/v1",
}
updated = {"EMBEDDING_MODEL": "BAAI/bge-m3"}
assert _empty_value_unsets_env_key("RAG_EMBEDDING_MODEL", {"type": "string"}) is True
assert _empty_value_unsets_env_key("RAG_OPENAI_API_BASE_URL", {"type": "string"}) is True
plan = _compute_env_apply_plan(previous, updated)
assert plan["services"] == ["open-webui"]
assert [action["id"] for action in plan["postApplyActions"]] == [
"open-webui-rag-sync",
"open-webui-rag-reindex",
]
def test_settings_apply_plan_syncs_rag_credential_without_reindex():
from settings import _compute_env_apply_plan
plan = _compute_env_apply_plan(
{"RAG_OPENAI_API_KEY": "old-secret"},
{"RAG_OPENAI_API_KEY": "new-secret"},
)
assert plan["services"] == ["open-webui"]
assert [action["id"] for action in plan["postApplyActions"]] == [
"open-webui-rag-sync",
]
def test_settings_validation_rejects_gguf_embedding_artifact():
from settings import _build_env_fields, _validate_env_values
values = {"EMBEDDING_MODEL": "someone/bge-m3-Q4_K_M-GGUF"}
fields = _build_env_fields(
{"EMBEDDING_MODEL": {"type": "string"}}, set(), values,
)
issues = _validate_env_values(values, fields)
assert issues[0]["key"] == "EMBEDDING_MODEL"
assert "GGUF/Q4" in issues[0]["message"]
def test_settings_validation_rejects_invalid_embeddings_memory_limit():
from settings import _build_env_fields, _validate_env_values
values = {"EMBEDDINGS_MEMORY_LIMIT": "lots"}
fields = _build_env_fields(
{"EMBEDDINGS_MEMORY_LIMIT": {"type": "string"}}, set(), values,
)
issues = _validate_env_values(values, fields)
assert issues == [{
"key": "EMBEDDINGS_MEMORY_LIMIT",
"message": "Must be a positive Docker memory value such as 4096M, 4G, or 6GB.",
}]
def test_settings_validation_accepts_compose_memory_units():
from settings import _build_env_fields, _validate_env_values
for value in ("4096M", "4G", "6GB", "4294967296"):
values = {"EMBEDDINGS_MEMORY_LIMIT": value}
fields = _build_env_fields(
{"EMBEDDINGS_MEMORY_LIMIT": {"type": "string"}}, set(), values,
)
assert _validate_env_values(values, fields) == []
@pytest.mark.parametrize("value", ["auto", "all", "0", "99", "999"])
def test_settings_validation_accepts_gpu_layer_modes_and_counts(value):
from settings import _validate_env_values
assert _validate_env_values(
{"N_GPU_LAYERS": value},
{"N_GPU_LAYERS": {"type": "string"}},
) == []
def test_settings_serialization_normalizes_gpu_layer_whitespace():
from settings import _serialize_form_values
assert _serialize_form_values(
{"N_GPU_LAYERS": " all "},
{"N_GPU_LAYERS": {"type": "string"}},
) == {"N_GPU_LAYERS": "all"}
@pytest.mark.parametrize("value", ["-1", "99.5", "automatic", "AUTO", "999;exit 1"])
def test_settings_validation_rejects_invalid_gpu_layer_values(value):
from settings import _validate_env_values
assert _validate_env_values(
{"N_GPU_LAYERS": value},
{"N_GPU_LAYERS": {"type": "string"}},
) == [{
"key": "N_GPU_LAYERS",
"message": "Must be auto, all, or a non-negative whole number.",
}]
def test_settings_validation_rejects_invalid_rag_base_url():
from settings import _build_env_fields, _validate_env_values
values = {"RAG_OPENAI_API_BASE_URL": "embeddings:80/v1"}
fields = _build_env_fields(
{"RAG_OPENAI_API_BASE_URL": {"type": "string"}}, set(), values,
)
assert _validate_env_values(values, fields) == [{
"key": "RAG_OPENAI_API_BASE_URL",
"message": "Must be an HTTP(S) OpenAI-compatible embeddings base URL.",
}]
@pytest.mark.parametrize(
"value",
[
"http://",
"https://:443/v1",
"https://example.test:70000/v1",
"https://user:[email protected]/v1",
"https://example.test/v1#fragment",
"https://example.test\\v1",
"https://example.test:999999999999999999999/v1",
],
)
def test_settings_validation_rejects_malformed_rag_endpoints(value):
from settings import _validate_env_values
assert _validate_env_values(
{"RAG_OPENAI_API_BASE_URL": value},
{"RAG_OPENAI_API_BASE_URL": {"type": "string"}},
) == [{
"key": "RAG_OPENAI_API_BASE_URL",
"message": "Must be an HTTP(S) OpenAI-compatible embeddings base URL.",
}]
@pytest.mark.parametrize(
"value",
[
"http://embeddings:80/v1",
"https://embeddings.example.test/v1?tenant=ods",
"http://127.0.0.1:8090/v1",
"http://[::1]:8090/v1",
],
)
def test_settings_validation_accepts_well_formed_rag_endpoints(value):
from settings import _validate_env_values
assert _validate_env_values(
{"RAG_OPENAI_API_BASE_URL": value},
{"RAG_OPENAI_API_BASE_URL": {"type": "string"}},
) == []
@pytest.mark.parametrize(
"value",
[
"someone/bge-m3-Q4_K_M",
"someone/bge-m3-q8_0",
"someone/bge-m3-GGML",
],
)
def test_settings_validation_rejects_quantized_embedding_artifact_names(value):
from settings import _validate_env_values
issues = _validate_env_values(
{"EMBEDDING_MODEL": value},
{"EMBEDDING_MODEL": {"type": "string"}},
)
assert issues and issues[0]["key"] == "EMBEDDING_MODEL"
def test_settings_validation_rejects_bundled_model_mismatch():
from settings import _build_env_fields, _validate_env_values
values = {
"EMBEDDING_MODEL": "BAAI/bge-m3",
"RAG_EMBEDDING_MODEL": "BAAI/bge-base-en-v1.5",
"RAG_OPENAI_API_BASE_URL": "http://embeddings:80/v1",
}
fields = _build_env_fields(
{key: {"type": "string"} for key in values}, set(), values,
)
issues = _validate_env_values(values, fields)
assert issues == [{
"key": "RAG_EMBEDDING_MODEL",
"message": (
"Bundled TEI serves EMBEDDING_MODEL only. Leave this override empty "
"to inherit it, or set RAG_OPENAI_API_BASE_URL to the external "
"provider that serves this different model."
),
}]
def test_settings_validation_allows_external_model_override():
from settings import _build_env_fields, _validate_env_values
values = {
"EMBEDDING_MODEL": "BAAI/bge-m3",
"RAG_EMBEDDING_MODEL": "external-v2",
"RAG_OPENAI_API_BASE_URL": "https://embeddings.example.test/v1",
}
fields = _build_env_fields(
{key: {"type": "string"} for key in values}, set(), values,
)
assert _validate_env_values(values, fields) == []
def test_settings_apply_plan_treats_hf_token_as_live_read():
from settings import _compute_env_apply_plan
plan = _compute_env_apply_plan(
{"HF_TOKEN": "hf_old_token"},
{"HF_TOKEN": "hf_new_token"},
)
assert plan["status"] == "none"
assert plan["services"] == []
assert plan["manualKeys"] == []
assert plan["summary"] == "No service recreation is required for the saved keys."
# --- Render round-trip fidelity ---
def test_render_env_preserves_extras_with_empty_values():
"""Keys with empty values must survive _render_env_from_values round-trip.
Regression guard for fork issue #335: the old filter
``value != ""`` silently dropped keys like LLAMA_ARG_TENSOR_SPLIT=""
on every save.
"""
from main import _render_env_from_values
values = {
"LLM_BACKEND": "local",
"TENSOR_SPLIT": "", # intentionally empty
"GPU_UUID": "GPU-abc123",
}
rendered = _render_env_from_values(values)
assert "TENSOR_SPLIT=" in rendered
assert "GPU_UUID=GPU-abc123" in rendered
@pytest.fixture()
def commented_example_template(tmp_path, monkeypatch):
"""Patch ``_resolve_template_path`` so .env.example resolution returns a
controlled file containing a commented-assignment line.
Required because the default test environment cannot resolve the real
``.env.example`` (INSTALL_DIR is /tmp/ods-test-install which does not
exist), so without this fixture every value in ``values`` would fall
through to the *extras* branch of ``_render_env_from_values`` and
bypass the ``commented_assignment`` branch the #529 fix targets.
LLAMA_ARG_TENSOR_SPLIT mirrors its real form at .env.example:184
(``# KEY= # trailing comment``).
"""
example_path = tmp_path / ".env.example"
example_path.write_text(
"LLM_BACKEND=local\n"
"# LLAMA_ARG_TENSOR_SPLIT= # Proportional VRAM weights (e.g. 3,1)\n",
encoding="utf-8",
)
def fake_resolve_template(name: str):
if name == ".env.example":
return example_path
return tmp_path / name
monkeypatch.setattr("main._resolve_template_path", fake_resolve_template)
return example_path
def test_render_env_uncomments_commented_key_with_empty_value(commented_example_template):
"""Regression for #529: a commented-out key in .env.example with an explicit
empty value in ``values`` must be rendered as an active empty assignment,
not silently kept as the comment line.
Exercises the ``commented_assignment`` branch of
``_render_env_from_values`` (line 700 in main.py) which the extras-only
test above does not cover. Reverting the production fix flips this from
PASS to FAIL.
"""
from main import _render_env_from_values
rendered = _render_env_from_values({"LLAMA_ARG_TENSOR_SPLIT": ""})
lines = rendered.splitlines()
assert "LLAMA_ARG_TENSOR_SPLIT=" in lines, "must be rendered as active empty assignment"
# Comment-line form must not survive — the original line had a trailing
# comment so test the substring rather than the exact line.
assert not any(line.lstrip().startswith("# LLAMA_ARG_TENSOR_SPLIT=") for line in lines), \
"comment line must not survive"
def test_render_env_uncomments_commented_key_with_value(commented_example_template):
"""Companion to the empty-value test: a commented key in .env.example with
a non-empty value in ``values`` must also be uncommented and assigned."""
from main import _render_env_from_values
rendered = _render_env_from_values({"LLAMA_ARG_TENSOR_SPLIT": "3,1"})
assert "LLAMA_ARG_TENSOR_SPLIT=3,1" in rendered.splitlines()
def test_render_env_preserves_commented_key_absent_from_values(commented_example_template):
"""Absent commented defaults should stay commented on dashboard saves.
Explicit empty values are meaningful, but missing values should not turn
optional template defaults into active empty assignments.
"""
from main import _render_env_from_values
rendered = _render_env_from_values({}) # nothing in values
lines = rendered.splitlines()
assert "LLAMA_ARG_TENSOR_SPLIT=" not in lines
assert any(line.lstrip().startswith("# LLAMA_ARG_TENSOR_SPLIT=") for line in lines)
@pytest.fixture()
def repeated_key_template(tmp_path, monkeypatch):
"""A template that repeats keys the way the real .env.example does: the
same commented default offered in two sections (VIDEO_GID, LLAMA_CPU_LIMIT),
and a prose comment that happens to start with ``# KEY=`` (ODS_MODE)."""
example_path = tmp_path / ".env.example"
example_path.write_text(
"ODS_MODE=local\n"
"# ODS_MODE=cloud and REMOTE_LLM_ENABLED=true. Provider API keys, peer tokens,\n"
"# and routing state live elsewhere.\n"
"# VIDEO_GID=44 # Host 'video' group GID (AMD)\n"
"# LLAMA_CPU_LIMIT=12.0 # Auto-generated\n"
"# --- Strix Halo ---\n"
"# VIDEO_GID=44 # `getent group video | cut -d: -f3`\n"
"# LLAMA_CPU_LIMIT=8.0\n",
encoding="utf-8",
)
def fake_resolve_template(name: str):
if name == ".env.example":
return example_path
return tmp_path / name
monkeypatch.setattr("main._resolve_template_path", fake_resolve_template)
return example_path
def _assignment_lines(rendered: str, key: str) -> list[str]:
return [line for line in rendered.splitlines() if line.startswith(f"{key}=")]
@pytest.mark.parametrize("template", [
"# VIDEO_GID=44\nVIDEO_GID=44\n",
"VIDEO_GID=44\nVIDEO_GID=992\n",
])
def test_render_env_mixed_and_active_repetitions_assign_once(repeated_key_template, template):
from main import _render_env_from_values
repeated_key_template.write_text(template, encoding="utf-8")
assert _assignment_lines(_render_env_from_values({"VIDEO_GID": "7"}), "VIDEO_GID") == ["VIDEO_GID=7"]
def test_render_env_unset_comment_does_not_suppress_later_active_key(repeated_key_template):
from main import _render_env_from_values
repeated_key_template.write_text("# VIDEO_GID=44\nVIDEO_GID=992\n", encoding="utf-8")
rendered = _render_env_from_values({})
assert _assignment_lines(rendered, "VIDEO_GID") == ["VIDEO_GID="]
assert "# VIDEO_GID=44" in rendered.splitlines()
def test_render_env_assigns_repeated_template_key_once(repeated_key_template):
"""Every commented occurrence of a key used to be rewritten into an
assignment, so a value for VIDEO_GID came out twice and validate-env.sh
rejected the saved file. Only the first occurrence may become the
assignment; later ones stay comments."""
from main import _render_env_from_values
rendered = _render_env_from_values({"ODS_MODE": "local", "VIDEO_GID": "44", "LLAMA_CPU_LIMIT": "1.0"})
lines = rendered.splitlines()
assert _assignment_lines(rendered, "VIDEO_GID") == ["VIDEO_GID=44"]
assert _assignment_lines(rendered, "LLAMA_CPU_LIMIT") == ["LLAMA_CPU_LIMIT=1.0"]
assert _assignment_lines(rendered, "ODS_MODE") == ["ODS_MODE=local"]
# The second offers of the same default survive as comments, in place.
assert "# VIDEO_GID=44 # `getent group video | cut -d: -f3`" in lines
assert "# LLAMA_CPU_LIMIT=8.0" in lines
# Prose that merely starts with "# KEY=" is not an assignment site.
assert "# ODS_MODE=cloud and REMOTE_LLM_ENABLED=true. Provider API keys, peer tokens," in lines
def test_render_env_repeated_key_absent_from_values_stays_commented(repeated_key_template):
from main import _render_env_from_values
rendered = _render_env_from_values({"ODS_MODE": "local"})
assert _assignment_lines(rendered, "VIDEO_GID") == []
assert sum(line.startswith("# VIDEO_GID=") for line in rendered.splitlines()) == 2
def test_render_env_real_template_never_duplicates_a_key(monkeypatch):
"""Against the repository's own .env.example: give every key it mentions a
value and make sure no key is assigned twice. Guards the template as much
as the renderer, since a new repeated section would trip validate-env.sh."""
import re
from main import _render_env_from_values
example_path = Path(__file__).resolve().parents[4] / ".env.example"
assert example_path.exists(), example_path
def fake_resolve_template(name: str):
if name == ".env.example":
return example_path
return example_path.parent / name
monkeypatch.setattr("main._resolve_template_path", fake_resolve_template)
mentioned = re.findall(r"^\s*#?\s*([A-Za-z_][A-Za-z0-9_]*)=", example_path.read_text(encoding="utf-8"), re.M)
rendered = _render_env_from_values({key: "x" for key in mentioned})
assigned = [line.split("=", 1)[0] for line in rendered.splitlines() if re.match(r"^[A-Za-z_][A-Za-z0-9_]*=", line)]
duplicates = sorted({key for key in assigned if assigned.count(key) > 1})
assert duplicates == [], f"rendered .env assigns keys more than once: {duplicates}"
assert set(assigned) == set(mentioned)
def test_settings_env_save_assigns_repeated_template_key_once(test_client, settings_env_fixture):
"""End to end through PUT /api/settings/env: a key that .env.example offers
twice (VIDEO_GID in the AMD and Strix Halo sections) must land in .env as
one assignment, so the saved file keeps passing validate-env.sh."""
example_path = settings_env_fixture["example_path"]
schema_path = settings_env_fixture["schema_path"]
schema = json.loads(schema_path.read_text(encoding="utf-8"))
schema["properties"]["VIDEO_GID"] = {"type": "integer", "description": "video group GID"}
schema_path.write_text(json.dumps(schema), encoding="utf-8")
example_path.write_text(
example_path.read_text(encoding="utf-8")
+ "# VIDEO_GID=44 # Host 'video' group GID (AMD)\n"
+ "# --- Strix Halo ---\n"
+ "# VIDEO_GID=44 # `getent group video | cut -d: -f3`\n",
encoding="utf-8",
)
response = test_client.put(
"/api/settings/env",
headers=test_client.auth_headers,
json={"mode": "form", "values": {"VIDEO_GID": "44"}},
)
assert response.status_code == 200, response.text
saved = settings_env_fixture["env_path"].read_text(encoding="utf-8")
assert _assignment_lines(saved, "VIDEO_GID") == ["VIDEO_GID=44"]
assigned = [line.split("=", 1)[0] for line in saved.splitlines() if line and line[0] not in "#" and "=" in line]
assert len(assigned) == len(set(assigned)), f"duplicate assignments in saved .env: {assigned}"
# --- Production schema secret-flag coverage ---
@pytest.mark.parametrize(
"key",
[
"TARGET_API_KEY",
"ANTHROPIC_API_KEY",
"OPENAI_API_KEY",
"TOGETHER_API_KEY",
"LIVEKIT_API_KEY",
"AUDIO_STT_OPENAI_API_KEY",
"AUDIO_TTS_OPENAI_API_KEY",
"RAG_OPENAI_API_KEY",
],
)
def test_production_schema_marks_provider_api_keys_secret(key):
"""Credential API keys in the production schema must carry ``secret: true``.
Regression guard: without the explicit flag, masking in both
``ods config show`` and ``GET /api/settings/env`` falls back to a
name-pattern match. The schema should be the authoritative source.
"""
import pathlib
schema_path = pathlib.Path(__file__).resolve().parents[4] / ".env.schema.json"
schema = json.loads(schema_path.read_text(encoding="utf-8"))
entry = schema["properties"].get(key)
assert entry is not None, f"schema missing entry for {key}"
assert entry.get("secret") is True, f"{key} must have 'secret': true in .env.schema.json"
def test_production_schema_only_allows_explicit_rag_and_retired_secret_removal():
"""Live secrets stay protected; only the RAG key and retired keys can be cleared."""
import pathlib
schema_path = pathlib.Path(__file__).resolve().parents[4] / ".env.schema.json"
schema = json.loads(schema_path.read_text(encoding="utf-8"))
clearable = {
key for key, definition in schema["properties"].items()
if definition.get("clearable") is True
}
retired_secrets = {
key for key, definition in schema["properties"].items()
if definition.get("secret") is True
and definition.get("description", "").startswith("Retired:")
}
assert retired_secrets == {
"OPENCLAW_API_KEY", "OPENCLAW_TOKEN", "LEMONADE_API_KEY", "LITELLM_LEMONADE_API_KEY",
}
assert clearable == {"RAG_OPENAI_API_KEY"} | retired_secrets
def test_production_schema_protects_hermes_dashboard_session_token():
import pathlib
schema_path = pathlib.Path(__file__).resolve().parents[4] / ".env.schema.json"
schema = json.loads(schema_path.read_text(encoding="utf-8"))
entry = schema["properties"]["HERMES_DASHBOARD_SESSION_TOKEN"]
assert entry["secret"] is True
assert entry["minLength"] >= 32
def test_env_example_keys_are_present_in_schema():
"""Every documented .env.example key should be editable in Settings."""
import pathlib
import re
root = pathlib.Path(__file__).resolve().parents[4]
schema = json.loads((root / ".env.schema.json").read_text(encoding="utf-8"))
example = (root / ".env.example").read_text(encoding="utf-8")
documented_keys = {
match.group(1)
for match in re.finditer(r"^\s*#?\s*([A-Z][A-Z0-9_]+)=", example, flags=re.MULTILINE)
}
schema_keys = set(schema.get("properties", {}))
assert documented_keys - schema_keys == set()
# --- Render quoting: values Compose would interpolate or truncate ---
def test_render_env_quotes_values_compose_would_rewrite(commented_example_template):
"""Values the dashboard writes back must read the same for Compose and ODS.
Docker Compose interpolates ``$NAME`` in unquoted values and cuts them at
the first `` #``; a password saved as ``hunter$two`` used to reach the
container as ``hunter``. Such values are written single-quoted (literal
for Compose, ``lib/safe-env.sh`` and ``strip_matching_quotes``); plain
values keep their bare form so existing files stay byte-identical.
"""
from main import _render_env_from_values
from settings import _parse_env_text
values = {
"LLM_BACKEND": "local",
"N8N_PASS": "hunter$two",
"TOKEN_SPY_API_KEY": "token #1",
"LLM_MODEL": "it's $5",
}
rendered = _render_env_from_values(values)
lines = rendered.splitlines()
assert "LLM_BACKEND=local" in lines
assert "N8N_PASS='hunter$two'" in lines
assert "TOKEN_SPY_API_KEY='token #1'" in lines
assert 'LLM_MODEL="it\'s \\$5"' in lines
reparsed, issues = _parse_env_text(rendered)
assert issues == []
assert reparsed["N8N_PASS"] == "hunter$two"
assert reparsed["TOKEN_SPY_API_KEY"] == "token #1"
def test_api_settings_env_save_quotes_interpolation_sensitive_secret(test_client, settings_env_fixture):
env_path = settings_env_fixture["env_path"]
response = test_client.put(
"/api/settings/env",
headers=test_client.auth_headers,
json={
"mode": "form",
"values": {"OPENAI_API_KEY": "sk-live $ecret #1"},
},
)
assert response.status_code == 200
updated_env = env_path.read_text(encoding="utf-8")
assert "OPENAI_API_KEY='sk-live $ecret #1'" in updated_env.splitlines()
from settings import _parse_env_text
saved_values, _ = _parse_env_text(updated_env)
assert saved_values["OPENAI_API_KEY"] == "sk-live $ecret #1"
assert response.json()["fields"]["OPENAI_API_KEY"]["hasValue"] is True
def test_rendered_env_values_match_bash_reader(tmp_path):
"""``lib/safe-env.sh`` (ods-cli) must decode what the dashboard writes."""
import shutil
import subprocess
from pathlib import Path
safe_env = Path(__file__).resolve().parents[4] / "lib" / "safe-env.sh"
if not safe_env.is_file() or shutil.which("bash") is None:
pytest.skip("lib/safe-env.sh or bash not available in this checkout")
from main import _render_env_from_values
values = {
"PLAIN": "value",
"DOLLAR": "hunter$two",
"HASH": "token #1",
"PADDED": " padded ",
"MIXED": "it's $5 \"q\" back\\slash",
}
env_file = tmp_path / ".env"
env_file.write_text(_render_env_from_values(values), encoding="utf-8")
script = (
f". '{safe_env}'; load_env_file '{env_file}'; "
+ " ".join(f"printf '%s\\0' \"${key}\";" for key in values)
)
out = subprocess.run(["bash", "-c", script], capture_output=True, check=True)
decoded = out.stdout.decode("utf-8").split("\0")[: len(values)]
assert decoded == list(values.values())
def test_api_settings_env_save_keeps_compose_comment_semantics(test_client, settings_env_fixture):
"""A hand-written inline comment must not be frozen into the value on save.
Compose reads ``OPENAI_API_KEY=sk-live-secret # rotate me`` as
``sk-live-secret``; the Settings page must read and write back the same.
"""
env_path = settings_env_fixture["env_path"]
env_path.write_text(
"OPENAI_API_KEY=sk-live-secret # rotate me\n"
"RAG_OPENAI_API_KEY=\"rag-live-secret\" # trailing note\n"
"LLM_BACKEND=local\n"
"WEBUI_AUTH=true\n",
encoding="utf-8",
)
response = test_client.put(
"/api/settings/env",
headers=test_client.auth_headers,
json={"mode": "form", "values": {"LLM_BACKEND": "cloud"}},
)
assert response.status_code == 200
lines = env_path.read_text(encoding="utf-8").splitlines()
assert "OPENAI_API_KEY=sk-live-secret" in lines
assert "RAG_OPENAI_API_KEY=rag-live-secret" in lines
assert "LLM_BACKEND=cloud" in lines
def test_api_settings_env_second_save_does_not_double_escape(test_client, settings_env_fixture):
"""Saving twice must be idempotent for values that use the escape set."""
env_path = settings_env_fixture["env_path"]
from settings import _parse_env_text
for _ in range(2):
response = test_client.put(
"/api/settings/env",
headers=test_client.auth_headers,
json={"mode": "form", "values": {"OPENAI_API_KEY": "it's $5 \"q\""}},
)
assert response.status_code == 200
saved, _issues = _parse_env_text(env_path.read_text(encoding="utf-8"))
assert saved["OPENAI_API_KEY"] == "it's $5 \"q\""
assert 'OPENAI_API_KEY="it\'s \\$5 \\"q\\""' in env_path.read_text(encoding="utf-8").splitlines()
def test_api_settings_env_masks_extension_keys_outside_the_schema(test_client, settings_env_fixture):
"""Extension-written credentials that the schema does not describe must be
masked by name. LibreChat's compose requires CREDS_KEY and
LIBRECHAT_MEILI_KEY in .env (``${CREDS_KEY:?...}``), so they exist as
local overrides; they used to come back in cleartext with secret=false.
"""
env_path = settings_env_fixture["env_path"]
env_path.write_text(
env_path.read_text(encoding="utf-8")
+ "CREDS_KEY=creds-leak-value\n"
+ "LIBRECHAT_MEILI_KEY=meili-leak-value\n"
+ "GOOGLE_KEY=google-leak-value\n"
+ "ODS_ROUTER_INTERNAL_KEY=router-leak-value\n"
+ "LANGFUSE_PROJECT_PUBLIC_KEY=pk-lf-visible\n"
+ "TLS_KEY_FILE=/etc/ods/tls.key\n",
encoding="utf-8",
)
response = test_client.get("/api/settings/env", headers=test_client.auth_headers)
assert response.status_code == 200
payload = response.json()
body = json.dumps(payload)
for key, sentinel in (
("CREDS_KEY", "creds-leak-value"),
("LIBRECHAT_MEILI_KEY", "meili-leak-value"),
("GOOGLE_KEY", "google-leak-value"),
("ODS_ROUTER_INTERNAL_KEY", "router-leak-value"),
):
assert payload["fields"][key]["secret"] is True, key
assert payload["fields"][key]["hasValue"] is True, key
assert payload["values"][key] == "", key
assert sentinel not in body, key
# Precision: a public key and a key *file path* are not credentials.
assert payload["fields"]["LANGFUSE_PROJECT_PUBLIC_KEY"]["secret"] is False
assert payload["values"]["LANGFUSE_PROJECT_PUBLIC_KEY"] == "pk-lf-visible"
assert payload["fields"]["TLS_KEY_FILE"]["secret"] is False
assert payload["values"]["TLS_KEY_FILE"] == "/etc/ods/tls.key"
@pytest.mark.parametrize(
("key", "expected"),
[
("CREDS_KEY", True),
("GOOGLE_KEY", True),
("OPENROUTER_KEY", True),
("LIBRECHAT_MEILI_KEY", True),
("ODS_FLEET_PROBE_KEY", True),
("BEDROCK_AWS_SECRET_ACCESS_KEY", True),
("LANGFUSE_PROJECT_PUBLIC_KEY", False),
("SHIELD_API_KEY_PATH", True), # already matched by API_KEY before this change
("TLS_KEY_FILE", False),
("LLAMA_ARG_CACHE_TYPE_K", False),
("LLAMA_ARG_CHECKPOINT_EVERY_N_TOKENS", False),
("KEYBOARD_LAYOUT", False),
],
)
def test_is_secret_field_name_heuristic(key, expected):
from settings import _is_secret_field
assert _is_secret_field(key) is expected
def test_api_settings_env_save_binds_env_revision_to_apply_plan(test_client, settings_env_fixture, monkeypatch):
monkeypatch.setattr('main._active_settings_apply_services', lambda: {'open-webui'})
revision = 'a' * 64
monkeypatch.setattr('main._call_agent_env_update', lambda raw_text: {
'backup_path': 'data/config-backups/.env.backup.test',
'env_revision': revision,
})
response = test_client.put('/api/settings/env', headers=test_client.auth_headers,
json={'mode': 'form', 'values': {'WEBUI_AUTH': False}})
assert response.status_code == 200
assert response.json()['applyPlan']['envRevision'] == revision
def test_api_settings_env_save_marks_plan_unsupported_without_revision(test_client, settings_env_fixture, monkeypatch):
monkeypatch.setattr('main._active_settings_apply_services', lambda: {'open-webui'})
monkeypatch.setattr('main._call_agent_env_update', lambda raw_text: {
'backup_path': 'data/config-backups/.env.backup.test',
})
response = test_client.put('/api/settings/env', headers=test_client.auth_headers,
json={'mode': 'form', 'values': {'WEBUI_AUTH': False}})
assert response.status_code == 200
plan = response.json()['applyPlan']
assert plan['supported'] is False
assert plan['envRevision'] is None
assert 'Update ODS' in plan['summary']
def test_api_settings_env_apply_forwards_expected_revision(test_client, monkeypatch):
captured = {}
def fake_call(service_ids, expected_env_revision=None):
captured['service_ids'] = service_ids
captured['expected_env_revision'] = expected_env_revision
return {'status': 'ok'}
monkeypatch.setattr('main._call_agent_core_recreate', fake_call)
revision = 'b' * 64
response = test_client.post('/api/settings/env/apply', headers=test_client.auth_headers,
json={'service_ids': ['llama-server'], 'expected_env_revision': revision})
assert response.status_code == 200
assert captured == {'service_ids': ['llama-server'], 'expected_env_revision': revision}
def test_api_settings_env_apply_rejects_malformed_revision(test_client):
response = test_client.post('/api/settings/env/apply', headers=test_client.auth_headers,
json={'service_ids': ['llama-server'], 'expected_env_revision': 'nope'})
assert response.status_code == 400
def test_api_settings_env_apply_propagates_env_revision_mismatch(test_client, monkeypatch):
from host_agent_client import AgentHTTPError
def fake_call(service_ids, expected_env_revision=None):
raise AgentHTTPError(409, 'mismatch', json.dumps({
'code': 'env_revision_mismatch',
'error': 'Environment file changed since this plan was saved; reload Settings and re-save before applying.',
}))
monkeypatch.setattr('main._call_agent_core_recreate', fake_call)
response = test_client.post('/api/settings/env/apply', headers=test_client.auth_headers,
json={'service_ids': ['llama-server'], 'expected_env_revision': 'c' * 64})
assert response.status_code == 409
detail = response.json()['detail']
assert detail['code'] == 'env_revision_mismatch'
assert 'reload' in detail['message'].lower()
def test_core_recreate_client_sends_the_expected_revision(monkeypatch):
import main
captured: dict[str, object] = {}
def fake_request(method, path, *, payload, timeout):
captured.update(method=method, path=path, payload=payload, timeout=timeout)
return {'status': 'ok'}
monkeypatch.setattr(main, 'request_agent_json', fake_request)
main._call_agent_core_recreate(['llama-server'], 'd' * 64)
assert captured['payload'] == {'service_ids': ['llama-server'], 'expected_env_revision': 'd' * 64}
main._call_agent_core_recreate(['searxng'])
assert captured['payload'] == {'service_ids': ['searxng']}