Pass host devices into a container

Give one service access to a GPU, a USB device, FUSE, a webcam, or a TPM, and keep the other hardened defaults.

Read as MarkdownEdit on GitHub

Prerequisites

  • The device node exists on the host, for example /dev/dri or /dev/ttyUSB0.
  • You know the devices: entry syntax: <host>[:<container>[:<perms>]].

Add a device to a service

Add the devices: entries

List each device under run.options.devices. If the service needs specific permissions, add them to the entry.

services:
  - name: media
    image: jellyfin/jellyfin
    tag: "10.10"
    run:
      port: 8096
      options:
        devices:
          - /dev/dri              # all Intel/AMD GPU nodes
          - /dev/dri/card0:/dev/dri/card0:rw   # explicit perms

Make sure that the config is valid

yoink validate

yoink validate rejects malformed entries. Security defaults shows the error and the rejected entries.

Deploy

Run yoink up. Make sure that the app in the container can open the device.

GPU transcode (Plex / Jellyfin / Frigate / Ollama)

- name: jellyfin
  image: jellyfin/jellyfin
  tag: "10.10"
  run:
    port: 8096
    options:
      user: "0:0"             # most media images need root for HW access
      devices:
        - /dev/dri            # Intel/AMD VAAPI
        # - /dev/nvidia0      # NVIDIA — see below
        # - /dev/nvidiactl
        # - /dev/nvidia-uvm

For NVIDIA, install the nvidia-container-runtime on the host and list the /dev/nvidia* nodes. yoink does not pass the --gpus flag through. Use the same pattern for Ollama, vLLM, and whisper-server.

USB-attached hub (Zigbee / Z-Wave / serial)

- name: zigbee2mqtt
  image: koenkk/zigbee2mqtt
  tag: latest
  run:
    options:
      user: "0:0"
      devices:
        - /dev/ttyUSB0:/dev/ttyACM0:rw   # remap if your stick reports a different node

If the order of /dev/ttyUSB* changes after a reboot, add udev rules on the host. The rules give the device a stable /dev/serial/by-id/... path.

FUSE (JuiceFS, sshfs, restic mount)

- name: juicefs
  image: juicedata/mount
  tag: latest
  run:
    options:
      user: "0:0"
      cap_add: [SYS_ADMIN]    # mount(2) needs the cap
      read_only: false        # FUSE userspace daemons write to /var/lib
      devices:
        - /dev/fuse

The other hardened defaults stay in effect: no-new-privileges, cap_drop=ALL except SYS_ADMIN, and non-root if the daemon supports it.

Webcam (Frigate)

- name: frigate
  image: ghcr.io/blakeblackshear/frigate
  tag: stable
  run:
    options:
      user: "0:0"
      devices:
        - /dev/video0
        - /dev/dri              # also use VAAPI for hw decode

TPM / hardware crypto

- name: vault
  image: hashicorp/vault
  run:
    options:
      cap_add: [IPC_LOCK]
      devices:
        - /dev/tpm0:/dev/tpm0:rw

See also

Type a flag, a config field, or a task.