botserver/docs/src/appendix-env-vars/README.md

Appendix C: Environment Variables

General Bots uses a minimal set of environment variables. All configuration is managed through config.csv files within each bot's .gbot folder, with secrets stored securely in Vault.

Required Environment Variables

Only Vault-related environment variables are used by General Bots:

VAULT_* Variables

Purpose: HashiCorp Vault integration for secure secrets management.

Variable	Description	Example
VAULT_ADDR	Vault server URL	http://localhost:8200
VAULT_TOKEN	Authentication token	Auto-generated during bootstrap
VAULT_NAMESPACE	Vault namespace (optional)	admin

Example:

VAULT_ADDR=http://localhost:8200
VAULT_TOKEN=hvs.your-vault-token

Auto-Managed Services

The following services are automatically configured through Vault:

Service	Management
PostgreSQL	Connection credentials in Vault
S3-Compatible Storage	Access keys in Vault
Cache	Connection managed via Vault
Email (Stalwart)	Credentials in Vault
LLM API Keys	Stored in Vault

You do not need to set environment variables for these services. Vault handles credential distribution and rotation automatically.

What NOT to Use Environment Variables For

All application configuration belongs in config.csv:

Configuration	Where to Configure
Database connection	Managed by Vault
Storage credentials	Managed by Vault
LLM API keys	Managed by Vault
LLM provider	config.csv: llm-url
Email settings	config.csv: email-*
Channel tokens	config.csv: whatsapp-*, etc.
Bot settings	config.csv: all bot-specific settings
Feature flags	config.csv: various keys

Configuration Philosophy

General Bots follows these principles:

1. Vault-First: All secrets are managed by Vault
2. Minimal Environment: Only Vault address and token use environment variables
3. config.csv for Settings: All application configuration is in config.csv
4. Per-Bot Configuration: Each bot has its own config.csv in its .gbot folder
5. No Hardcoded Secrets: Never store secrets in code or config files

Setting Environment Variables

Linux/macOS

export VAULT_ADDR=http://localhost:8200
export VAULT_TOKEN=hvs.your-vault-token

Systemd Service

[Service]
Environment="VAULT_ADDR=http://localhost:8200"
Environment="VAULT_TOKEN=hvs.your-vault-token"

LXC Container

When using LXC deployment, environment variables are set in the container configuration:

lxc config set container-name environment.VAULT_ADDR="http://localhost:8200"
lxc config set container-name environment.VAULT_TOKEN="hvs.your-vault-token"

Security Notes

1. Never commit tokens: Use .env files (gitignored) or secrets management
2. Rotate regularly: Vault tokens should be rotated periodically
3. Limit access: Only the botserver process needs these variables
4. Use TLS: Always use HTTPS for Vault in production

Bootstrap Process

During bootstrap, General Bots:

1. Connects to Vault using VAULT_* variables
2. Retrieves credentials for all managed services
3. Configures database, storage, cache, and other services
4. Stores service endpoints securely

This eliminates the need for manual credential management.

Troubleshooting

Vault Connection Failed

Error: Failed to connect to Vault

Verify:

• VAULT_ADDR is set correctly
• Vault server is running and accessible
• VAULT_TOKEN is valid and not expired
• Network allows connection to Vault host

Service Not Available

If a managed service (database, storage, cache) is unavailable:

1. Check Vault is running and unsealed
2. Verify secrets exist in Vault
3. Check service container/process status
4. Review logs for connection errors

See Also

• config.csv Format - Bot configuration
• Secrets Management - Vault integration details
• Drive Integration - Storage setup
• Authentication - Security features