Incus-compose - the missing docker-compose for incus - v0.0.1-beta6 now available

,
1

Today we released version v0.0.1-beta2 of incus-compose, it’s a bugfix release since beta1 and should be pretty stable for most compose scenarios.

Please report any kind of bugs you see to:

Many thanks and have fun,

René

incus-compose README as reference here:

Bring the familiar Docker Compose workflow to Incus containers. incus-compose implements the Compose specification for the Incus ecosystem, allowing you to define and run multi-container applications using the same docker-compose.yml files you already know.

Why incus-compose?

Incus provides powerful system containers and virtual machines with superior security and isolation, but lacks the declarative multi-container orchestration that Docker Compose offers. This tool bridges that gap:

  • Use existing docker-compose.yml files with Incus containers
  • Leverage Incus’s native OCI registry support for image pulling
  • Run Docker/OCI images directly from registries
  • Manage complex multi-container applications with familiar commands
  • Benefit from Incus’s resource efficiency and security model

Quick Links

Full Documentation | Contributing

Status

Beta - testing the beta1 release of incus-compose.

What works:

  • up, down, list (and ps), start, stop, restart, exec, config, logs commands
  • Compose project parsing via compose-go
  • OCI image pulling from docker.io, ghcr.io, and other registries
  • Bridge networks with automatic name sanitization
  • Storage volumes with UID/GID shifting for proper permissions
  • Bind mounts (local connections only)
  • Port forwarding via proxy devices
  • Incus project isolation

What’s coming:

  • VM instance support alongside containers
  • Container image building via Podman/Docker
  • Advanced compose features (healthchecks, resource limits, etc.)

Architecture

incus-compose uses a resource-first design, see Architecture Documentation for details.

Quick Start

Prerequisites

# Add OCI image remotes to Incus
incus remote add --protocol oci docker.io https://docker.io
incus remote add --protocol oci ghcr.io https://ghcr.io
incus remote add --protocol oci registry.gitlab.com https://registry.gitlab.com

Installation

Binary:

Source:

# Build from source
git clone https://gitlab.com/r3j0/incus-compose
cd incus-compose
just build

# Or install directly
go install gitlab.com/r3j0/incus-compose/cmd/incus-compose@latest

Usage

# Create a compose.yaml
cat > compose.yaml <<EOF
services:
  web:
    image: docker.io/nginx:alpine
    ports:
      - "8080:80"
    volumes:
      - web-data:/usr/share/nginx/html

volumes:
  web-data:
EOF

# Start services
incus-compose up

# View logs
incus-compose logs -f

# List running services
incus-compose list

# Stop and remove
incus-compose down

See Getting Started for detailed examples.

Credits

This project builds on work by @bketelsen.
Some components are adapted from docker compose.

This project uses AI tools as development aids (drafting, iteration, reviews, tests, and documentation).
Architecture, constraints, and final code decisions are owned by the human committers.

License

Apache 2.0

3 Likes
Early development version of the resurrected `incus-compose` online
2

Just released v0.0.1-beta3

New features:

Fixes:

2 Likes
3

As a user you might wanna have a look at the Fixtures for a quick start.

A complete compose file is immich (I run it in production with a manual docker.io/pcdummy/* mirror) and if you need nat-proxy is also very helpfull.

4

New release v0.0.1-beta4

Features

  • Added support for x-incus options.

    • Compose services can now pass raw Incus instance config directly through to Incus.
    • Example use cases: memory/CPU limits, nesting, security flags.
    • Project configuration can now be applied consistently across CLI commands and Incus operations.

  • Added automatic loading of the default incus profile.

  • Added project-wide x-incus-compose.network-profile support.

    • Disables a per project default network/bridge.

  • Added healthd reload support on service changes.

    • The health daemon can now reload/reconfigure when service state changes.

Fixes

  • Fixed network creation race that could cause dnsmasq failures in CI.

    • Avoids immediately updating a newly-created Incus network, which could restart dnsmasq before the old process released its socket.

  • Fixed down so compose-managed networks are deleted when the project is brought down.

    • This fixes dangling networks…

  • Fixed up --no-pull behavior.

    • The no-pull flag is now respected correctly.
    • 2x faster test runs, 3min from 6min

Tests and tooling

3 Likes
5

v0.0.1-beta5 / v0.0.1-beta6

Compose Incus override files

incus-compose now automatically loads a compose.incus.yaml file when it is present next to the main Compose file.

This makes it easier to keep upstream Docker Compose files unchanged while adding Incus-specific configuration in a separate override file.

Example:

compose.yaml
compose.incus.yaml

Running:

incus-compose -f compose.yaml config

will also load:

compose.incus.yaml

when available.

Healthd image base changed

The ic-healthd image now uses busybox:glibc instead of scratch.

This gives the image a minimal runtime base while still keeping it lightweight.

6

That is ic-healthd (the healthchecker daemon that runs in a container):

$ incus --project=immich console --show-log ic-healthd
2026/06/04 07:15:43 debug mode enabled
2026/06/04 07:15:43 data dir: /var/lib/ic-healthd
2026/06/04 07:15:43 secrets dir: /run/secrets/ic-healthd
2026/06/04 07:15:43 incus: https://10.131.32.1:8443
2026/06/04 07:15:43 projects: [immich]
2026/06/04 07:15:43 no persisted cert; performing first-run registration
2026/06/04 07:15:43 certificate registered and persisted
2026/06/04 07:15:43 connected to incus, project=immich
2026/06/04 07:15:43 database-1, unless-stopped, ["CMD","/usr/local/bin/healthcheck.sh"]
2026/06/04 07:15:43 ic-healthd, ,
2026/06/04 07:15:43 immich-machine-learning-1, unless-stopped, ["CMD","python3","/usr/src/healthcheck.py"]
2026/06/04 07:15:43 immich-server-1, unless-stopped, ["CMD","/usr/src/app/server/bin/immich-healthcheck"]
2026/06/04 07:15:43 redis-1, unless-stopped, ["CMD","redis-cli","ping","||","exit 1"]
2026/06/04 07:15:43 started checker for immich-machine-learning-1 (interval=5s, retries=3, restart=false)
2026/06/04 07:15:43 started checker for immich-server-1 (interval=5s, retries=3, restart=false)
2026/06/04 07:15:43 started checker for redis-1 (interval=5s, retries=3, restart=false)
2026/06/04 07:15:43 started checker for database-1 (interval=10s, retries=3, restart=false)
2026/06/04 07:15:43 health daemon running, monitoring 4 services
2026/06/04 07:15:51 immich-machine-learning-1: check failed (1/3)
2026/06/04 07:15:56 immich-machine-learning-1: check failed (2/3)
2026/06/04 07:16:01 immich-machine-learning-1: check failed (3/3)
2026/06/04 07:16:01 immich-machine-learning-1: stopping the check