Overview Solace Agent Mesh uses environment variables to configure brokers, LLM services, and runtime behavior. All environment variables are stored in the .env file in your project root.
The .env file is created automatically during sam init. Never commit this file to version control as it contains sensitive credentials.
Core Environment Variables Broker Configuration These variables configure the connection to your Solace PubSub+ broker:
Variable Description Default Example SOLACE_BROKER_URLWebSocket URL for broker connection ws://localhost:8008wss://broker.example.com:443SOLACE_BROKER_VPNMessage VPN name defaultproduction-vpnSOLACE_BROKER_USERNAMEAuthentication username defaultsam-service-accountSOLACE_BROKER_PASSWORDAuthentication password defaultsecure-password-123SOLACE_DEV_MODEEnable internal dev broker (no external broker needed) falsetrue or false
Production Broker
Local Container
Dev Mode
SOLACE_BROKER_URL = "wss://production-broker.example.com:443" SOLACE_BROKER_VPN = "production-vpn" SOLACE_BROKER_USERNAME = "service-account" SOLACE_BROKER_PASSWORD = "secure-password" SOLACE_DEV_MODE = "false"
LLM Service Configuration Configure your LLM provider (OpenAI, Anthropic, Azure, or any LiteLLM-compatible service):
Variable Description Required Example LLM_SERVICE_ENDPOINTLLM API base URL Yes https://api.openai.com/v1LLM_SERVICE_API_KEYAPI key for authentication Yes sk-proj-...LLM_SERVICE_PLANNING_MODEL_NAMEModel for complex planning tasks Yes openai/gpt-4oLLM_SERVICE_GENERAL_MODEL_NAMEModel for general tasks Yes openai/gpt-3.5-turbo
OpenAI
Anthropic
Azure OpenAI
Custom Endpoint
LLM_SERVICE_ENDPOINT = "https://api.openai.com/v1" LLM_SERVICE_API_KEY = "sk-proj-..." LLM_SERVICE_PLANNING_MODEL_NAME = "openai/gpt-4o" LLM_SERVICE_GENERAL_MODEL_NAME = "openai/gpt-3.5-turbo"
LLM OAuth 2.0 Configuration For LLM providers requiring OAuth 2.0 Client Credentials flow:
Variable Description Required Example LLM_SERVICE_OAUTH_ENDPOINTOAuth-protected LLM endpoint Yes* https://llm.example.com/v1LLM_SERVICE_OAUTH_TOKEN_URLOAuth token endpoint Yes* https://auth.example.com/oauth/tokenLLM_SERVICE_OAUTH_CLIENT_IDOAuth client ID Yes* sam-client-idLLM_SERVICE_OAUTH_CLIENT_SECRETOAuth client secret Yes* client-secret-xyzLLM_SERVICE_OAUTH_SCOPEOAuth scopes (space-separated) No llm.read llm.writeLLM_SERVICE_OAUTH_CA_CERT_PATHCustom CA certificate path No /path/to/ca-cert.pemLLM_SERVICE_OAUTH_TOKEN_REFRESH_BUFFER_SECONDSToken refresh buffer time No 300LLM_SERVICE_OAUTH_PLANNING_MODEL_NAMEPlanning model (OAuth) Yes* company/planning-modelLLM_SERVICE_OAUTH_GENERAL_MODEL_NAMEGeneral model (OAuth) Yes* company/general-model
*Required only when using OAuth authentication. Use *oauth_planning_model or *oauth_general_model in your YAML configs to enable OAuth.
LLM_SERVICE_OAUTH_ENDPOINT = "https://llm.mycompany.com/v1" LLM_SERVICE_OAUTH_TOKEN_URL = "https://auth.mycompany.com/oauth/token" LLM_SERVICE_OAUTH_CLIENT_ID = "sam-production-client" LLM_SERVICE_OAUTH_CLIENT_SECRET = "super-secret-value" LLM_SERVICE_OAUTH_SCOPE = "llm.inference" LLM_SERVICE_OAUTH_TOKEN_REFRESH_BUFFER_SECONDS = "300" LLM_SERVICE_OAUTH_PLANNING_MODEL_NAME = "internal/gpt-4-equivalent" LLM_SERVICE_OAUTH_GENERAL_MODEL_NAME = "internal/gpt-3.5-equivalent"
Project Configuration Variable Description Default Example NAMESPACETopic namespace prefix for all agents solace_app/my_project/LOGGING_CONFIG_PATHPath to logging configuration configs/logging_config.yamlconfigs/custom_logging.yaml
NAMESPACE = "production/customer_service/" LOGGING_CONFIG_PATH = "configs/logging_config.yaml"
The NAMESPACE must end with a forward slash (/) for proper topic routing.
Web UI Gateway Variables Configuration for the built-in chat interface:
Variable Description Default Example FASTAPI_HOSTHost address for FastAPI server 127.0.0.10.0.0.0FASTAPI_PORTHTTP port for web UI 80008080FASTAPI_HTTPS_PORTHTTPS port (when SSL enabled) 8443443SESSION_SECRET_KEYSecret key for session encryption Auto-generated your-secret-key-hereENABLE_EMBED_RESOLUTIONEnable dynamic embeds in responses truetrue or falseSSL_KEYFILEPath to SSL private key file Empty /path/to/privkey.pemSSL_CERTFILEPath to SSL certificate file Empty /path/to/fullchain.pemSSL_KEYFILE_PASSWORDPassword for encrypted key file Empty key-password
FASTAPI_HOST = "127.0.0.1" FASTAPI_PORT = "8000" SESSION_SECRET_KEY = "randomly-generated-secret-key" ENABLE_EMBED_RESOLUTION = "true" SSL_KEYFILE = "" SSL_CERTFILE = ""
To generate a secure session secret key: python3 -c "import secrets; print(secrets.token_urlsafe(32))"
Configuration for the Platform API (management interface):
Variable Description Default Example PLATFORM_API_HOSTPlatform API host 127.0.0.10.0.0.0PLATFORM_API_PORTPlatform API port 80019000PLATFORM_SERVICE_URLFull Platform API URL Auto-generated http://localhost:8001
PLATFORM_API_HOST = "0.0.0.0" PLATFORM_API_PORT = "8001" PLATFORM_SERVICE_URL = "http://localhost:8001"
Artifact Storage Variables Configure where agent-generated files are stored:
S3-Compatible Storage For AWS S3, MinIO, or other S3-compatible services:
Variable Description Default Example S3_BUCKET_NAMES3 bucket name Empty sam-artifactsS3_ENDPOINT_URLS3 endpoint (leave empty for AWS S3) Empty https://s3.us-east-1.amazonaws.comS3_REGIONAWS region us-east-1us-west-2AWS_ACCESS_KEY_IDAWS access key N/A AKIAIOSFODNN7EXAMPLEAWS_SECRET_ACCESS_KEYAWS secret key N/A wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
S3_BUCKET_NAME = "my-sam-artifacts" S3_ENDPOINT_URL = "" S3_REGION = "us-east-1" AWS_ACCESS_KEY_ID = "AKIAIOSFODNN7EXAMPLE" AWS_SECRET_ACCESS_KEY = "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY"
Google Cloud Storage For GCS artifact storage:
GOOGLE_APPLICATION_CREDENTIALS = "/path/to/service-account-key.json" GCS_BUCKET_NAME = "sam-artifacts-bucket"
Database Variables For SQL-based session and state storage:
Variable Description Default Example ORCHESTRATOR_DATABASE_URLOrchestrator session database sqlite:///data/orchestrator.dbpostgresql://user:pass@host/dbWEB_UI_GATEWAY_DATABASE_URLWeb UI session database sqlite:///data/webui_gateway.dbpostgresql://user:pass@host/db
SQLite (Default)
PostgreSQL
PostgreSQL with SSL
ORCHESTRATOR_DATABASE_URL = "sqlite:///data/orchestrator.db" WEB_UI_GATEWAY_DATABASE_URL = "sqlite:///data/webui_gateway.db"
Optional Service Variables Image Generation For agents that generate images:
IMAGE_SERVICE_ENDPOINT = "https://api.openai.com/v1" IMAGE_SERVICE_API_KEY = "sk-..." IMAGE_MODEL_NAME = "dall-e-3"
Report Generation For custom report generation models:
LLM_REPORT_MODEL_NAME = "openai/gpt-4o"
Auto-Summarization Prevents token limit errors by auto-summarizing conversation history:
SAM_ENABLE_AUTO_SUMMARIZATION = "false" # Set to "true" to enable SAM_COMPACTION_PERCENTAGE = "0.25" # Compact 25% of history when threshold exceeded
Queue Configuration USE_TEMPORARY_QUEUES = "true" # Use temporary queues for agent responses
Environment Variable Substitution YAML configuration files can reference environment variables using ${VAR_NAME} or ${VAR_NAME, default_value} syntax:
# In shared_config.yaml broker_connection : broker_url : ${SOLACE_BROKER_URL, ws://localhost:8008} broker_username : ${SOLACE_BROKER_USERNAME, default} model : model : ${LLM_SERVICE_PLANNING_MODEL_NAME} api_base : ${LLM_SERVICE_ENDPOINT} api_key : ${LLM_SERVICE_API_KEY}
Security Best Practices
Never Commit .env Files
Add .env to your .gitignore: .env .env.* ! .env.example
Use Environment-Specific Files
Create separate env files for different environments: .env.development .env.staging .env.production
Restrict File Permissions
Rotate Secrets Regularly
Rotate API keys periodically
Use different credentials per environment
Monitor for unauthorized access
Use Secret Management Services
For production, consider:
AWS Secrets Manager
HashiCorp Vault
Azure Key Vault
Google Secret Manager
Example .env File Complete example with all common variables:
# Broker Configuration SOLACE_BROKER_URL = "ws://localhost:8008" SOLACE_BROKER_VPN = "default" SOLACE_BROKER_USERNAME = "default" SOLACE_BROKER_PASSWORD = "default" SOLACE_DEV_MODE = "false" # LLM Configuration LLM_SERVICE_ENDPOINT = "https://api.openai.com/v1" LLM_SERVICE_API_KEY = "sk-proj-..." LLM_SERVICE_PLANNING_MODEL_NAME = "openai/gpt-4o" LLM_SERVICE_GENERAL_MODEL_NAME = "openai/gpt-3.5-turbo" # Project Settings NAMESPACE = "my_project/" LOGGING_CONFIG_PATH = "configs/logging_config.yaml" # Web UI Gateway FASTAPI_HOST = "127.0.0.1" FASTAPI_PORT = "8000" FASTAPI_HTTPS_PORT = "8443" SESSION_SECRET_KEY = "your-random-secret-key-here" ENABLE_EMBED_RESOLUTION = "true" SSL_KEYFILE = "" SSL_CERTFILE = "" SSL_KEYFILE_PASSWORD = "" # Platform Service PLATFORM_API_HOST = "127.0.0.1" PLATFORM_API_PORT = "8001" PLATFORM_SERVICE_URL = "http://127.0.0.1:8001" # Artifact Storage S3_BUCKET_NAME = "" S3_ENDPOINT_URL = "" S3_REGION = "us-east-1" # Database URLs ORCHESTRATOR_DATABASE_URL = "sqlite:///data/orchestrator.db" WEB_UI_GATEWAY_DATABASE_URL = "sqlite:///data/webui_gateway.db"
Troubleshooting Variables Not Loading If environment variables aren’t being recognized:
Check .env file exists in project root
Verify no syntax errors (no spaces around =)
Restart the agent mesh: sam run
Check for typos in variable names
Invalid Values If you see “invalid value” errors:
Check for extra quotes or spaces
Boolean values should be true or false (lowercase)
URLs should include protocol (http:// or https://)
Namespaces must end with /
Missing Required Variables If required variables are missing:
# Re-run initialization to regenerate .env sam init # Or manually add missing variables from the example above
Next Steps 
