Skip to main content
Version: Next

Incus

System monitoringContainersVirtualization

Incus is a modern, secure, and powerful system container and virtual machine manager.

Incus is a modern, secure, and powerful system container and virtual machine manager. This integration allows you to monitor and control your Incus instances directly from Homarr.

Features​

  • Real-time monitoring of containers and virtual machines
  • Health monitoring widget showing cluster overview with nodes, instances, and resource usage
  • Instance control capabilities (start, stop, restart, freeze, unfreeze)
  • Dedicated management page for batch operations on instances

Widgets & Capabilities​

System Health MonitoringDisplays information showing the health and status of your system(s).
Details

Adding the integration​

You can find how to add the integration on the Integrations Management documentation page.

Secrets​

info
Incus uses mutual TLS (mTLS) for secure authentication. You'll need to provide both a client certificate and private key.
NameDescription
Client Certificate
The client certificate for mTLS authentication
Private Key
The private key for authentication
When adding secrets in Homarr, make sure to include the full certificate content including the header and footer lines:
  • Client Certificate: Include -----BEGIN CERTIFICATE----- and -----END CERTIFICATE-----
  • Private Key: Include -----BEGIN RSA PRIVATE KEY----- and -----END RSA PRIVATE KEY-----

Steps to retrieve the credentials:

  1. Option 1: Use existing Incus client certificates
    If you already have the incus CLI configured, find your certificates at:
    • ~/.config/incus/client.crt (Client certificate)
    • ~/.config/incus/client.key (Private key)
  2. Option 2: Generate new client certificates
    Generate a private key:openssl genrsa -out homarr-client.key 4096
  3. Create a Certificate Signing Request (CSR):openssl req -new -key homarr-client.key -out homarr-client.csr -subj "/CN=homarr-client"
  4. Self-sign the certificate:openssl x509 -req -days 3650 -in homarr-client.csr -signkey homarr-client.key -out homarr-client.crt
  5. Add the certificate to the Incus trust store on your Incus server:incus config trust add homarr-client.crt --name homarr
  6. Verify your certificate is trusted:incus config trust list

Network Requirements​

RequirementDetails
Default Port8443
ProtocolHTTPS with mTLS
Incus Version5.0 or later recommended

Ensure Homarr can reach your Incus server. If the API is not accessible, enable network access on the Incus server:

incus config set core.https_address :8443

Incus Tools Page​

The dedicated Incus management page provides full control over your instances. Navigate to Manage → Tools → Incus to access it.

Features​

  • Integration Selector: If you have multiple Incus integrations, select which server to manage
  • Instance Table: View all instances with name, state, type, description, and node location
  • Batch Operations: Select multiple instances and perform actions like start, stop, restart, freeze, or unfreeze
ActionDescription
StartStart selected instances
StopStop selected instances
RestartRestart selected instances
FreezePause/freeze selected instances
UnfreezeResume frozen instances

Troubleshooting​

Connection Refused / Cannot Connect​

  1. Verify the Incus server URL is correct and includes the port (default: 8443)
  2. Ensure Homarr can reach the Incus server (check firewalls)
  3. Verify Incus is listening on the network interface: 
    incus config set core.https_address :8443

403 Forbidden Error​

  1. Verify your client certificate is added to Incus trust store: 
    incus config trust list
  2. Ensure the certificate and private key match
  3. Check certificate hasn't expired: 
    openssl x509 -in client.crt -noout -dates

Certificate Errors​

  1. Ensure you're using the correct certificate format (PEM)
  2. Include the full certificate chain if required
  3. Verify the private key matches the certificate: 
    # These should produce the same output
    openssl x509 -noout -modulus -in client.crt | openssl md5
    openssl rsa -noout -modulus -in client.key | openssl md5

Widget Shows 0 for CPU/Memory​

Resource metrics require the instance to be running and may depend on:

  • For containers: cgroup metrics availability
  • For VMs: QEMU guest agent installation

For VMs, install the QEMU guest agent:

# Inside the VM
apt install qemu-guest-agent
systemctl enable --now qemu-guest-agent

Security Considerations​

  • Client certificates and private keys are stored encrypted in Homarr's database
  • Use dedicated certificates for Homarr (not your personal Incus client cert)
  • Always use HTTPS (port 8443)
  • Consider placing Homarr and Incus on the same private network

Permissions​

  • The Incus integration requires integration-interact-all permission for control operations
  • Read-only monitoring requires integration-use-all permission
  • Only admin users can access the Tools → Incus page

Further Reading​