Security

Secrets & Variables

Manage secrets and environment variables securely for API keys, credentials, and configuration values.

Agent Zero supports both global secrets (Settings) and project-scoped secrets (Projects). For detailed information on project-specific secrets and variables, see the Projects guide.

→ View Project Secrets Guide

Global Secrets

Global secrets are available to all chats and projects unless overridden:

  1. Open Settings in the sidebar
  2. Navigate to External Services or Agent Settings
  3. Enter API keys for services (OpenRouter, OpenAI, etc.)
  4. Click Save

Common Global Secrets:

  • OpenRouter API Key
  • OpenAI API Key
  • Anthropic API Key
  • Database credentials
  • Email service credentials

Project-Scoped Secrets

Projects can have their own isolated secrets that override global settings:

Variables (Non-sensitive)

Stored in .a0proj/variables.env:

API_BASE_URL=https://api.example.com
DEFAULT_TIMEOUT=30
OUTPUT_FORMAT=json

Secrets (Sensitive)

Stored in .a0proj/secrets.env:

API_KEY=sk-abc123xyz...
DATABASE_PASSWORD=super_secret_pwd
GITHUB_TOKEN=ghp_xyz789...

⚠️ Security: Project secrets override global secrets and are stored locally in the container. They are masked in the UI and may not be included in automatic backups.

Using Secrets in Prompts

Reference secrets by name in your prompts:

Example:

"Use my API_KEY to authenticate with the external service and fetch the data."

"Connect to the database using my DATABASE_PASSWORD and run the query."

The agent automatically accesses the appropriate secrets from the current context (project-scoped if available, otherwise global).

Best Practices

  • Use project secrets for client-specific credentials
  • Never commit secrets to version control
  • Backup secrets manually - they may not be in automatic backups
  • Rotate credentials periodically for security
  • Use meaningful names that clearly indicate purpose
  • Document required secrets in project instructions