Variables and Secrets

Relevant source files

• README.md
• agent.py
• docs/setup/installation.md
• initialize.py
• knowledge/main/about/github_readme.md
• knowledge/main/about/installation.md
• models.py
• python/helpers/guids.py
• python/helpers/memory.py
• python/helpers/settings.py
• python/tools/browser_agent.py
• requirements.txt
• run_ui.py

Purpose and Scope

This page documents how Agent Zero manages sensitive credentials and configuration through project-specific variables and secrets. Projects provide isolated storage for API keys, passwords, and other sensitive data that agents can use without directly seeing the values. This prevents credential leakage in logs, memory, and agent outputs while enabling secure automation.

For general configuration and settings management, see Settings System. For environment variables used during initial setup, see Environment Variables. For project directory structure and organization, see Project Structure.

---

Secret Storage Architecture

Agent Zero stores secrets through a multi-layer system implemented in python/helpers/settings.py153-154 and managed by the secrets manager helper.

Storage Layers

Layer	Implementation	Scope	Code Reference
Settings secrets Field	Settings.secrets: str	Project-scoped	python/helpers/settings.py153-154
.env File	/a0/usr/.env key=value	Global system credentials	python/helpers/settings.py450-453
Settings Authentication	Settings.auth_login, auth_password, etc.	UI and system auth	python/helpers/settings.py123-125

Code Structure

Sources: python/helpers/settings.py53-160 python/helpers/settings.py440-460 python/helpers/settings.py490-508

---

Secret Storage Hierarchy

Sources: README.md123-124 knowledge/main/about/installation.md169-183

---

.env File Format

The global .env file stores system authentication credentials and is separate from project-scoped secrets managed by the secrets manager.

File Location

/a0/usr/.env

Purpose and Scope

The .env file stores system-level authentication only:

Variable	Purpose	Code Reference
AUTH_LOGIN	Web UI username	python/helpers/settings.py450
AUTH_PASSWORD	Web UI password	python/helpers/settings.py451
RFC_PASSWORD	Remote function call password	python/helpers/settings.py452
ROOT_PASSWORD	Container root password	python/helpers/settings.py453
API_KEY_*	LLM provider keys (legacy)	python/helpers/settings.py491-493

Format Example

Loading Process

Writing Process

Authentication values are written back to .env via python/helpers/settings.py490-503:

Note: The .env file should not be version controlled. API keys stored here are legacy; new implementations use the secrets manager for project-scoped credentials.

Sources: python/helpers/settings.py440-460 python/helpers/settings.py490-508

---

SecretsManager Interface

Project-scoped secrets are managed by the SecretsManager class, which provides context-aware secret storage and retrieval.

Obtaining SecretsManager Instance

From code in python/tools/browser_agent.py156-157:

Core Methods

Method	Purpose	Returns	Code Reference
load_secrets()	Load all secrets for current context	dict[str, str]	browser_agent.py157
read_secrets_raw()	Get raw secrets file content	str	settings.py458
get_masked_secrets()	Get secrets with values masked	str	settings.py314
save_secrets_with_merge(content)	Save secrets preserving comments/order	None	settings.py508
mask_values(text, placeholder)	Redact secret values from text	str	browser_agent.py219

Usage Pattern: Loading Secrets

Usage Pattern: Masking Output

From python/tools/browser_agent.py219:

This prevents secret values from appearing in agent prompts or outputs.

Settings Integration

Secrets are stored in the Settings.secrets field python/helpers/settings.py154 and loaded via:

Sources: python/helpers/settings.py154 python/helpers/settings.py311-316 python/helpers/settings.py456-460 python/helpers/settings.py505-508 python/tools/browser_agent.py156-157 python/tools/browser_agent.py219

---

Secret Loading and Context Binding

Secrets are loaded when a SecretsManager is instantiated with an AgentContext. The manager provides context-aware access to project-scoped secrets.

Loading Flow

Browser Agent Integration Example

From python/tools/browser_agent.py156-171:

This ensures:

1. Browser agent has access to secrets for form filling
2. Secret values never appear in agent logs or conversation history
3. Secrets are project-scoped via the AgentContext

Context Binding

Sources: python/tools/browser_agent.py156-171 python/tools/browser_agent.py219 agent.py45-296

---

Security Model: Hidden from Agent

A key security feature is that agents can use secrets without seeing their values. This prevents credential leakage in conversation logs, memory storage, and agent outputs.

How Secrets Are Hidden

Security Mechanisms

Mechanism	Description	Example
Variable Substitution	Agent references $SECRET_NAME, replaced at runtime	$DATABASE_PASSWORD → actual value
Output Redaction	Secret values removed from tool outputs	p@ssw0rd123 → ***SECRET***
Memory Isolation	Secrets never stored in agent memory/embeddings	No secret values in FAISS database
Log Sanitization	Chat logs and history exclude secret values	Conversation history safe to export

Example: Masked Output Redaction

The mask_values() method redacts secret values from any text output:

Before Masking:

After Masking:

Browser Agent Secret Handling

From python/tools/browser_agent.py156-171:

1. Load secrets: secrets_dict = secrets_manager.load_secrets()
2. Pass to browser-use: Secrets available for form filling as sensitive_data
3. Mask input: message = secrets_manager.mask_values(message, placeholder="<secret>{key}</secret>")

The browser-use library receives secrets in a format it can use (<secret>KEY_NAME</secret>), and the actual values are injected by the browser agent during execution. The main Agent Zero agent never sees the raw secret values.

Sources: python/tools/browser_agent.py156-171 python/tools/browser_agent.py219

---

Project Isolation

Project-specific secrets ensure complete isolation between different projects, preventing credential leakage across client boundaries.

Isolation Guarantees

Isolation Benefits

Benefit	Description
Multi-Client Safety	Each client's credentials completely isolated
No Cross-Contamination	Project A agent cannot access Project B secrets
Audit Trail	Secret usage tracked per project
Compliance	Meets data separation requirements for regulated industries

Example: Multi-Client Scenario

Scenario: Managing two clients with different API credentials.

Project Structure:

/a0/usr/projects/
├── acme-corp/
│   └── secrets/
│       └── credentials.env
│           ACME_API_KEY=acme_xxxxxxxxxxxxx
│           ACME_DB_PASSWORD=acme_secure_pass
│
└── globex-inc/
    └── secrets/
        └── credentials.env
            GLOBEX_API_KEY=globex_yyyyyyyyyyyy
            GLOBEX_DB_PASSWORD=globex_secure_pass

Agent in acme-corp project:

• Can access ACME_API_KEY and ACME_DB_PASSWORD
• Cannot access GLOBEX_API_KEY or GLOBEX_DB_PASSWORD
• Can access global .env keys (e.g., OPENAI_API_KEY)

Agent in globex-inc project:

• Can access GLOBEX_API_KEY and GLOBEX_DB_PASSWORD
• Cannot access ACME_API_KEY or ACME_DB_PASSWORD
• Can access global .env keys (e.g., OPENAI_API_KEY)

Sources: README.md123-124 README.md32-34

---

Creating and Managing Secrets

Adding Global Secrets

Method 1: Direct File Edit

Edit /a0/usr/.env:

Add secrets:

Restart container for changes to take effect.

Method 2: Settings UI

1. Open Settings in Web UI
2. Navigate to API Keys tab
3. Add provider-specific API keys
4. Keys are automatically written to .env

Adding Project Secrets

Method 1: File System

Create secret files in project's secrets/ directory:

Method 2: Via Agent (Future Enhancement)

Agents can be instructed to create secrets files programmatically:

Agent: "Create a secret in this project for DATABASE_PASSWORD with value from user"
User: "The password is: secure_db_pass_123"
Agent: *writes to secrets/database.env without exposing value*

Rotating Secrets

To rotate a secret:

1. Update the secret file - Edit .env or project secrets/*.env
2. Restart agent context - Secrets are loaded at context initialization
3. Verify access - Test that new secret works

For active contexts, restart is required to load updated secrets.

Sources: docs/setup/installation.md291-303

---

Variables Field vs Secrets Field

The Settings TypedDict includes both variables and secrets fields python/helpers/settings.py153-154:

Distinction

Field	Purpose	Storage Format	Code Reference
variables	Non-sensitive configuration values	String (likely key=value format)	settings.py153
secrets	Sensitive credentials	String (managed by SecretsManager)	settings.py154

Both are stored as strings in settings.json but are loaded and processed differently by the settings system.

Environment Variables for Initial Configuration

The A0_SET_* prefix in .env provides initial defaults that are merged into settings.json:

From python/helpers/settings.py21-51:

Example .env configuration:

The A0_SET_* variables are only used if settings.json doesn't exist or is missing those values. Once settings are saved via the UI, settings.json takes precedence.

Sources: python/helpers/settings.py21-51 python/helpers/settings.py153-154 python/helpers/settings.py512-602

---

Accessing Secrets in Code

From Tools

Tools access secrets via the SecretsManager obtained from AgentContext:

Reference: Tool base class in python/helpers/tool.py example usage in python/tools/browser_agent.py156-157

From Extensions

Extensions have access to the agent and can retrieve secrets the same way:

Settings UI Integration

The Settings interface reads and writes secrets through the manager:

Reading (from python/helpers/settings.py311-316):

Writing (from python/helpers/settings.py505-508):

The save_secrets_with_merge method preserves comments and order in the secrets file, making manual editing easier.

Sources: python/helpers/settings.py311-316 python/helpers/settings.py505-508 python/tools/browser_agent.py156-157

---

Best Practices

Secret Organization

1. Use project secrets for client-specific credentials

   • API keys unique to a client
   • Database passwords for client databases
   • Service tokens for client integrations

2. Use global secrets for shared services

   • LLM provider API keys (OpenAI, Anthropic)
   • Search service credentials (SearXNG)
   • System-level passwords (RFC, root)

3. Organize secrets by service

   • secrets/database.env - All database credentials
   • secrets/apis.env - External API keys
   • secrets/production.env - Production-only secrets

Security Guidelines

1. Never commit secrets to version control

   • Add .env and secrets/ to .gitignore
   • Use .env.example with dummy values for documentation

2. Use descriptive secret names

   • Good: STRIPE_PRODUCTION_KEY, ACME_CLIENT_API_KEY
   • Bad: KEY1, PASSWORD, SECRET

3. Rotate secrets regularly

   • Update secret files
   • Restart affected contexts
   • Verify functionality

4. Audit secret access

   • Monitor logs for secret usage patterns
   • Track which projects access which secrets
   • Investigate unexpected access

Multi-Project Setup

For managing multiple clients:

/a0/usr/projects/
├── client-alpha/
│   ├── secrets/
│   │   ├── production.env      # Production credentials
│   │   └── staging.env          # Staging credentials
│   └── skills/
├── client-beta/
│   ├── secrets/
│   │   ├── api_keys.env         # All API keys
│   │   └── databases.env        # All DB credentials
│   └── skills/
└── internal-tools/
    ├── secrets/
    │   └── github.env           # GitHub tokens for repos
    └── skills/

Each project maintains complete isolation of sensitive credentials.

Sources: README.md123-124 README.md32-34

---

Troubleshooting

Secret Not Found

Symptom: Tool or agent cannot access expected secret

Diagnostic Steps:

1. Verify secrets manager is initialized:

2. Check secret name (case-sensitive):

3. Verify secrets are loaded for context project:

Secret Value Appearing in Output

Symptom: Secret value visible in agent output or logs

Solutions:

1. Apply output masking:

2. Check browser agent integration: From python/tools/browser_agent.py219:

3. Avoid printing secrets directly:

Settings UI Secrets Not Saving

Symptom: Changes in Settings UI don't persist

Check:

1. Verify merge logic is preserving content: From python/helpers/settings.py505-508:

2. Ensure no exceptions during save: Check logs for errors in _write_sensitive_settings()

3. Verify Settings.secrets field is being written:

Authentication Credentials Not Loading

Symptom: UI login fails or passwords don't work

Check:

1. Verify .env contains auth fields:

2. Check loading in settings: From python/helpers/settings.py450-453:

3. Restart container after .env changes

Sources: python/helpers/settings.py311-316 python/helpers/settings.py440-460 python/helpers/settings.py505-508 python/tools/browser_agent.py219

---

Summary

Agent Zero's variables and secrets system provides:

• Hierarchical storage - Global and project-specific secret isolation
• Hidden credentials - Agents use secrets without seeing values
• Project isolation - Complete separation between client credentials
• Simple format - Standard .env key=value syntax
• Runtime injection - Secrets injected during execution, not exposed in context

This architecture enables secure multi-client workflows where sensitive credentials are properly isolated and never leak into conversation logs, memory systems, or agent outputs.

For setting up projects with secrets, see Managing Projects. For understanding how project isolation works at the memory and knowledge level, see Project Isolation.

Sources: README.md1-393 docs/setup/installation.md1-586