Host Capability (Container Runtime)

Request the host's container runtime with a host: capability entry — the provider grants it or refuses with a clear message.

What this demonstrates

A `host:`-marked entry in `requires`/`supports` requests a host capability — granted or refused, never provisioned
The value names an interface, not a product: `container_runtime: docker` means the Docker Engine API (a Podman-compatible socket satisfies it); `any` is runtime-agnostic
`requires` = must be granted or the provider refuses to deploy; `supports` = optional — deploy, probe, degrade
A granted capability exposes `$socket`, `$url`, and `$api`, wired into env vars with `set_env`
The required `host:` marker makes the app's privilege surface machine-extractable — `launchfile validate` prints it

When to use this: Container managers, monitoring agents, and update watchers that talk to the host's container runtime — anything that needs the Docker socket.

Host Capabilities Requires

host-container-runtime.yamlView on GitHub

# Example: App that needs the host's container runtime (D-44)
# Modeled on Dockge (a Docker Compose stack manager, catalog/apps/dockge) —
# the same pattern fits Portainer, Diun, and Beszel.
#
# The `host:` marker on a requires/supports entry requests a host
# CAPABILITY: the provider grants it (mounts/forwards the runtime socket
# and populates $socket / $url / $api) or refuses with a clear message.
# It never provisions anything — unlike a backing service (`type:` entry).
#
# The value names an interface, not a product: `container_runtime: docker`
# means "the Docker Engine API" — a Podman-compatible socket satisfies it.

version: launch/v1
name: dockge
description: "Easy-to-use Docker Compose stack manager with web UI"

image: louislam/dockge:1

requires:
  - host: { container_runtime: docker }   # capability → grant or refuse
    set_env:
      DOCKER_HOST: $url                  # e.g. unix:///var/run/docker.sock

provides:
  - protocol: http
    port: 5001
    exposed: true

storage:
  stacks:
    path: /opt/stacks
    persistent: true
  data:
    path: /app/data
    persistent: true

health: /
restart: always

# Optional variant — a monitoring agent like Beszel declares the socket
# under `supports:` instead: it deploys everywhere, probes DOCKER_HOST at
# startup, and shows container stats only where the capability was granted.

Key lines explained

host: { container_runtime: docker }: The capability entry — the host: marker flags it as privileged; the value names the interface the app speaks.
DOCKER_HOST: $url: Wires the granted coordinate — a DOCKER_HOST-style connection string like unix:///var/run/docker.sock — into the app's environment.

See this pattern in real apps — Dockge and Beszel are real socket consumers that fit this pattern.