ScottiBYTE Incus Backup

Current release: v1.1.0

ScottiBYTE Incus Backup is a centralized backup, restore, and scheduled backup platform for Incus containers and Incus virtual machines across every remote available to an Incus client.

The application is designed to run as a lightweight client-only control node using Docker Compose. It leverages the native Incus client and existing trust relationships already configured on the Docker host.

Unlike traditional backup systems, ScottiBYTE Incus Backup does not require an Incus server locally. The container securely mounts the host Incus client configuration read-only and communicates directly with remote Incus servers using the official Incus CLI.

The result is a clean, lightweight, multi-remote backup solution with no database dependencies and no complicated infrastructure requirements.

Dashboard Overview

The ScottiBYTE Incus Backup dashboard provides:

Multi-remote Incus backup management
Centralized container and VM visibility
One-click backup exports
Persistent scheduled backups
Bulk scheduling for visible or filtered instances
Inline schedule editing
Inline restore operations
Backup age visualization
Backup protection tracking
Live or Stop+Restart backup modes
IncusBackup self-protection when backing up the app container
Remote health monitoring
Recent activity logging
Upload/import support for external backups
Large inventory navigation with row highlighting, keyboard movement, floating headers, and scroll-to-top support
Lightweight Docker deployment
Native Incus client integration
Secure read-only trust mounting
No database required

Features

Discover Incus containers and virtual machines across configured remotes
Export backups as compressed .tar.gz
Restore backups as:
- Original instance
- Cloned instance
Upload and import local .tar.gz backup files
Persistent scheduled backups
Per-instance schedule editing
Bulk schedule assignment for visible or filtered instances
Scheduled backup retention
Optional missed-run handling on startup
Scheduled backup dashboard count
Backup protection indicators
Backup age visualization:
- 🟢 Green = backed up today
- 🟡 Yellow = 1–7 days old
- 🟠 Orange = stale
- 🔴 Red = no backups
Backup modes:
- Live
- Stop + Restart
IncusBackup self-protection to force Live mode when backing up the backup application container
Inline backup job tracking
Recent activity feed
Multi-remote Incus support
Docker Compose deployment
Watchtower-compatible labels
Automatic remote health monitoring
Compact dashboard mode
Row highlighting and keyboard navigation for large instance inventories
Floating Containers table header while scrolling
Scroll-to-top button for long instance lists
Client-only architecture
Secure trust mounting
Native Incus CLI support

Security Model

This application intentionally operates as an Incus client only.

The Docker container does not store or generate Incus trust credentials internally.

Instead, the existing Incus client configuration from the Docker host is mounted read-only into the container:

${HOME}/.config/incus:/incus-client:ro

This ensures:

Trust credentials remain on the Docker host
Docker Hub images remain safe to publish
Remote trust relationships stay externally managed
The container cannot modify Incus trust data

1. Install the Incus Client

The Docker host must have the Incus client installed before trust relationships can be configured.

Ubuntu example:

sudo apt update
sudo apt install -y incus-client

Verify:

incus version

2. Enable HTTPS API Access on Incus Servers

Run this on every Incus server you want ScottiBYTE Incus Backup to manage:

incus config set core.https_address :8443

Verify:

ss -ltnp | grep 8443

3. Create an Incus Trust Token

On the remote Incus server:

incus config trust add IncusBackup

Copy the generated trust token.

4. Add Remote Incus Servers

Run these commands on the Docker host.

Example remote:

incus remote add vmsmist https://vmsmist:8443 --accept-certificate

Paste the trust token when prompted.

Verify connectivity:

incus remote list

Verify instances are visible:

incus list vmsmist:

Repeat for every Incus server you want ScottiBYTE Incus Backup to manage.

Examples:

incus remote add vmsstorm https://vmsstorm:8443 --accept-certificate
incus remote add vmsrain https://vmsrain:8443 --accept-certificate
incus remote add mondo-2 https://mondo-2:8443 --accept-certificate

5. Create the Application Directory

mkdir -p ~/incusbackup
cd ~/incusbackup

mkdir -p backups
mkdir -p uploads

6. Create docker-compose.yml

Create:

nano docker-compose.yml

Paste:

services:
  incusbackup:
    image: scottibyte/incusbackup:latest
    container_name: incusbackup
    restart: unless-stopped

    ports:
      - "3030:3030"

    environment:
      PORT: "3030"
      INCUS_CONF: /incus-client
      INCUS_BACKUP_DIR: /app/backups
      INCUS_COMPLETED_JOB_TTL_MS: "180000"

    volumes:
      - ./backups:/app/backups
      - ./uploads:/app/uploads

      # Read-only host Incus trust mount
      - ${HOME}/.config/incus:/incus-client:ro

    security_opt:
      - no-new-privileges:true

    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:3030"]
      interval: 30s
      timeout: 10s
      retries: 3

    labels:
      - "com.centurylinklabs.watchtower.enable=true"

7. Start ScottiBYTE Incus Backup

docker compose up -d

View logs:

docker logs -f incusbackup

You should see:

ScottiBYTE Incus Backup running at http://0.0.0.0:3030
Backup directory: /app/backups
Completed jobs auto-hide after 180 seconds.
Scheduled backup engine active. Interval 60 seconds. Concurrency 1.

8. Verify Incus Access Inside the Container

Verify the Incus CLI exists:

docker exec -it incusbackup which incus

Verify remotes:

docker exec -it incusbackup incus remote list

Verify instances:

docker exec -it incusbackup incus list vmsmist:

Replace vmsmist with one of your configured remotes.

9. Open the Dashboard

Open a browser and go to:

http://YOUR-SERVER-IP:3030

Example:

http://172.16.2.247:3030

Scheduled Backups

Version 1.1.0 adds a built-in scheduled backup engine.

Schedules are stored persistently in:

~/incusbackup/backups/settings.json

The scheduler runs inside the Incus Backup application container and uses the same backup engine as manual exports.

Supported schedule types:

Off
Hourly
Daily
Weekly
Monthly

The dashboard supports:

Per-instance schedule editing
Bulk scheduling of currently visible or filtered instances
Scheduled backup retention
Optional missed-run handling on startup
A scheduled backup count on the status dashboard
Inline schedule summaries in the Containers table

Bulk scheduling is especially useful when filtering by remote, instance type, protection state, or backup age.

IncusBackup Self-Protection

When the Incus Backup application backs up its own IncusBackup container, it is automatically protected.

The app forces its own backup mode to:

Live - self protected

This prevents the backup process from stopping the container that is running the backup application.

Other containers and virtual machines can still use either Live or Stop + Restart mode.

Backup Modes

Live Backup

Exports the instance while it remains running.

Recommended for:

General workloads
Low-risk services
Convenience backups

Stop + Restart Backup

Gracefully stops the instance before backup and restarts it afterward.

Recommended for:

Databases
Stateful applications
Critical production workloads
Consistency-sensitive backups

During Stop + Restart mode the dashboard temporarily displays:

Backing Up

instead of Running or Stopped so the UI accurately reflects backup activity.

Backup Age Visualization

Protection status is color coded:

Color	Meaning
🟢 Green	Backed up today
🟡 Yellow	1–7 days old
🟠 Orange	Backup stale
🔴 Red	No backups

Restore Options

Expand a container or VM row to view backups.

Restore Original

Restores using the original instance name.

Disabled automatically if the original instance already exists.

Restore Clone

Restores using a generated safe clone name such as:

container-restored

or:

container-restored-2

Upload External Backups

The dashboard supports uploading external .tar.gz Incus exports.

Workflow:

Choose backup file
Select destination remote
Enter restore name
Upload and import

Uploaded files are staged in:

~/incusbackup/uploads

Backup Storage Locations

Docker host paths:

~/incusbackup/backups
~/incusbackup/uploads

Container paths:

/app/backups
/app/uploads

Incus trust mount:

/incus-client

Updating ScottiBYTE Incus Backup

From the ~/incusbackup directory:

docker compose pull
docker compose up -d

View logs:

docker logs -f incusbackup

Watchtower Support

The compose file includes:

labels:
  - "com.centurylinklabs.watchtower.enable=true"

This allows automated updates using Watchtower if desired.

Troubleshooting

No Containers Displayed

Verify remotes on the Docker host:

incus remote list

Verify remotes inside the container:

docker exec -it incusbackup incus remote list

Incus Client Missing Inside Container

Verify:

docker exec -it incusbackup which incus

Container Cannot Access Trust Configuration

Verify mount:

docker exec -it incusbackup ls -la /incus-client

Remote Unreachable

Verify connectivity:

incus list vmsmist:

Check remote server API:

ss -ltnp | grep 8443

Dashboard Will Not Load

Verify container:

docker ps

Check logs:

docker logs -f incusbackup

Verify port:

ss -ltnp | grep 3030

Port Conflict

Edit:

ports:
  - "3030:3030"

Example alternative:

ports:
  - "3031:3030"

Restart:

docker compose up -d

Access:

http://YOUR-SERVER-IP:3031

Important Notes

Test restores regularly
Stop + Restart mode is safest for databases
Live backup mode is faster but may not guarantee perfect write consistency
Scheduled backups use the same export engine as manual backups
Backup files can consume significant storage
This application can stop and restart containers during backup operations
The IncusBackup application container is self-protected and forced to Live mode
Remote Incus trust is fully controlled by the Docker host Incus client

Docker Hub

scottibyte/incusbackup:latest
scottibyte/incusbackup:1.1.0

🌐 Community

Community Support

Need help with Incus Backup, Docker deployment, Incus profile management, container creation, or ScottiBYTE utilities?

Join the ScottiBYTE Rocket.Chat community:

Join ScottiBYTE Rocket.Chat

New users can start in #general. From there, you can find other ScottiBYTE project channels and community discussions.

For bugs and feature requests, please continue to use GitHub Issues. For quick questions and community discussion, use Rocket.Chat.

Name		Name	Last commit message	Last commit date
images		images
.dockerignore		.dockerignore
.gitignore		.gitignore
Dockerfile		Dockerfile
LICENSE		LICENSE
README.md		README.md
docker-compose.yml		docker-compose.yml
package-lock.json		package-lock.json
package.json		package.json
server.js		server.js

Latest commit

History

Folders and files

Repository files navigation

ScottiBYTE Incus Backup

Dashboard Overview

Features

Security Model

1. Install the Incus Client

2. Enable HTTPS API Access on Incus Servers

3. Create an Incus Trust Token

4. Add Remote Incus Servers

5. Create the Application Directory

6. Create docker-compose.yml

7. Start ScottiBYTE Incus Backup

8. Verify Incus Access Inside the Container

9. Open the Dashboard

Scheduled Backups

IncusBackup Self-Protection

Backup Modes

Live Backup

Stop + Restart Backup

Backup Age Visualization

Restore Options

Restore Original

Restore Clone

Upload External Backups

Backup Storage Locations

Updating ScottiBYTE Incus Backup

Watchtower Support

Troubleshooting

No Containers Displayed

Incus Client Missing Inside Container

Container Cannot Access Trust Configuration

Remote Unreachable

Dashboard Will Not Load

Port Conflict

Important Notes

Docker Hub

🌐 Community

Community Support

About

Topics

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages