Integrations

Integrations connect Homarr to your services, enabling widgets to display real-time data and provide interactive controls. Homarr supports over 50 integrations across categories like media management, system monitoring, network security, and more.

How Integrations Work

Integrations in Homarr provide a secure bridge between your boards and external services:

Create Integration: Configure connection details and credentials
Test Connection: Verify connectivity and authentication
Assign to Widgets: Select which widgets can use the integration
Real-Time Updates: Widgets fetch data using the integration
Permission Control: Manage who can use each integration

Integration Architecture

All integrations extend a base class providing common functionality:

// From packages/integrations/src/base/integration.ts:35
abstract class Integration {
  constructor(protected integration: IntegrationInput) {}
  
  // Base properties
  public get publicIntegration() {
    return {
      id: this.integration.id,
      name: this.integration.name,
      url: this.integration.url
    };
  }
  
  // Secret management
  protected getSecretValue(kind: IntegrationSecretKind) {
    const secret = this.integration.decryptedSecrets.find(
      secret => secret.kind === kind
    );
    if (!secret) throw new Error(`No secret of kind ${kind}`);
    return secret.value;
  }
  
  // URL helpers
  protected url(path: `/${string}`) {
    return new URL(`${this.integration.url}${path}`);
  }
  
  // Connection testing
  public async testConnectionAsync(): Promise<TestingResult> {
    // Implements secure connection testing with certificate support
  }
}

Supported Integrations

Homarr supports integrations across multiple categories:

Media Management

Media Servers (Plex, Jellyfin, Emby)

Features:

Library statistics (movies, TV shows, music)
Recently added media
Active streams
User activity

Required Secrets:

Plex: API Key (X-Plex-Token)
Jellyfin: Username & Password OR API Key
Emby: API Key

Example URL:

http://plex.example.com:32400
http://jellyfin.example.com:8096

Supported Widgets:

Media Server
Media Releases

Media Requests (Overseerr, Jellyseerr, Seerr)

Features:

Request statistics
Pending requests
Request management
Search functionality

Required Secrets:

API Key

Example URL:

http://overseerr.example.com:5055

Supported Widgets:

Media Requests (List)
Media Requests (Stats)
Search (global search integration)

Media Organization (Sonarr, Radarr, Lidarr, Readarr)

Features:

Release calendar
Missing episodes/movies
Queue management
Library statistics

Required Secrets:

API Key

Example URL:

http://sonarr.example.com:8989
http://radarr.example.com:7878

Supported Widgets:

Calendar
Media Server

Download Clients

Torrent Clients (qBittorrent, Transmission, Deluge)

Features:

Active downloads
Download/upload speeds
Queue management
Torrent controls

Required Secrets:

qBittorrent: Username & Password
Transmission: Username & Password
Deluge: Password

Example URL:

http://qbittorrent.example.com:8080
http://transmission.example.com:9091

Supported Widgets:

Downloads

Usenet Clients (SABnzbd, NZBGet)

Features:

Download queue
History
Speed statistics
Pause/resume controls

Required Secrets:

SABnzbd: API Key
NZBGet: Username & Password

Example URL:

http://sabnzbd.example.com:8080
http://nzbget.example.com:6789

Supported Widgets:

Downloads

System Monitoring

Health Monitoring (Dash., Glances, Proxmox, TrueNAS, Unraid)

Features:

CPU usage
Memory usage
Disk space
Network statistics
Temperature sensors

Required Secrets:

Dash.: None
Glances: None
Proxmox: Username, Token ID, API Key, Realm
TrueNAS: Username & Password
Unraid: API Key

Example URL:

http://dashdot.example.com:3001
http://glances.example.com:61208
https://proxmox.example.com:8006

Supported Widgets:

System Resources
System Disks
Health Monitoring

Container Management (Docker, Coolify)

Features:

Container status
Resource usage
Start/stop controls
Logs

Required Secrets:

Docker: Direct socket access (no secrets)
Coolify: API Key

Example URL:

unix:///var/run/docker.sock
http://coolify.example.com:3000

Supported Widgets:

Docker Containers
Coolify

Network & Security

DNS Filtering (Pi-hole, AdGuard Home)

Features:

Query statistics
Blocked queries
Top domains
Enable/disable filtering

Required Secrets:

Pi-hole: API Key (optional for read-only)
AdGuard Home: Username & Password

Example URL:

http://pihole.example.com
http://adguard.example.com:3000

Supported Widgets:

DNS Hole Summary
DNS Hole Controls

Firewall (OPNsense)

Features:

Firewall rules
Traffic statistics
System info
Gateway status

Required Secrets:

API Key
API Secret

Example URL:

https://opnsense.example.com

Supported Widgets:

Firewall

Network Controller (Unifi Controller)

Features:

Connected clients
Network usage
Device status
Site statistics

Required Secrets:

Username & Password

Example URL:

https://unifi.example.com:8443

Supported Widgets:

Network Controller Summary
Network Controller Status

Development & Releases

Release Providers (GitHub, GitLab, Docker Hub, NPM)

Features:

Latest releases
Release notes
Download counts
Version tracking

Required Secrets:

GitHub: None (public) OR Personal Access Token OR GitHub App credentials
GitLab: None (public) OR Personal Access Token
Docker Hub: None (public) OR Username & Personal Access Token
NPM: None

Example URL:

https://api.github.com (default)
https://gitlab.com (default)
https://hub.docker.com (default)
https://registry.npmjs.org (default)

Supported Widgets:

Releases

Smart Home

Home Assistant

Features:

Entity states
Service calls
Automation triggers
Calendar events

Required Secrets:

API Key (Long-Lived Access Token)

Example URL:

http://homeassistant.example.com:8123

Supported Widgets:

Smart Home Entity State
Smart Home Execute Automation
Calendar

Other Services

Additional Integrations

Prowlarr: Indexer manager statistics
Tdarr: Media transcoding status
Nextcloud: Calendar integration
ntfy: Notification delivery
iCal: Calendar feeds
Minecraft: Server status
OpenMediaVault: NAS management

Adding Integrations

Step-by-Step Setup

Navigate to Integrations

Go to Settings → Integrations in the Homarr interface.

Select Integration Type

Click Add Integration and select the service type from the list.Integrations are organized by category:

Media Services
Download Clients
System Monitoring
Network & Security
And more…

Configure Basic Settings

Enter the basic connection information:

Name: Descriptive name for this integration (e.g., “Main Plex Server”)
URL: Base URL of the service (e.g., http://plex.example.com:32400)
External URL (optional): Public URL if different from internal

Add Secrets

Enter authentication credentials based on the integration type:

API Key: Single token for authentication
Username & Password: Credentials for login
Multiple Options: Some integrations support alternative auth methods

Secrets are encrypted at rest and never exposed in the UI after creation.

Test Connection

Click Test Connection to verify:

Network connectivity
Authentication validity
SSL/TLS certificate (if HTTPS)
API availability

See Testing Connections for troubleshooting.

Save Integration

Click Save to create the integration. It’s now available for use in widgets.

Integration Secrets

Homarr supports multiple secret types:

// From packages/definitions/src/integration.ts:6
const integrationSecretKindObject = {
  apiKey: { isPublic: false, multiline: false },
  username: { isPublic: true, multiline: false },
  password: { isPublic: false, multiline: false },
  tokenId: { isPublic: true, multiline: false },
  realm: { isPublic: true, multiline: false },
  personalAccessToken: { isPublic: false, multiline: false },
  topic: { isPublic: true, multiline: false },
  opnsenseApiKey: { isPublic: false, multiline: false },
  opnsenseApiSecret: { isPublic: false, multiline: false },
  url: { isPublic: false, multiline: false },
  privateKey: { isPublic: false, multiline: true },
  githubAppId: { isPublic: true, multiline: false },
  githubInstallationId: { isPublic: true, multiline: false }
};

Secret Properties:

isPublic: Whether the secret value is visible to users with view access
multiline: Whether the input should be a textarea (e.g., for private keys)

Non-public secrets are encrypted and never sent to the client. Only the server has access to decrypt them.

Testing Connections

Homarr includes comprehensive connection testing:

Test Process

// From packages/integrations/src/base/test-connection/test-connection-service.ts:38
class TestConnectionService {
  async handleAsync(testingCallbackAsync) {
    // Load trusted certificates
    const ca = await getAllTrustedCertificatesAsync();
    const checkServerIdentity = createCustomCheckServerIdentity(
      await getTrustedCertificateHostnamesAsync()
    );
    
    // Test connection with custom certificate support
    const result = await testingCallbackAsync({ ca, checkServerIdentity })
      .catch(error => {
        // Handle certificate errors specially
        if (error.cause?.type === "certificate") {
          return this.fetchCertificateAsync().then(cert => 
            TestConnectionError.CertificateResult(error.cause, cert)
          );
        }
        return TestConnectionError.FromIntegrationError(error);
      });
    
    return result;
  }
}

Test Results

Success
Connection Failed
Authentication Failed
Certificate Error

✅ Connection successful

Network connectivity verified
Authentication accepted
API responding correctly
Integration ready to use

Custom Certificates

For self-signed or custom CA certificates:

Navigate to Settings → Certificates
Upload CA certificate or server certificate
Assign to hostname
Test connection again

Homarr will use the custom certificate for validation.

Integration Secrets Management

Secret Storage

Secrets are encrypted at rest using AES-256-GCM:

Encryption: Secrets encrypted with master key
Storage: Encrypted values stored in database
Decryption: Only decrypted when needed by server
Never Exposed: Secrets never sent to client

Secret Rotation

Regularly rotate integration secrets:

Generate new API key/credentials in service
Edit integration in Homarr
Update secret values
Test connection
Save changes
Revoke old credentials in service

Widgets automatically use updated credentials on next data fetch.

Secret Permissions

Control who can view and manage integration secrets:

View: See integration configuration (public secrets visible)
Edit: Update URL and secrets
Full: Complete control including deletion

Using Integrations in Widgets

Once configured, integrations can be selected when adding widgets:

Add widget to board (edit mode)
Select widget type
Choose integration(s) from dropdown
Configure widget options
Save widget

Multiple Integrations

Some widgets support multiple integrations:

// Example: Calendar widget with multiple Sonarr/Radarr instances
integrationIds: [
  "sonarr-1",
  "sonarr-2",
  "radarr-1"
]

The widget combines data from all selected integrations.

Integration Requirements

// From widget definition (packages/widgets/src/calendar/index.ts:34)
supportedIntegrations: getIntegrationKindsByCategory("calendar"),
integrationsRequired: false

supportedIntegrations: List of compatible integration types
integrationsRequired: Whether widget requires at least one integration

Integration Permissions

Control which users can access integrations:

Permission Levels

View Access

Users can:

See integration name and URL
Use integration in widgets
View data from integration

Cannot:

Edit configuration
View secrets
Delete integration

Full Access

Users can:

Everything in View access
Edit configuration
Update secrets
Delete integration
Manage permissions

Granting Access

Open integration settings
Click Permissions
Add users or groups
Select permission level
Save changes

Permission Inheritance

Integration permissions work with board permissions:

Widget shows data only if user has integration view access
Board permissions don’t grant integration access
Both board AND integration access required to view widget data

Integration Categories

// From packages/definitions/src/integration.ts:404
const integrationCategories = [
  "dnsHole",
  "mediaService",
  "calendar",
  "mediaSearch",
  "mediaRelease",
  "mediaRequest",
  "downloadClient",
  "usenet",
  "torrent",
  "miscellaneous",
  "smartHomeServer",
  "indexerManager",
  "healthMonitoring",
  "search",
  "mediaTranscoding",
  "networkController",
  "releasesProvider",
  "notifications",
  "firewall"
];

Categories help organize integrations and determine widget compatibility.

Advanced Features

External URLs

Some integrations support separate internal and external URLs:

Internal URL: Used by Homarr server to fetch data
External URL: Used by browser for direct links

Use case: Service behind reverse proxy with different internal/external addresses.

Custom Headers

Some integrations support custom HTTP headers:

Authentication headers
Custom user agents
Proxy headers

Configure in integration settings under Advanced.

Connection Timeouts

Configure request timeouts for slow services:

Default: 30 seconds
Configurable per integration
Prevents hanging requests

Troubleshooting

Integration not appearing in widget

Widget shows no data

SSL/TLS errors

Check:

Certificate is valid
Hostname matches certificate
CA is trusted

Solution:

Add custom certificate
Use HTTP if acceptable
Fix certificate on service
Disable certificate validation (not recommended)

Slow widget updates

Best Practices

Security

Use HTTPS when possible
Rotate secrets regularly
Grant minimal required permissions
Use service accounts, not personal accounts
Monitor integration usage

Organization

Use descriptive integration names
Group similar integrations
Document custom configurations
Tag integrations by environment (prod/test)
Archive unused integrations

Performance

Test connections before deploying
Monitor response times
Use internal URLs when possible
Limit concurrent requests
Cache where appropriate

Maintenance

Review integrations quarterly
Update URLs when services move
Remove unused integrations
Test after service updates
Keep documentation current

Next Steps

Add Widgets

Use your integrations in widgets

Configure Permissions

Set up user access to integrations

API Documentation

Integration API reference

Troubleshooting

Common integration issues

Get Started

Core Features

Configuration

Guides

​How Integrations Work

​Integration Architecture

​Supported Integrations

​Media Management

​Download Clients

​System Monitoring

​Network & Security

​Development & Releases

​Smart Home

​Other Services

​Adding Integrations

​Step-by-Step Setup

​Integration Secrets

​Testing Connections

​Test Process

​Test Results

​Custom Certificates

​Integration Secrets Management

​Secret Storage

​Secret Rotation

​Secret Permissions

​Using Integrations in Widgets

​Widget Integration Selection

​Multiple Integrations

​Integration Requirements

​Integration Permissions

​Permission Levels

View Access

Full Access

​Granting Access

​Permission Inheritance

​Integration Categories

​Advanced Features

​External URLs

​Custom Headers

​Connection Timeouts

​Troubleshooting

​Best Practices

Security

Organization

Performance

Maintenance

​Next Steps

Add Widgets

Configure Permissions

API Documentation

Troubleshooting

Build docs developers (and LLMs) love

How Integrations Work

Integration Architecture

Supported Integrations

Media Management

Download Clients

System Monitoring

Network & Security

Development & Releases

Smart Home

Other Services

Adding Integrations

Step-by-Step Setup

Integration Secrets

Testing Connections

Test Process

Test Results

Custom Certificates

Integration Secrets Management

Secret Storage

Secret Rotation

Secret Permissions

Using Integrations in Widgets

Widget Integration Selection

Multiple Integrations

Integration Requirements

Integration Permissions

Permission Levels

Granting Access

Permission Inheritance

Integration Categories

Advanced Features

External URLs

Custom Headers

Connection Timeouts

Troubleshooting

Best Practices

Next Steps