Project files

HomeBot API Key Configuration Guide

This document explains how to securely manage various API keys in the HomeBot project.

🔐 Supported Key Types

📁 Configuration Files

Recommended method: .env.local file

Create a .env.local file in the project's software/ directory:

cd software
cp .env.example .env.local
# Edit .env.local to enter your keys

File Format

# Volcano Engine TTS Configuration
VOLCANO_APPID=your_appid_here
VOLCANO_ACCESS_TOKEN=your_token_here

# DeepSeek LLM Configuration
DEEPSEEK_API_KEY=sk-your_api_key_here

# Image Understanding Configuration (Optional, leave blank to use DeepSeek)
# VISION_API_KEY=your_vision_api_key

🚀 Quick Configuration

Method 1: Using the Configuration Wizard (Recommended)

cd software
python tools/setup_secrets.py

Follow the prompts to enter the keys, and the .env.local file will be created automatically.

Method 2: Manual Creation

1. Copy the template file:

   cp software/.env.example software/.env.local
   

2. Edit .env.local and fill in the keys obtained from each platform

3. Verify the configuration:

   python tools/check_config.py
   

Method 3: System Environment Variables

Set the variables in system environment variables (suitable for CI/CD or Docker):

# Linux/macOS
export VOLCANO_APPID=your_appid
export VOLCANO_ACCESS_TOKEN=your_token
export DEEPSEEK_API_KEY=sk-your_key

# Windows PowerShell
$env:VOLCANO_APPID="your_appid"
$env:DEEPSEEK_API_KEY="sk-your_key"

🔍 Secret Key Acquisition Guide

Volcano Engine TTS

1. Visit Volcano Engine Console (opens in a new tab)
2. Go to "Speech Recognition" → "Speech Technology"
3. Create an application to obtain the AppID and Access Token

DeepSeek LLM

1. Visit the DeepSeek Open Platform (opens in a new tab)
2. Go to the "API Keys" page
3. Create a new API Key

✅ Configuration Check

Run the following command to check the configuration status:

cd software
python tools/check_config.py

Sample output:

==================================================
HomeBot API Key Configuration Status
==================================================

🎤 Volcano Engine TTS: ✅ Configured
   AppID: 870360...
   Access Token: BBsO5****-S-

🤖 DeepSeek LLM: ✅ Configured
   API Key: sk-523****afef
   Model: deepseek-chat

👁️  Image Understanding: ✅ Configured
   Provider: deepseek
   API Key: sk-523****afef

📄 Configuration file path: /path/to/homebot/software/.env.local
==================================================

🛡️ Security Considerations

⚠️ Never do the following

1. Do not commit .env.local to Git

   • It is already added to .gitignore, but please confirm it has not been forcibly added

2. Do not hardcode keys in your code

   # ❌ Incorrect
   API_KEY = "sk-actual-key-here"
   
   # ✅ Correct
   from configs import get_secrets
   api_key = get_secrets().llm.api_key
   

3. Do not share logs containing keys

   • Using check_secrets() will automatically desensitize the display

✅ Security Best Practices

1. Rotate API Keys regularly
2. Use different keys for different environments (development/testing/production)
3. Restrict the scope of API Key permissions
4. Monitor API usage, disable keys immediately if anomalies are detected

🔧 Developer Notes

Using Secrets in Code

from configs import get_config, get_secrets

# Method 1: Get via config object (recommended)
config = get_config()
api_key = config.llm.api_key  # Automatically loads from environment variables

# Method 2: Directly access the secrets module
secrets = get_secrets()
token = secrets.tts.access_token

Forced Secret Verification

Force-check secrets at service startup:

from configs.secrets import require_secrets

def __init__(self):
    require_secrets("tts")  # Prints help and exits if not configured
    # ...

Reload Configuration

from configs import reload_secrets

# Reload if the user modifies .env.local
reload_secrets()

📂 File Structure

software/
├── .env.example          # Configuration template (can be committed to git)
├── .env.local            # Local configuration (gitignored)
├── .env.development      # Development environment configuration (optional)
├── .env.production       # Production environment configuration (optional)
└── src/
    └── configs/
        ├── __init__.py    # Unified export
        ├── config.py      # Main configuration
        └── secrets.py     # Secret management

❓ Frequently Asked Questions

Q: Why does the program run even when .env.local does not exist?

A: The program attempts to read the key from environment variables. If none are set, it will only report an error when the key is actually required.

Q: Can it be used in Docker?

A: Yes, pass the environment variable using the -e parameter:

docker run -e DEEPSEEK_API_KEY=sk-xxx homebot

Q: How do I use different configurations for different environments?

A: Create .env.development or .env.production, or set the ENV environment variable to switch between them.

Q: Do image understanding and LLM use the same API key?

A: By default, if DeepSeek is used as the Vision Provider, the LLM's API key is reused. To configure them independently, set VISION_API_KEY.

If you have any questions, please refer to the project README or submit an Issue.