Skip to content

Agent Zero AI framework

#81 - .env vars applied to settings

deci2400dd588200
diff --git a/README.md b/README.md
index 8c0bb596a..d2c0d9b4b 100644
--- a/README.md
+++ b/README.md
@@ -81,6 +81,7 @@ Agent Zero now supports **Projects** – isolated workspaces with their own prom
- The framework does not guide or limit the agent in any way. There are no hard-coded rails that agents have to follow.
- Every prompt, every small message template sent to the agent in its communication loop can be found in the **prompts/** folder and changed.
- Every default tool can be found in the **python/tools/** folder and changed or copied to create new predefined tools.
+- **Automated configuration** via `A0_SET_` environment variables for deployment automation and easy setup.
![Prompts](/docs/res/prompts.png)
diff --git a/docs/development.md b/docs/development.md
index 54fe39580..9faa1805b 100644
--- a/docs/development.md
+++ b/docs/development.md
@@ -149,6 +149,20 @@ You're now ready to contribute to Agent Zero, create custom extensions, or modif
- See [extensibility](extensibility.md) for instructions on how to create custom extensions.
- See [contribution](contribution.md) for instructions on how to contribute to the framework.
+## Configuration via Environment Variables
+
+For development and testing, you can override default settings using the `.env` file with `A0_SET_` prefixed variables:
+
+```env
+# Add to your .env file
+A0_SET_chat_model_provider=ollama
+A0_SET_chat_model_name=llama3.2
+A0_SET_chat_model_api_base=http://localhost:11434
+A0_SET_memory_recall_interval=5
+```
+
+These environment variables automatically override the hardcoded defaults in `get_default_settings()` without modifying code. Useful for testing different configurations or multi-environment setups.
+
## Want to build your docker image?
- You can use the `DockerfileLocal` to build your docker image.
- Navigate to your project root in the terminal and run `docker build -f DockerfileLocal -t agent-zero-local --build-arg CACHE_DATE=$(date +%Y-%m-%d:%H:%M:%S) .`
diff --git a/docs/installation.md b/docs/installation.md
index b8688f091..26bdab10f 100644
--- a/docs/installation.md
+++ b/docs/installation.md
@@ -93,9 +93,55 @@ The following user guide provides instructions for installing and running Agent
- `/tmp/settings.json` - Your Agent Zero settings
> [!TIP]
-> Choose a location that's easy to access and backup. All your Agent Zero data
+> Choose a location that's easy to access and backup. All your Agent Zero data
> will be directly accessible in this directory.
+### Automated Configuration via Environment Variables
+
+Agent Zero settings can be automatically configured using environment variables with the `A0_SET_` prefix in your `.env` file. This enables automated deployments without manual configuration.
+
+**Usage:**
+Add variables to your `.env` file in the format:
+```
+A0_SET_{setting_name}={value}
+```
+
+**Examples:**
+```env
+# Model configuration
+A0_SET_chat_model_provider=anthropic
+A0_SET_chat_model_name=claude-3-5-sonnet-20241022
+A0_SET_chat_model_ctx_length=200000
+
+# Memory settings
+A0_SET_memory_recall_enabled=true
+A0_SET_memory_recall_interval=5
+
+# Agent configuration
+A0_SET_agent_profile=custom
+A0_SET_agent_memory_subdir=production
+```
+
+**Docker usage:**
+When running Docker, you can pass these as environment variables:
+```bash
+docker run -p 50080:80 \
+ -e A0_SET_chat_model_provider=anthropic \
+ -e A0_SET_chat_model_name=claude-3-5-sonnet-20241022 \
+ agent0ai/agent-zero
+```
+
+**Type conversion:**
+- Strings are used as-is
+- Numbers are automatically converted (e.g., "100000" becomes integer 100000)
+- Booleans accept: true/false, 1/0, yes/no, on/off (case-insensitive)
+- Dictionaries must be valid JSON (e.g., `{"temperature": "0"}`)
+
+**Notes:**
+- These override default values in settings.json
+- Sensitive settings (API keys, passwords) use their existing environment variables
+- Container/process restart required for changes to take effect
+
2.3. Run the container:
- In Docker Desktop, go back to the "Images" tab
- Click the `Run` button next to the `agent0ai/agent-zero` image
diff --git a/python/helpers/settings.py b/python/helpers/settings.py
index 9e71b7956..b6ca2df0b 100644
--- a/python/helpers/settings.py
+++ b/python/helpers/settings.py
@@ -4,7 +4,7 @@ import json
import os
import re
import subprocess
-from typing import Any, Literal, TypedDict, cast
+from typing import Any, Literal, TypedDict, cast, TypeVar
import models
from python.helpers import runtime, whisper, defer, git
@@ -15,6 +15,38 @@ from python.helpers.secrets import get_default_secrets_manager
from python.helpers import dirty_json
+T = TypeVar('T')
+
+def get_default_value(name: str, value: T) -> T:
+ """
+ Load setting value from .env with A0_SET_ prefix, falling back to default.
+
+ Args:
+ name: Setting name (will be prefixed with A0_SET_)
+ value: Default value to use if env var not set
+
+ Returns:
+ Environment variable value (type-normalized) or default value
+ """
+ env_value = dotenv.get_dotenv_value(f"A0_SET_{name}")
+
+ if env_value is None:
+ return value
+
+ # Normalize type to match value param type
+ try:
+ if isinstance(value, bool):
+ return env_value.lower() in ('true', '1', 'yes', 'on') # type: ignore
+ elif isinstance(value, dict):
+ return json.loads(env_value) # type: ignore
+ elif isinstance(value, str):
+ return str(env_value).strip() # type: ignore
+ else:
+ return type(value)(env_value) # type: ignore
+ except (ValueError, TypeError, json.JSONDecodeError):
+ return value
+
+
class Settings(TypedDict):
version: str
@@ -1456,83 +1488,83 @@ def _write_sensitive_settings(settings: Settings):
def get_default_settings() -> Settings:
return Settings(
version=_get_version(),
- chat_model_provider="openrouter",
- chat_model_name="openai/gpt-4.1",
- chat_model_api_base="",
- chat_model_kwargs={"temperature": "0"},
- chat_model_ctx_length=100000,
- chat_model_ctx_history=0.7,
- chat_model_vision=True,
- chat_model_rl_requests=0,
- chat_model_rl_input=0,
- chat_model_rl_output=0,
- util_model_provider="openrouter",
- util_model_name="openai/gpt-4.1-mini",
- util_model_api_base="",
- util_model_ctx_length=100000,
- util_model_ctx_input=0.7,
- util_model_kwargs={"temperature": "0"},
- util_model_rl_requests=0,
- util_model_rl_input=0,
- util_model_rl_output=0,
- embed_model_provider="huggingface",
- embed_model_name="sentence-transformers/all-MiniLM-L6-v2",
- embed_model_api_base="",
- embed_model_kwargs={},
- embed_model_rl_requests=0,
- embed_model_rl_input=0,
- browser_model_provider="openrouter",
- browser_model_name="openai/gpt-4.1",
- browser_model_api_base="",
- browser_model_vision=True,
- browser_model_rl_requests=0,
- browser_model_rl_input=0,
- browser_model_rl_output=0,
- browser_model_kwargs={"temperature": "0"},
- browser_http_headers={},
- memory_recall_enabled=True,
- memory_recall_delayed=False,
- memory_recall_interval=3,
- memory_recall_history_len=10000,
- memory_recall_memories_max_search=12,
- memory_recall_solutions_max_search=8,
- memory_recall_memories_max_result=5,
- memory_recall_solutions_max_result=3,
- memory_recall_similarity_threshold=0.7,
- memory_recall_query_prep=True,
- memory_recall_post_filter=True,
- memory_memorize_enabled=True,
- memory_memorize_consolidation=True,
- memory_memorize_replace_threshold=0.9,
+ chat_model_provider=get_default_value("chat_model_provider", "openrouter"),
+ chat_model_name=get_default_value("chat_model_name", "openai/gpt-4.1"),
+ chat_model_api_base=get_default_value("chat_model_api_base", ""),
+ chat_model_kwargs=get_default_value("chat_model_kwargs", {"temperature": "0"}),
+ chat_model_ctx_length=get_default_value("chat_model_ctx_length", 100000),
+ chat_model_ctx_history=get_default_value("chat_model_ctx_history", 0.7),
+ chat_model_vision=get_default_value("chat_model_vision", True),
+ chat_model_rl_requests=get_default_value("chat_model_rl_requests", 0),
+ chat_model_rl_input=get_default_value("chat_model_rl_input", 0),
+ chat_model_rl_output=get_default_value("chat_model_rl_output", 0),
+ util_model_provider=get_default_value("util_model_provider", "openrouter"),
+ util_model_name=get_default_value("util_model_name", "openai/gpt-4.1-mini"),
+ util_model_api_base=get_default_value("util_model_api_base", ""),
+ util_model_ctx_length=get_default_value("util_model_ctx_length", 100000),
+ util_model_ctx_input=get_default_value("util_model_ctx_input", 0.7),
+ util_model_kwargs=get_default_value("util_model_kwargs", {"temperature": "0"}),
+ util_model_rl_requests=get_default_value("util_model_rl_requests", 0),
+ util_model_rl_input=get_default_value("util_model_rl_input", 0),
+ util_model_rl_output=get_default_value("util_model_rl_output", 0),
+ embed_model_provider=get_default_value("embed_model_provider", "huggingface"),
+ embed_model_name=get_default_value("embed_model_name", "sentence-transformers/all-MiniLM-L6-v2"),
+ embed_model_api_base=get_default_value("embed_model_api_base", ""),
+ embed_model_kwargs=get_default_value("embed_model_kwargs", {}),
+ embed_model_rl_requests=get_default_value("embed_model_rl_requests", 0),
+ embed_model_rl_input=get_default_value("embed_model_rl_input", 0),
+ browser_model_provider=get_default_value("browser_model_provider", "openrouter"),
+ browser_model_name=get_default_value("browser_model_name", "openai/gpt-4.1"),
+ browser_model_api_base=get_default_value("browser_model_api_base", ""),
+ browser_model_vision=get_default_value("browser_model_vision", True),
+ browser_model_rl_requests=get_default_value("browser_model_rl_requests", 0),
+ browser_model_rl_input=get_default_value("browser_model_rl_input", 0),
+ browser_model_rl_output=get_default_value("browser_model_rl_output", 0),
+ browser_model_kwargs=get_default_value("browser_model_kwargs", {"temperature": "0"}),
+ browser_http_headers=get_default_value("browser_http_headers", {}),
+ memory_recall_enabled=get_default_value("memory_recall_enabled", True),
+ memory_recall_delayed=get_default_value("memory_recall_delayed", False),
+ memory_recall_interval=get_default_value("memory_recall_interval", 3),
+ memory_recall_history_len=get_default_value("memory_recall_history_len", 10000),
+ memory_recall_memories_max_search=get_default_value("memory_recall_memories_max_search", 12),
+ memory_recall_solutions_max_search=get_default_value("memory_recall_solutions_max_search", 8),
+ memory_recall_memories_max_result=get_default_value("memory_recall_memories_max_result", 5),
+ memory_recall_solutions_max_result=get_default_value("memory_recall_solutions_max_result", 3),
+ memory_recall_similarity_threshold=get_default_value("memory_recall_similarity_threshold", 0.7),
+ memory_recall_query_prep=get_default_value("memory_recall_query_prep", True),
+ memory_recall_post_filter=get_default_value("memory_recall_post_filter", True),
+ memory_memorize_enabled=get_default_value("memory_memorize_enabled", True),
+ memory_memorize_consolidation=get_default_value("memory_memorize_consolidation", True),
+ memory_memorize_replace_threshold=get_default_value("memory_memorize_replace_threshold", 0.9),
api_keys={},
auth_login="",
auth_password="",
root_password="",
- agent_profile="agent0",
- agent_memory_subdir="default",
- agent_knowledge_subdir="custom",
- rfc_auto_docker=True,
- rfc_url="localhost",
+ agent_profile=get_default_value("agent_profile", "agent0"),
+ agent_memory_subdir=get_default_value("agent_memory_subdir", "default"),
+ agent_knowledge_subdir=get_default_value("agent_knowledge_subdir", "custom"),
+ rfc_auto_docker=get_default_value("rfc_auto_docker", True),
+ rfc_url=get_default_value("rfc_url", "localhost"),
rfc_password="",
- rfc_port_http=55080,
- rfc_port_ssh=55022,
- shell_interface="local" if runtime.is_dockerized() else "ssh",
- stt_model_size="base",
- stt_language="en",
- stt_silence_threshold=0.3,
- stt_silence_duration=1000,
- stt_waiting_timeout=2000,
- tts_kokoro=True,
- mcp_servers='{\n "mcpServers": {}\n}',
- mcp_client_init_timeout=10,
- mcp_client_tool_timeout=120,
- mcp_server_enabled=False,
+ rfc_port_http=get_default_value("rfc_port_http", 55080),
+ rfc_port_ssh=get_default_value("rfc_port_ssh", 55022),
+ shell_interface=get_default_value("shell_interface", "local" if runtime.is_dockerized() else "ssh"),
+ stt_model_size=get_default_value("stt_model_size", "base"),
+ stt_language=get_default_value("stt_language", "en"),
+ stt_silence_threshold=get_default_value("stt_silence_threshold", 0.3),
+ stt_silence_duration=get_default_value("stt_silence_duration", 1000),
+ stt_waiting_timeout=get_default_value("stt_waiting_timeout", 2000),
+ tts_kokoro=get_default_value("tts_kokoro", True),
+ mcp_servers=get_default_value("mcp_servers", '{\n "mcpServers": {}\n}'),
+ mcp_client_init_timeout=get_default_value("mcp_client_init_timeout", 10),
+ mcp_client_tool_timeout=get_default_value("mcp_client_tool_timeout", 120),
+ mcp_server_enabled=get_default_value("mcp_server_enabled", False),
mcp_server_token=create_auth_token(),
- a2a_server_enabled=False,
+ a2a_server_enabled=get_default_value("a2a_server_enabled", False),
variables="",
secrets="",
- litellm_global_kwargs={},
- update_check_enabled=True,
+ litellm_global_kwargs=get_default_value("litellm_global_kwargs", {}),
+ update_check_enabled=get_default_value("update_check_enabled", True),
)