incusd-client

High-level Python client for incusd, built on pyincusd.

Provides an OOP abstraction over the entire Incus REST API — instances, storage, networking, clustering, images, and more.

Install

pip install pyincusd

This library depends on pyincusd for the underlying API client and Unix socket transport.

Usage

from incusd.instances import Instance
from incusd.storage import StoragePool
from incusd.networks import Network
from incusd.cluster import Cluster

# Instances
i = Instance("my-vm")
i.launch("images:ubuntu/24.04/cloud", vm=True)
i.state                     # "Running"
i.metadata                  # full instance details
i.console.open("vga")       # ConsoleSession (extends Operation)
i.exec(["bash"])            # ExecSession (extends Operation)
i.file("/etc/hostname").read()  # io.RawIOBase
i.root_volume               # StorageVolume
i.delete()

# Storage
pool = StoragePool("default")
pool.volumes                # list[StorageVolume]
pool.create_volume("data")

# Networks
net = Network("incusbr0")
net.type                    # "bridge"
net.forwards                # list[NetworkForward]
net.load_balancers          # list[NetworkLoadBalancer]
net.peers                   # list[NetworkPeer]

# Cluster
cl = Cluster()
cl.enabled                  # bool
cl.members                  # list[ClusterMember]
cl.enable()

Architecture

• pyincusd — auto-generated typed API client (low-level, CI-maintained)
• incusd-client (this repo) — hand-crafted OOP layer on top (high-level, human-maintained)

Every class wraps one or more pyincusd API classes:

Class	Wraps
Instance	InstancesApi
StoragePool	StorageApi
Network	NetworksApi
Cluster / ClusterMember	ClusterApi
StoreImage / AliasImage / InstanceImage	ImagesApi
Profile	ProfilesApi
Project	ProjectsApi
Certificate	CertificatesApi
Operation / ConsoleSession / ExecSession	OperationsApi
Server	ServerApi
Warning	WarningsApi

Sub-resources follow the parent → child pattern:

• Instance.snapshots → list[Snapshot]
• Instance.backups → list[Backup]
• Instance.file("/path") → File (extends io.RawIOBase)
• Network.forwards → list[NetworkForward]
• StoragePool.volumes → list[StorageVolume]
• StoragePool.buckets → list[StorageBucket]

Cross-resource references are resolved automatically:

• StorageVolume.used_by → [Instance("foo")]
• Instance.location → ClusterMember("node1")
• Instance.profiles → [Profile("default")]

API Coverage

22/22 Incus REST APIs fully covered. See the source files for complete class documentation.

License

Apache-2.0