App configuration

Every app has a configuration file in its folder that tells the Supervisor what the app is and what it needs. This page lists every key the Supervisor accepts. It follows the schema in the Supervisor code (supervisor/apps/validate.py).

The file is called config.yaml, config.yml, or config.json. All examples here use YAML. Because the Supervisor searches a repository for these names at any depth, do not use config.yaml for anything else in your app, unless it is inside a folder called rootfs or a hidden folder.

name: "Hello world"
version: "1.1.0"
slug: "hello_world"
description: "My first real app!"
url: "https://github.com/me/my-apps/tree/main/hello_world"
arch:
  - aarch64
  - amd64
init: false
ports:
  8000/tcp: 8000
map:
  - type: share
    read_only: false
  - type: homeassistant_config
    path: /custom/config/path
image: "ghcr.io/me/hello-world"

Keys the Supervisor does not know are ignored without a warning, so check your spelling.

Without machine, the app is available on every machine. With it, the app is only available on the machine types you list. An entry with a ! in front, like !raspberrypi5-64, explicitly excludes a machine type.

The accepted values are generic-aarch64, generic-x86-64, green, intel-nuc, khadas-vim3, odroid-c2, odroid-c4, odroid-m1, odroid-n2, qemuarm-64, qemux86-64, raspberrypi3-64, raspberrypi4-64, raspberrypi5-64, and yellow. The deprecated values odroid-xu, qemuarm, qemux86, raspberrypi, raspberrypi2, raspberrypi3, raspberrypi4, and tinker are still accepted, with a warning.

Use the name of a multi-architecture image. The placeholder {arch} is still supported for images that are published per architecture, like ghcr.io/me/{arch}-my-app. See Publish your app.

The types and rules are in Add options.

webui and watchdog use placeholders, which the Supervisor fills in:

• [HOST]: the host. For Open Web UI, that is the address the user reaches Home Assistant on; the watchdog uses the IP address of the app.
• [PORT:8080]: for Open Web UI, the port on the host that container port 8080 is mapped to. The watchdog connects to the IP address of the app, so it uses container port 8080 itself, unless the app runs on the host network.
• [PROTO:option]: https if the option called option is true, http otherwise.

webui: "[PROTO:ssl]://[HOST]:[PORT:8080]/dashboard"
watchdog: "http://[HOST]:[PORT:8080]/health"

The format of webui is http, https, or [PROTO:option], then ://[HOST]:[PORT:number], then an optional path. watchdog accepts the same, and also tcp://[HOST]:[PORT:number] to check only that the port accepts connections. In watchdog, the port may also be a plain number. An HTTP watchdog counts any response below 300 as healthy.

An app with ingress_port: 0 must not expose any port between 62000 and 65500 in ports; the Supervisor rejects that configuration.

map lists the folders of the host to mount in the container. Each entry has a type, and optionally read_only (default true) and path (the mount point in the container).

map:
  - type: share
    read_only: false
  - type: ssl
  - type: media
    path: /mnt/media

If you set path, it must not be empty, not /, and not the same as the path of another entry.

Older names are still accepted, with a warning: addons for local_apps (mounted at /addons), all_addon_configs for all_app_configs (mounted at /addon_configs), and addon_config for app_config. The old config type mounts the Home Assistant configuration at /config; use homeassistant_config instead. The old short form, like share:rw, still works too.

More on each of these in Access hardware and the host.

The capabilities you can add are AUDIT_WRITE, BPF, CHECKPOINT_RESTORE, DAC_READ_SEARCH, IPC_LOCK, MKNOD, NET_ADMIN, NET_RAW, PERFMON, SETFCAP, SYS_ADMIN, SYS_MODULE, SYS_NICE, SYS_PTRACE, SYS_RAWIO, SYS_RESOURCE, and SYS_TIME. Ask only for what your app needs: many of them lower the security rating.

AUDIT_WRITE, MKNOD, NET_RAW, and SETFCAP are part of the default set of Docker today. The Supervisor is moving to a smaller default set without them, behind two feature flags that are off by default: app_drop_net_raw drops NET_RAW, and app_reduced_capabilities drops the other three. If your app needs one of them, list it in privileged now; a capability you ask for is never dropped.

Each limit is a number, or a mapping with soft and hard:

ulimits:
  nofile:
    soft: 65535
    hard: 65535
  nproc: 4096

A value can not be higher than the hard limit of the host. On Home Assistant OS, the hard limit of nofile is 524288; ulimit -Ha on the host shows all of them.

More in Talk to Home Assistant and the Supervisor.

See Share services and discover integrations.

With backup: cold, backup_pre and backup_post are ignored.

The Supervisor still reads a few old keys and converts or ignores them, with a warning:

• advanced is ignored.
• codenotary is ignored.
• snapshot, snapshot_pre, snapshot_post, and snapshot_exclude are read as their backup counterparts.
• auto_uart is read as uart.
• startup: before and startup: after are read as services and application.
• devices entries in the old host:container:permissions format are reduced to the host path.

A separate build.yaml (or build.json) is deprecated as well. See Build the container image.