Runtime exceptions
An app is never shaped around one runtime. When an app works on docker and fails on podman, incus or apple, the runtime is fixed to match docker: process 1, the command resolved with the image’s user and PATH, capabilities, networking, signals. This page is the one list of the gaps that are still open. Each row names the runtime, what an app sees there against docker, why the gap stays, the ticket that closes it, and the apps that live with it.
Closing a gap deletes its row and every marker that names it.
| Row | Runtime | What an app sees, against docker | Why it stays | Ticket | Apps |
|---|---|---|---|---|---|
| RX-2 | apple | The command is not process 1. The helper is the container’s first process in its VM and supervises the command as its child, so an image that must be process 1 (s6-overlay’s /init) refuses to start and a check that reads /proc/1 reads the helper. | The helper starts apple entries without a pid namespace of their own. | SHC-3253 | none |
| RX-3 | apple | sysctls are refused. | The apple CLI has no flag for a container’s kernel settings, and the helper does not write them in the VM yet. | SHC-3253 | mailcow, mariadb, mysql |
| RX-4 | apple | runtime, devices and group_add are refused: no GPU or render node reaches the container. | The apple CLI passes no host device into a container’s VM. | SHC-3253 | jellyfin |
| RX-9 | incus | ipc, pid, uts or cgroup set to host is refused, where docker runs the container in the host’s namespace. | An unprivileged Incus instance holds no capability in a namespace the host’s user namespace owns. Running the instance in the host’s user namespace, as network_mode: host and userns_mode: host do, would give it one, but LXC writes into the namespaces it starts a container with: it sets the hostname in the UTS namespace and mounts /proc for the pid namespace, so a kept host namespace needs those writes held back first. | SHC-3638 | none |
| RX-10 | incus | ipc or pid set to service:<name> or container:<name> is refused, and so is network_mode: container:<name>. network_mode: service:<name> is honoured. | The kernel mounts /proc for a pid namespace only for the user namespace that owns it, each Incus instance owns its own, and LXC cannot inherit the holder’s user namespace instead: it then makes no idmapped mount of the root (measured on Incus 7.5.1). LXC can inherit an ipc namespace, which is not built. A container: value names a container by its runtime name, which SHC chooses on every runtime. | SHC-3638 | none |
| RX-11 | incus | cgroup_parent is refused. | Incus makes and owns each instance’s cgroup under its own tree. Docker’s value is a path under docker’s cgroup root, which an Incus node does not have. | SHC-3638 | none |
| RX-12 | incus | storage_opt is refused. | An instance’s root size is a disk device on its storage pool, which size could set where the pool enforces one, and that is not built. Docker honours size only on overlay2 over xfs with pquota, devicemapper, btrfs or zfs, and refuses it on overlay2 over ext4. | SHC-3638 | none |
| RX-13 | incus | use_api_socket is refused. | Compose binds the docker engine’s socket and the user’s registry credentials into the container, and an Incus node runs no docker engine. An app that needs an engine asks for SHC’s broker (privileges.docker_socket in its app.yaml). | SHC-3638 | none |
Markers
Section titled “Markers”An app that lives with a gap says so on the line that needs it, or on the line above:
# shc-runtime-exception: RX-3 sysctls: net.ipv4.tcp_keepalive_time: "60"tests/unit/catalog/runtime_exceptions_test.go keeps this page honest. It
fails when:
- a row does not parse, repeats an id, names a runtime SHC does not run, or names no ticket;
- an app under
apps/carries a marker for a row that does not list it, or a row lists an app that carries no marker for it; - a
compose.yamlunderapps/uses, without a marker naming a row that lists the app: a template conditional on the runtime (shc.runtime), a runtime’s own extension key (x-incus,x-incus-compose,x-podman), or a service key that the incus or apple runtime refuses (ce’s composenorm table). A key the apple runtime leaves to the render (configs) is not a gap; - a service key the incus runtime refuses is named by no incus row, in backticks, or a composenorm note cites a row that is not an incus one. A refusal docker gives on the same node, which its composenorm note says, is not a gap.
Prefer a feature every runtime honours over a marker.
shc@docs:~$