Extensions

incus-compose groups its commands into two categories, and --help shows the split. The compose category is the docker compose verbs. Everything here is in the extensions category: it has no docker compose counterpart, or it does the job better than the counterpart does.

Command	Does
`backup`	Snapshot project data volumes into a backup project
`list`	List resources - the one to reach for over `ps`
`port-forward`	Forward a local TCP port into an instance
`incus`	Run an `incus` command in the project context
`healthd`	Manage the ic-healthd sidecar
`self-update`	Update incus-compose to the latest release

list

List project resources. This is the one to reach for: ps is the docker compose-compatible variant and reports instances only, where list reports the project as a whole and knows about the ic-healthd sidecar.

incus-compose list [SERVICE...]

Option	Description
`--format`	table (default), yaml, json
`--no-healthd`	Exclude the ic-healthd sidecar from the output

The IMAGE column shows the compose image for each service. The ic-healthd sidecar is listed by default; its image is resolved from the instance's stored metadata. Pass --no-healthd to omit it.

Changed in 1.0.0-rc.1: healthd is listed by default.

port-forward

Forward a local TCP port into an instance, published or not.

incus-compose port-forward [options] SERVICE TARGET_PORT [LISTEN_PORT]

Option	Description
`--index`	Index of the container if service has multiple replicas (default: 0)
`--dry-run`	Print the `incus` command instead of running it

This has no docker compose counterpart. It runs a local TCP listener and forwards every connection made to it into the instance, so it reaches a port that was never published - a database you did not want on the host, for instance. LISTEN_PORT defaults to TARGET_PORT, and either port can be prefixed with an address to use, IPv6 in square brackets:

incus-compose port-forward db 5432          # 127.0.0.1:5432 -> 5432 in db
incus-compose port-forward db 5432 15432    # 127.0.0.1:15432 -> 5432 in db
incus-compose port-forward db 5432 0.0.0.0:15432

Like exec, it shells out to your local incus client and targets the instance via INCUS_PROJECT. It needs Incus 7.3, or 7.0.1 LTS.

Since: v1.3.0

incus

Run any incus command scoped to the current compose project. All flags and arguments are passed through verbatim; only INCUS_PROJECT is injected.

incus-compose incus COMMAND [ARGS...]

Examples:

incus-compose incus list                        # list instances in this project
incus-compose incus config show web-1           # show instance config
incus-compose incus config set web-1 limits.memory 512MiB
incus-compose incus exec web-1 -- bash

Equivalent to INCUS_PROJECT=<project> incus COMMAND [ARGS...].

healthd

Manage the ic-healthd sidecar. See Health Checking for full details.

incus-compose healthd <subcommand>

Subcommand	Description
`logs [--follow]`	Stream the ic-healthd container log
`reload`	Send SIGHUP to the ic-healthd process
`restart`	Restart the ic-healthd container
`status`	Print the shared daemon's health status key
`up`	Create the sidecar, or replace one running an older image
`down [--force]`	Stop and remove the sidecar

Each follows the project's scope, so in a global-scope project they act on the shared daemon in the Incus incus-compose project. With no compose file present they all act on the shared daemon directly: healthd up creates one, the rest fail with no ic-healthd is running when there is none. healthd down asks first when other projects rely on that daemon; --force skips the question and is required without a terminal.

Since: v1.3.0: healthd status.

healthd up also accepts --image, --binary, --incus, --network, --scope, --pull and --timeout. See Health Checking - Scope and Network Configuration.

self-update

Update incus-compose to the latest release from GitHub.

incus-compose self-update

Option	Description
`--draft`	Also consider draft releases when checking for updates (works only with GITHUB_TOKEN set)
`--pre-release`	Also consider pre-releases when checking for updates

This command is only available when both conditions are met:

The binary was built with a release version (not latest / development builds)
The binary file is writable by the current user

When available, self-update checks the lxc/incus-compose GitHub releases for a newer version matching the current OS and architecture. If a newer version is found, the binary is replaced in-place. If you are already on the latest version, no action is taken.

Changed v1.0.0: the --drafts option has been added

Environment variables

Flags given on the command line win. See Environment Variables for the resolution order and the flags that deliberately have none.

Command	Variable	Flag	Description
`list`	`INCUS_COMPOSE_LIST_FORMAT`	`--format`	Output format: `table`, `yaml` or `json`
`list`	`INCUS_COMPOSE_NO_HEALTHD`	`--no-healthd`	Don't list the healthd sidecar
`port-forward`	`INCUS_COMPOSE_PORT_FORWARD_INDEX`	`--index`	Replica index if service is scaled
`healthd up`	`INCUS_COMPOSE_HEALTHD_IMAGE`	`--image`	Healthd OCI image
`healthd up`	`INCUS_COMPOSE_HEALTHD_BINARY`	`--binary`	Local ic-healthd binary path
`healthd up`	`INCUS_COMPOSE_HEALTHD_INCUS`	`--incus`	Incus API URL for the sidecar
`healthd up`	`INCUS_COMPOSE_HEALTHD_NETWORK`	`--network`	Network for the sidecar (project scope)
`healthd up`	`INCUS_COMPOSE_HEALTHD_SCOPE`	`--scope`	`global` or `project`
`healthd up`	`INCUS_COMPOSE_HEALTHD_PULL`	`--pull`	Pull policy
`healthd up`	`INCUS_COMPOSE_HEALTHD_TIMEOUT`	`--timeout`	Timeout for stopping
`healthd down`	`INCUS_COMPOSE_HEALTHD_IMAGE`	`--image`	Healthd OCI image
`healthd down`	`INCUS_COMPOSE_HEALTHD_DOWN_FORCE`	`--force`	Stop a shared daemon without asking
`healthd down`	`INCUS_COMPOSE_HEALTHD_TIMEOUT`	`--timeout`	Timeout for stopping
`healthd logs`	`INCUS_COMPOSE_HEALTHD_LOGS_FOLLOW`	`--follow`, `-f`	Follow log output
`healthd restart`	`INCUS_COMPOSE_HEALTHD_RESTART_TIMEOUT`	`--timeout`	Timeout for stopping
`self-update`	`INCUS_COMPOSE_SELF_UPDATE_DRAFT`	`--draft`	Also consider draft releases
`self-update`	`INCUS_COMPOSE_SELF_UPDATE_PRE_RELEASE`	`--pre-release`	Also consider pre-releases

port-forward --dry-run has no variable - see the exceptions table in Environment Variables.

The healthd rows are the incus-compose healthd <subcommand> management commands, distinct from up's own --healthd-* flags. The daemon itself reads a further set of variables - see The ic-healthd daemon.