Open Home Assistant web interface
Navigate to HACS → Integrations
Click the menu button (⋮) in the top right
Select "Custom repositories"
Add the repository:
- Repository URL: https://your-gitea-domain.com/your-username/adguard-control-hub
- Category: Integration
Click "Add"

Step 2: Install Integration

In HACS → Integrations, search for "AdGuard Control Hub"
Click on the integration when found
Click "Install"
Click "Install" again to confirm
Restart Home Assistant when prompted

Step 3: Add Integration to Home Assistant

Go to Settings → Devices & Services
Click "+ Add Integration"
Search for "AdGuard Control Hub"
Click on it to start configuration

🛠️ Method 2: Manual Installation

If you prefer manual installation or don't use HACS:

Step 1: Download Files

Go to your repository's releases page
Download the latest release ZIP file
Extract the archive

Step 2: Copy Files

# Navigate to your Home Assistant config directory
cd /config

# Create custom_components directory if it doesn't exist
mkdir -p custom_components

# Copy the integration files
cp -r /path/to/extracted/custom_components/adguard_hub custom_components/

Step 3: Restart and Configure

Restart Home Assistant
Go to Settings → Devices & Services → "+ Add Integration"
Search for "AdGuard Control Hub"

⚙️ Configuration

When adding the integration, you'll need to provide:

Required Settings

Host: IP address or hostname of your AdGuard Home (e.g., 192.168.1.100)
Port: Port number, usually 3000 for the web interface
Username: Admin username for AdGuard Home
Password: Admin password for AdGuard Home

Optional Settings

SSL: Enable if your AdGuard Home uses HTTPS
Verify SSL: Disable for self-signed certificates

Example Configuration

Host: 192.168.1.100
Port: 3000
Username: admin
Password: your-secure-password
SSL: ☐ (unchecked for HTTP)
Verify SSL: ☑ (checked by default)

🔍 Verification

After successful configuration, verify the installation:

Check Entities Created

Go to Settings → Devices & Services
Find "AdGuard Control Hub" in the list
Click on it to see the device
Verify entities are created:
- switch.adguard_protection (Global protection)
- switch.adguard_client_* (Client switches)
- Various sensors for statistics

Test Basic Functionality

Go to Developer Tools → States
Find switch.adguard_protection
Try toggling it on/off
Check that the state changes

🚨 Troubleshooting

Integration Not Found

HACS Users: Ensure you added the custom repository correctly
Manual Users: Verify files are in the correct location (custom_components/adguard_hub/)
Restart Home Assistant and clear browser cache

Cannot Connect Error

# Test AdGuard Home API access manually
curl -u admin:password http://192.168.1.100:3000/control/status

Common solutions:

Verify IP address and port
Check username/password
Ensure AdGuard Home is running
Check firewall settings

No Entities Created

Check Home Assistant logs for errors
Verify AdGuard Home has clients configured
Try reloading the integration

Authentication Issues

Ensure credentials are correct in AdGuard Home web interface
Check if account has admin privileges
Try creating a new admin user specifically for Home Assistant

📊 Post-Installation Setup

Enable Debug Logging (Optional)

Add to configuration.yaml for troubleshooting:

logger:
  default: warning
  logs:
    custom_components.adguard_hub: debug

Configure Update Interval (Optional)

# Customize scan interval in configuration.yaml
adguard_hub:
  scan_interval: 30  # seconds (default: 30)

🔄 Updates

HACS Updates

HACS will automatically notify you of updates
Click "Update" when available
Restart Home Assistant after updating

Manual Updates

Download new release
Replace files in custom_components/adguard_hub/
Restart Home Assistant

✅ Installation Complete!

Your AdGuard Control Hub should now be installed and ready to use!

Next Steps:

Configuration Guide - Advanced configuration options
Dashboard Examples - Create control panels
Automation Examples - Set up automated rules

Need help? Check the Troubleshooting Guide or open an issue on the repository.