Running Docker (OCI) containers with Incus

Since version 6.3, Incus is no longer limited to system containers: it can launch OCI images, meaning application containers from Docker Hub and other registries. This guide adds the OCI remote, launches an image (nginx), explains the CONTAINER (APP) type and sets out the limits of that compatibility. Tested on Incus 7.0. For anyone who wants to run application workloads without installing Docker, on the same platform as their system containers and virtual machines.

What you will learn

Add the OCI remote (docker:).
Launch an application image from Docker Hub.
Understand the CONTAINER (APP) type.
Know the limits compared to Docker.

Prerequisites

Incus installed and initialised (see the installation).
Outbound connectivity to the registries (Docker Hub).

Adding the OCI remote

Unlike the images: remote, which is already present, the Docker remote is not configured by default. You add it once, with the oci protocol:

incus remote add docker https://docker.io --protocol oci
incus remote list

| docker | https://docker.io | oci | none | YES | NO | NO |

Launching an OCI image

With the remote in place, incus launch behaves as it does for a system container, pointing at the docker: remote:

incus launch docker:nginx web
incus list

The output shows a container of a particular type, CONTAINER (APP):

+------+---------+-----------------------+-----------------+
| NAME |  STATE  |         IPV4          |      TYPE       |
+------+---------+-----------------------+-----------------+
| web  | RUNNING | 10.173.191.174 (eth0) | CONTAINER (APP) |
+------+---------+-----------------------+-----------------+

Understanding the CONTAINER (APP) type

The (APP) suffix marks an application container, as opposed to the classic system container. The difference is fundamental:

a system container runs a complete init (systemd) and a whole distribution;
an application container (APP) runs the image process (nginx here) as PID 1, with no system init.

In practice you do not connect to it with incus shell as you would to a machine: you interact with the application process, exactly as with a Docker container. That is the expected behaviour for an OCI image.

Exposing the service

As for any Incus instance, you publish a port with a proxy device linking a host port to the container:

incus config device add web http proxy \
  listen=tcp:0.0.0.0:8080 connect=tcp:127.0.0.1:80

The container's nginx becomes reachable on port 8080 of the host. The networking guide covers the proxy device and its options.

Launching an OCI image larger than 10 GB, you can hit tar: Cannot write: No space left on device even though the disk has room. The real cause: the temporary decompression volume uses volume.size (10 GB by default), and the message does not say so. The fix:

incus storage set <pool> volume.size=50GiB

The limits compared to Docker

The OCI compatibility of Incus is convenient, but it is not a complete replacement for Docker. Things to keep in mind:

no image build from a Dockerfile (Incus consumes images, it does not build them);
no Docker Compose and no native application orchestration;
the tooling ecosystem (private registries, scanners, CI) is still built around Docker.

For a homelab or a handful of services, running OCI images inside Incus avoids installing Docker. For intensive application work, Docker and its ecosystem remain better suited. See the Incus vs Docker comparison.

Key points

The OCI remote is added once: incus remote add docker https://docker.io --protocol oci.
incus launch docker:<image> launches an application image from Docker Hub.
The CONTAINER (APP) type marks an application container (process as PID 1, no init).
You expose a service with a proxy device (listen and connect).
Incus consumes OCI images but does not build them: it is not a complete Docker.

FAQ: common questions about OCI containers in Incus

How do you launch a Docker image with Incus?

You first add the OCI remote with incus remote add docker https://docker.io --protocol oci, because it is not configured by default. Then you launch the image with incus launch docker:nginx web. Incus downloads the image from Docker Hub and starts an application container.

Add the remote, then launch

The Docker remote is not configured by default, so you add it once:

incus remote add docker https://docker.io --protocol oci
incus launch docker:nginx web

Incus downloads the OCI image from Docker Hub and starts an application container. The feature has existed since Incus 6.3.

What is a CONTAINER (APP) type container in Incus?

It is an application container, coming from an OCI image, as opposed to the classic system container. It runs the image process as PID 1, with no system init.

Can you build Docker images with Incus?

No. Incus consumes existing OCI images from registries but does not build them: there is no equivalent of building from a Dockerfile. To build application images you need Docker, Podman or Buildah. Incus stays designed to run system containers and virtual machines.

How do you expose a port of an Incus OCI container?

With a proxy device, which links a host port to the container. For example incus config device add web http proxy listen=tcp:0.0.0.0:8080 connect=tcp:127.0.0.1:80 makes the container service reachable on port 8080 of the host. It is the same mechanism as for any Incus instance.

The proxy device

You publish a port with a proxy device linking a host port to the container:

incus config device add web http proxy \
  listen=tcp:0.0.0.0:8080 connect=tcp:127.0.0.1:80

The service (here nginx on port 80 of the container) becomes reachable on port 8080 of the host. It is the same mechanism as for any Incus instance, system container or virtual machine.

Next steps

Incus networking: make the application service you just launched reachable on the network.
Incus storage: give a persistent volume to an OCI container whose filesystem is disposable.
Profiles and projects: keep your application containers in a space separate from your system containers.