Write suta.yaml

suta.yaml describes what the devices in one project run: containers, their settings, secrets, persistent data, hardware settings and the Suta OS version. Keep it in a repository next to your code. When you plan, Suta turns it into one generation per device in the project, pinning every image by digest so each device runs exactly what you reviewed.

# yaml-language-server: $schema=https://suta.dev/schema/suta.json
project: drone        # the project this file deploys
os: latest            # or an exact Suta OS version, such as 2026.09.1
probation: 2m         # how long a change must stay healthy
hardware:
  i2c: true           # for the sensor's /dev/i2c-1; changing it restarts devices

apps:
  web:
    image: ghcr.io/acme/web:1.4
    ports: ["80:8080"]
    env:
      LOG_LEVEL: info
    secrets:
      - name: db-password
        env: DB_PASSWORD
    files:
      /etc/web/config.toml:
        source: config/web.toml
    volumes:
      /var/lib/web: web-data
    probe:
      http: /health
      port: 8080

  sensor:
    image: ghcr.io/acme/sensor:2.0
    devices: [/dev/i2c-1]
    network: host
    probe:
      exec: [sensor, --check]

registries:
  ghcr.io:
    username: acme-ci
    password: ghcr-token     # the name of a Suta secret

sites:
  london:
    apps:
      web:
        env: {REGION: eu-west}

devices:
  lab-pi:
    probation: 30s
    apps:
      web:
        image: ghcr.io/acme/web:1.5-rc

The first line lets editors with YAML language support, such as VS Code with the Red Hat YAML extension, complete settings and flag mistakes as you type using the suta.yaml schema. suta plan still checks what the schema can’t, such as whether images and secrets exist.

Top-level settings

Setting	Default	Description
project	required	The slug of the project to deploy, shown in the dashboard under the project’s name. Plans cover only that project’s devices.
os	latest	Suta OS version. latest is pinned to the newest release when you first plan.
probation	60s	How long a change must stay healthy before a device accepts it: 90s, 2m, 1h or seconds, from 10 seconds to 1 hour.
hardware	all off	Interfaces and overlays the device starts with. See Hardware settings.
apps	none	The containers to run, by name.
registries	none	Credentials for private registries, by registry host.
sites	none	Overrides for devices in a site.
devices	none	Overrides for one device, by device name.

App, site, secret and volume names use lowercase letters, digits and hyphens, up to 40 characters.

Apps

Setting	Description
image	A container image, by tag (nginx:1.27, ghcr.io/acme/web:1.4) or digest. Images must include linux/arm64.
command	Replaces the image’s command, as a list.
env	Environment variables.
secrets	Secrets by name. A plain name mounts the value as the file /run/secrets/NAME; {name, env} sets an environment variable instead. name@3 pins version 3.
files	Read-only configuration files by container path, with source (a path relative to suta.yaml) or content, and an optional octal mode such as "0600". Up to 64 KiB each.
ports	HOST:CONTAINER, or HOST:CONTAINER/udp.
volumes	Container path to volume name. Add :ro for read-only.
devices	Host device nodes, such as /dev/i2c-1 or /dev/ttyUSB0.
network	bridge (default, with published ports) or host.
privileged	true gives the container full access to the device. Use sparingly.
probe	The health check used during probation: http: /path with port, tcp: PORT or exec: [command].
enabled	false leaves the app out unless a site or device override enables it.

Without a probe, an app is healthy when its container keeps running. An app that exits and restarts three times fails its probation.

Hardware settings

Some hardware is off until the device starts with it turned on: SPI for an e-ink display, I2C for a sensor, or the device-tree overlay a HAT’s instructions tell you to add to config.txt. Declare these under hardware, next to the apps that use them:

hardware:
  spi: true
  overlays:
    - hifiberry-dac
    - gpio-fan,gpiopin=14,temp=60000

apps:
  frame:
    image: ghcr.io/acme/frame:1.0
    devices: [/dev/spidev0.0, /dev/gpiochip0]

Setting	Description
spi	true turns on SPI: /dev/spidev0.0 and /dev/spidev0.1.
i2c	true turns on I2C on the GPIO header: /dev/i2c-1.
overlays	Device-tree overlays in the order they load. Write each one as it appears after dtoverlay= in the HAT’s instructions: its name, then any parameters. It must be an overlay that Suta OS includes.

The device reads these settings only when it starts, so changing them restarts it, and the plan says so. Each device tries the new settings the same way it tries a new Suta OS version: it starts with them once, and keeps them only if your apps stay healthy and it keeps reaching Suta for the whole probation. It also checks that /dev/spidev0.0 or /dev/i2c-1 appears when you turn on SPI or I2C. Otherwise it restarts with its previous settings and reports why. A device refuses an overlay that its Suta OS doesn’t include before it changes anything.

If an app lists /dev/spidev0.0, /dev/spidev0.1 or /dev/i2c-1 under devices but the setting that creates it is off, the plan warns you.

Hardware settings apply to devices that run Suta OS. A device on Raspberry Pi OS keeps its own config.txt until you move it to Suta OS; the plan warns you when that’s the case. A device that moved to Suta OS also keeps the hardware settings it had on Raspberry Pi OS.

Caution

On the Pi Zero 2 W and Pi 3, the device can’t undo a setting that stops the kernel before Suta OS starts; you’d need to fix its SD card by hand. Try a new overlay on one device first, with a rollout canary or --device.

Volumes

A volume is a directory under /data/volumes on the device. Volumes keep their data across generations and are never rolled back, so a new version of your app must still work with the data an older version wrote, and the other way round.

Secrets

A workspace admin creates secrets with the CLI or in Settings > Secrets. Then refer to them by name in suta.yaml:

suta secret set db-password

A plan pins the latest version of each secret it uses. Setting a new value creates a new version; devices get it with your next plan and rollout. Secret values are encrypted in Suta and only sent to devices whose generation names them.

Sites and devices

Give a device a site with suta device site DEVICE SITE or on its Settings tab. A plan resolves each device’s settings in this order:

1. The top level of suta.yaml.
2. The device’s site under sites.
3. The device’s own entry under devices.

Overrides can set os, probation and hardware, and for existing apps image, command, env, files and enabled. Set an environment variable or file to null to remove it. A hardware override changes only the settings it names; its overlays replace the whole list.

To see where each value comes from, run:

suta device explain lab-pi apps.web

suta.lock

suta plan writes suta.lock next to suta.yaml. It records the image digests, Suta OS version and secret versions the plan used. Commit it: the next plan keeps those pins, so an image tag that moves doesn’t change your devices by surprise. Run suta plan --update to pick up new images, OS releases and secret versions.

Caution

Every app your devices run comes from suta.yaml. A device runs exactly the apps in its generation and stops any others that Suta started earlier.