⚙️ Configuration

HippoX can be configured through multiple methods: environment variables, TOML files, JSON files, or programmatically via API. Configuration is loaded in priority order, with programmatic overrides taking highest precedence.

🔧

Configuration Priority: Programmatic Parameters greater than JSON String greater than JSON File greater than TOML File greater than Environment Variables greater than Defaults

🌐 Environment Variables

Set environment variables before starting your application. This is the simplest way to get started.

Basic Settings

Variable	Description	Default
HIPPOX_LANG	Language setting (en or zh)	en

SMTP Email Settings

Variable	Description
HIPPOX_SMTP_HOST	SMTP server hostname (e.g., smtp.gmail.com)
HIPPOX_SMTP_PORT	SMTP server port (587 for TLS, 465 for SSL)
HIPPOX_SMTP_USERNAME	SMTP authentication username
HIPPOX_SMTP_PASSWORD	SMTP authentication password
HIPPOX_SMTP_FROM	Default sender email address

Messaging Platform Settings

Variable	Description
HIPPOX_TELEGRAM_BOT_TOKEN	Telegram bot token
HIPPOX_DINGDING_ACCESS_TOKEN	DingTalk robot access token
HIPPOX_FEISHU_WEBHOOK	Feishu bot webhook URL
HIPPOX_WECOM_WEBHOOK	WeCom robot webhook URL

FTP Settings

Variable	Description	Default
HIPPOX_FTP_HOST	FTP server hostname	(empty)
HIPPOX_FTP_PORT	FTP server port	21
HIPPOX_FTP_USERNAME	FTP username	anonymous
HIPPOX_FTP_PASSWORD	FTP password	(empty)
HIPPOX_FTP_REMOTE_DIR	Default remote directory	/
HIPPOX_FTP_TIMEOUT	Connection timeout in seconds	30
HIPPOX_FTP_MODE	Transfer mode (binary or ascii)	binary

TCP Settings

Variable	Description	Default
HIPPOX_TCP_HOST	Default TCP host	127.0.0.1
HIPPOX_TCP_PORT	Default TCP port	8888
HIPPOX_TCP_TIMEOUT	Timeout in seconds	30
HIPPOX_TCP_ENCODING	Encoding (utf8, hex, base64)	utf8

UDP Settings

Variable	Description	Default
HIPPOX_UDP_HOST	Default UDP host	127.0.0.1
HIPPOX_UDP_PORT	Default UDP port	9999
HIPPOX_UDP_TIMEOUT	Timeout in seconds	30
HIPPOX_UDP_ENCODING	Encoding (utf8, hex, base64)	utf8
HIPPOX_UDP_BROADCAST	Enable broadcast	false

PostgreSQL Settings

Variable	Description
HIPPOX_PG_HOST	PostgreSQL server hostname
HIPPOX_PG_PORT	PostgreSQL port (default 5432)
HIPPOX_PG_DATABASE	Database name
HIPPOX_PG_USERNAME	Database username
HIPPOX_PG_PASSWORD	Database password
HIPPOX_PG_POOL_SIZE	Connection pool size (default 10)
HIPPOX_PG_TIMEOUT	Query timeout in seconds (default 30)

MySQL Settings

Variable	Description
HIPPOX_MYSQL_HOST	MySQL server hostname
HIPPOX_MYSQL_PORT	MySQL port (default 3306)
HIPPOX_MYSQL_DATABASE	Database name
HIPPOX_MYSQL_USERNAME	Database username
HIPPOX_MYSQL_PASSWORD	Database password
HIPPOX_MYSQL_POOL_SIZE	Connection pool size (default 10)
HIPPOX_MYSQL_TIMEOUT	Query timeout in seconds (default 30)

Redis Settings

Variable	Description
HIPPOX_REDIS_HOST	Redis server hostname
HIPPOX_REDIS_PORT	Redis port (default 6379)
HIPPOX_REDIS_PASSWORD	Redis password
HIPPOX_REDIS_DB	Database number (default 0)
HIPPOX_REDIS_POOL_SIZE	Connection pool size (default 10)
HIPPOX_REDIS_TIMEOUT	Operation timeout in seconds (default 30)

SQLite Settings

Variable	Description
HIPPOX_SQLITE_PATH	Path to SQLite database file
HIPPOX_SQLITE_POOL_SIZE	Connection pool size (default 5)
HIPPOX_SQLITE_TIMEOUT	Query timeout in seconds (default 30)

GitHub Settings

Variable	Description	Default
HIPPOX_GITHUB_TOKEN	GitHub Personal Access Token	(empty)
HIPPOX_GITHUB_API_URL	GitHub API URL	https://api.github.com
HIPPOX_GITHUB_TIMEOUT	API timeout in seconds	30

Docker Settings

Variable	Description	Default
HIPPOX_DOCKER_HOST	Docker daemon host	unix:///var/run/docker.sock
HIPPOX_DOCKER_API_VERSION	Docker API version	(empty)
HIPPOX_DOCKER_TIMEOUT	Connection timeout in seconds	30
HIPPOX_DOCKER_TLS_VERIFY	Enable TLS verification	false
HIPPOX_DOCKER_CERT_PATH	Path to TLS certificates	(empty)

Kubernetes Settings

Variable	Description	Default
HIPPOX_K8S_KUBECONFIG	Path to kubeconfig file	(empty)
HIPPOX_K8S_CONTEXT	Kubernetes context name	(empty)
HIPPOX_K8S_NAMESPACE	Default namespace	default
HIPPOX_K8S_API_SERVER	API server URL	(empty)
HIPPOX_K8S_API_TOKEN	API bearer token	(empty)
HIPPOX_K8S_TIMEOUT	API timeout in seconds	30
HIPPOX_K8S_INSECURE	Skip TLS verification	false
HIPPOX_K8S_CA_CERT	CA certificate path	(empty)
HIPPOX_K8S_CLIENT_CERT	Client certificate path	(empty)
HIPPOX_K8S_CLIENT_KEY	Client key path	(empty)

Example .env File

Here is an example .env file for reference:

Start of .env file content:

OPENAI_API_KEY=sk-your-key-here

HIPPOX_SMTP_HOST=smtp.gmail.com HIPPOX_SMTP_PORT=587 HIPPOX_SMTP_USERNAME=your-email@gmail.com HIPPOX_SMTP_PASSWORD=your-app-password HIPPOX_SMTP_FROM=noreply@yourdomain.com

HIPPOX_GITHUB_TOKEN=ghp_your_token_here

HIPPOX_PG_HOST=localhost HIPPOX_PG_PORT=5432 HIPPOX_PG_DATABASE=myapp HIPPOX_PG_USERNAME=postgres HIPPOX_PG_PASSWORD=secret

HIPPOX_DOCKER_HOST=unix:///var/run/docker.sock

End of .env file content.

📄 Configuration Files

TOML File

Create a config.toml file with the following content:

Start of config.toml:

lang = “en”

[smtp] host = “smtp.gmail.com” port = 587 username = “your-email@gmail.com” password = “your-app-password” from = “noreply@yourdomain.com”

[github] token = “ghp_your_token_here” api_url = “https://api.github.com ” timeout = 30

[postgresql] host = “localhost” port = 5432 database = “myapp” username = “postgres” password = “secret” pool_size = 10 timeout = 30

[docker] host = “unix:///var/run/docker.sock” timeout = 30

[k8s] kubeconfig = “/path/to/kubeconfig” namespace = “default” timeout = 30

End of config.toml.

Load the TOML file using ConfigInitMethod::TomlFile with the file path.

JSON File

Create a config.json file with the following content:

Start of config.json:

( “lang”: “en”, “smtp_host”: “smtp.gmail.com”, “smtp_port”: 587, “smtp_username”: “your-email@gmail.com”, “smtp_password”: “your-app-password”, “smtp_from”: “noreply@yourdomain.com”, “github_token”: “ghp_your_token_here”, “pg_host”: “localhost”, “pg_port”: 5432, “pg_database”: “myapp”, “pg_username”: “postgres”, “pg_password”: “secret” )

End of config.json.

Load the JSON file using ConfigInitMethod::JsonFile with the file path.

💻 Programmatic Configuration

Via JSON String

Use ConfigInitMethod::ParamsJsonStr with a JSON string.

Example JSON string content:

( “lang”: “zh”, “smtp_host”: “smtp.qq.com”, “smtp_port”: 587, “telegram_bot_token”: “123456:ABC-DEF” )

Via Individual Parameters

After initializing HippoX, you can update configuration programmatically.

Call hippox.update_config with a closure that modifies the config.

Example:

hippox.update_config with a closure that sets smtp_host, smtp_username, smtp_password, and telegram_bot_token.

🔍 Checking Configuration Status

HippoX provides helper methods to check if specific integrations are configured:

Method	Returns true when…
is_smtp_configured	SMTP host, username, password, and from address are set
is_telegram_configured	Telegram bot token is set
is_dingtalk_configured	DingTalk access token is set
is_feishu_configured	Feishu webhook URL is set
is_wecom_configured	WeCom webhook URL is set
is_ftp_configured	FTP host is set
is_postgresql_configured	PostgreSQL host and database are set
is_mysql_configured	MySQL host and database are set
is_redis_configured	Redis host is set
is_sqlite_configured	SQLite path is set
is_docker_configured	Docker host is set
is_k8s_configured	Kubeconfig or API server is set
is_github_configured	GitHub token is set

Example usage:

Get config by calling get_config.

Then check each configuration using the methods above.

For example, if config.is_smtp_configured returns true, then email skills are available.

If config.is_telegram_configured returns true, then Telegram notifications are ready.

📝 Getting Current Configuration

Get the current configuration by calling get_config.

Then you can read fields like config.lang, config.smtp_host, config.docker_host.

💡

Security Note: Never commit sensitive configuration (API keys, passwords, tokens) to version control. Use environment variables or secret management tools for production deployments.