Skip to content

Remotes, migration, and backup workflows

Remotes let one Incus client manage multiple Incus servers and image servers.

Official docs:

  • Remotes: https://linuxcontainers.org/incus/docs/main/remotes/
  • Backup and restore: https://linuxcontainers.org/incus/docs/main/backup/

List remotes

incus remote list

Common remotes:

  • local: - your local Incus server;
  • images: - public Linux Containers image server;
  • custom names for your own Incus hosts.

Add a remote with a trust token

On the server, expose the HTTPS API only on a trusted management network and create a one-time trust token for the client:

incus config set core.https_address=:8443
incus config trust add workstation-01

On the client, use the generated token:

incus remote add lab <trust-token>
incus list lab:

Treat trust tokens as short-lived secrets. If the server is behind NAT, add the remote with its externally reachable address instead and provide the token when prompted.

Work with remote instances

incus list lab:
incus launch images:debian/13 lab:web-01
incus shell lab:web-01
incus stop lab:web-01

Copy instances between hosts

Copy while keeping source:

incus copy web-01 lab:web-01

Move and remove source:

incus move web-01 lab:web-01

Copy with snapshots:

incus copy web-01 lab:web-01 --instance-only=false

Export/import backup

incus export web-01 web-01-$(date +%Y%m%d).tar.gz
incus import web-01-20260101.tar.gz

Test restore on another host:

incus import web-01-20260101.tar.gz restored-web-01
incus start restored-web-01
incus info restored-web-01

Scheduled snapshots and off-host backups

Snapshots are useful rollback points, not complete backups, because they live in the same storage pool as the source. Set expiry for routine snapshots, then copy both the instance and every attached custom volume to a separate Incus host.

incus config set app-01 snapshots.schedule=@daily snapshots.expiry=7d
incus storage volume set default app-data snapshots.schedule=@daily snapshots.expiry=7d
incus copy app-01 backup-host:app-01
incus storage volume copy default/app-data backup-host:default/app-data

An instance backup does not include custom storage volumes. Test the copied instance and volume on the backup host before relying on the workflow:

incus start backup-host:app-01
incus info backup-host:app-01
incus storage volume show backup-host:default/app-data

Backup checklist

For each important instance, document:

  • instance name;
  • project;
  • profiles;
  • storage pool;
  • attached custom volumes;
  • static IPs and proxy devices;
  • backup command;
  • custom-volume backup command;
  • restore test date.

Migration checklist

Before migration:

incus info app-01
incus config show app-01 --expanded
incus snapshot app-01 pre-migration

Copy to target:

incus copy app-01 new-host:app-01

Verify target:

incus start new-host:app-01
incus list new-host:app-01
incus info new-host:app-01

Only delete the old instance after testing application-level behavior.