Available Integrations
Homarr supports 30+ integrations across multiple categories:Media Servers
Stream and manage your media with Plex, Jellyfin, and Emby
Download Clients
Monitor torrents and Usenet downloads
Media Organizers
Automate media management with Sonarr, Radarr, and more
Smart Home
Control Home Assistant entities and automations
System Monitoring
Track Proxmox, TrueNAS, Unraid, and system metrics
Container Registries
Monitor Docker Hub, GHCR, and Quay releases
How to Add an Integration
Step 1: Navigate to Integration Settings
From your Homarr dashboard:- Click the Settings icon in the sidebar
- Select Integrations from the menu
- Click Add Integration
Step 2: Choose Your Integration Type
Select the service you want to integrate from the available options. Each integration has specific requirements:- API Key: Most integrations require an API key or access token
- URL: The base URL where your service is accessible
- Credentials: Some services require username/password authentication
Step 3: Configure Connection Details
- API Key Based
- Username/Password
- Token Based
For services like Sonarr, Radarr, and Prowlarr:
Step 4: Test Connection
After entering your details:- Click Test Connection to verify connectivity
- If successful, click Save to add the integration
- The integration is now available for use in widgets
Common Configuration Steps
Finding API Keys
Most *arr applications (Sonarr, Radarr, etc.) store API keys in:- Web UI: Settings → General → Security → API Key
- Config File: Usually in
config.xmlin the application directory
URL Format
Use the complete base URL including protocol and port:SSL/TLS Certificates
For self-signed certificates:- Homarr supports custom certificates
- Add your certificate to Homarr’s trusted certificates
- Or disable certificate validation (not recommended for production)
Network Considerations
Docker Networking
Docker Networking
When running Homarr in Docker:
- Use container names if services are on the same Docker network
- Example:
http://sonarr:8989instead ofhttp://localhost:8989 - Ensure containers can communicate via Docker network or host networking
Reverse Proxy Setup
Reverse Proxy Setup
If using a reverse proxy:
- Use the external URL that the proxy exposes
- Ensure proper headers are forwarded (X-Forwarded-For, X-Real-IP)
- Some services may require base URL configuration
Firewall Configuration
Firewall Configuration
Ensure Homarr can reach your services:
- Check firewall rules allow traffic on required ports
- Verify services are listening on the correct network interface
- Test connectivity with
curlortelnetfrom the Homarr container
Troubleshooting Connection Issues
Connection Refused
Symptoms: “Connection refused” or “Unable to connect” errors Solutions:- Verify the service is running and accessible
- Check the URL and port number are correct
- Ensure no firewall is blocking the connection
- Try accessing the service URL directly from a browser
Authentication Failed
Symptoms: “Unauthorized” or “Authentication failed” errors Solutions:- Double-check your API key, username, or password
- Ensure there are no extra spaces in credentials
- Verify the API key hasn’t expired or been regenerated
- Check if the service requires specific authentication format
SSL/Certificate Errors
Symptoms: “Certificate verification failed” or “SSL handshake failed” Solutions:- Add self-signed certificates to Homarr’s trust store
- Verify certificate is not expired
- Check certificate matches the domain/IP you’re using
- Consider using HTTP for local network testing
Timeout Errors
Symptoms: “Request timeout” or “Connection timed out” Solutions:- Service may be slow to respond - increase timeout settings
- Check network latency between Homarr and the service
- Verify DNS resolution is working correctly
- Service may be overloaded - check its performance
Invalid Response
Symptoms: “Unexpected response” or “Parse error” Solutions:- Service version may be incompatible - check minimum requirements
- API may have changed - ensure service is up to date
- Check if reverse proxy is modifying responses
- Verify service is returning JSON (not HTML error pages)
Integration Capabilities
Different integrations provide different capabilities:| Capability | Description | Examples |
|---|---|---|
| Monitoring | Display real-time status and metrics | Active streams, download speeds, system resources |
| Control | Execute actions remotely | Pause/resume downloads, trigger automations |
| Calendar | Show scheduled events | TV show air dates, maintenance schedules |
| Media Requests | Manage media requests | Overseerr, Jellyseerr request counts |
| Releases | Track software versions | Container image updates, new releases |
| Health | System health monitoring | Node status, VM statistics, storage usage |
Not all integrations support all capabilities. Check the specific integration documentation for supported features.
Security Best Practices
- Use HTTPS: Enable SSL/TLS for services exposed outside your network
- Strong API Keys: Use long, randomly generated API keys
- Limited Permissions: Create separate API keys with minimal required permissions
- Network Isolation: Keep services on isolated networks when possible
- Regular Updates: Keep all services and Homarr updated for security patches
- Access Control: Use authentication on all services, even on local networks
Next Steps
Add Widgets
Use your integrations in dashboard widgets
Configure Boards
Organize widgets across multiple boards
Integration Management
Control user access to integrations
API Reference
Programmatic integration management