Compose Labels (x-arcane)

This is the reference for the x-arcane Compose extension and the com.getarcaneapp.arcane.* container labels. Use them to set project and container icons, add links to a project, configure the updater, and hide containers from the default list.

Arcane turns x-arcane settings into container labels when it loads the Compose file. Docker Compose run outside Arcane ignores x-arcane, so in that case, and for standalone containers, set the labels directly. After changing either, deploy or recreate the containers through Arcane to apply them.

Set project icons and links

Add an x-arcane block at the top level of compose.yaml:

x-arcane:
  icon-light: nginx
  icon-dark: nginx
  urls:
    - https://docs.example.com
    - https://github.com/example/repo

services:
  nginx:
    image: nginx:alpine

Project tags can also be declared here; see Projects.

Set service icons

Service icons are set with labels, not x-arcane:

services:
  nginx:
    image: nginx:alpine
    labels:
      - com.getarcaneapp.arcane.icon-light=nginx
      - com.getarcaneapp.arcane.icon-dark=nginx

The labels work like the project fields above, and com.getarcaneapp.arcane.icon is the single-icon fallback. The short forms arcane.icon, arcane.icon-light, and arcane.icon-dark also work. Project icons and service icons are independent: one never changes the other.

Icon values are either absolute http:// or https:// URLs, which are used as-is, or slugs from your icon catalog. Data URIs and base64 icons are not supported. The Icon Catalog setting in your account preferences decides how slugs resolve:

icon-light and icon-dark slugs get -light or -dark added before .svg, so icon-light: nginx resolves to nginx-light.svg. The single icon slug uses the base file.

Hide containers

Set hidden: true to leave a service’s containers out of the default container list and dashboard counts:

services:
  worker:
    image: ghcr.io/acme/worker:latest
    x-arcane:
      hidden: true

A top-level x-arcane.hidden: true applies to every service, and hidden: false on a service keeps that service visible. An explicit com.getarcaneapp.arcane.hidden label overrides both. Outside Arcane, use the label:

labels:
  com.getarcaneapp.arcane.hidden: 'true'

To see hidden containers, turn on Show Hidden Containers in the container table’s view options.

Updater behavior

Set project defaults under x-arcane.updater, then override individual fields per service:

x-arcane:
  updater:
    strategy: auto
    constraint: '3.x'

services:
  first:
    image: alpine:3.20.0
    x-arcane:
      updater:
        constraint: '=3.20.1'
  second:
    image: alpine:3.20.0
    x-arcane:
      updater:
        enabled: false

Each field is resolved separately, first match wins:

1. An explicit label on the service.
2. The service’s x-arcane.updater field.
3. The project’s x-arcane.updater default.

An empty constraint or tag-pattern string clears an inherited value. Arcane can check project metadata before any containers exist, and the Compose editor offers completions and hover help for these fields.

What each strategy does, and how updates are checked and applied, is explained in Auto Updates.

Reference

Container labels

The last three are explained under Per-container labels.