WendyOS systemd Services

WendyOS is a Yocto-based Linux distribution managed entirely by systemd. This document covers what runs on a WendyOS device, the startup order, and how services depend on one another.

For the Agent's Cloud-owned UUID unenrollment, guarded local erasure and restart recovery, see Cloud-owned unenrollment. This requires compatible Cloud and Agent builds; it is not an assertion of deployed acceptance.

Service inventory

Startup order

The diagram below shows the major ordering relationships. Solid arrows indicate After=/Requires=; dashed arrows indicate Before=/Wants=.

local-fs.target
   |
   +-- data.mount
   |      |
   |      +-- mender-systemd-growfs-data.service (Tegra only)
   |             |
   +-- wendyos-etc-binds.service ────────────────────────────────────+
          |                                                           |
          +-- wendyos-uuid-generate.service                          |
          |        |                                                  |
          +-- wendyos-device-name-generate.service                   |
                   |                                                  |
                   +-- (sysinit.target) ──────────────────────────────+
                                                                      |
                          var-lib-containerd.mount                    |
                          home.mount                    gadget-setup.service
                          [var-log.mount]                      |
                                |                              |
                          containerd.service            network.target
                                |                              |
                                +------------------------------+
                                             |
                                     wendyos-agent.service
                                      (multi-user.target)

wendyos-uuid-generate.service
wendyos-device-name-generate.service
      |
      +-- wendyos-hostname.service --> avahi-daemon.service --+
      +-- wendyos-identity.service ---------------------------+
                                                               |
                                                     wendyos-agent.service

systemd target dependencies

Key ordering rules

1. /data must be mounted before any bind mount or identity service runs.
2. wendyos-etc-binds.service must complete before UUID and device-name generation so the generated files land on the persistent /data volume.
3. gadget-setup.service runs before systemd-networkd so the usb0 interface exists when networkd starts.
4. containerd.service must be running and /var/lib/containerd must be bind-mounted before wendyos-agent.service starts.
5. EEPROM services (RPi 5 only) run after multi-user.target and use a flag file (/var/lib/wendyos/eeprom-updated, /var/lib/wendyos/eeprom-nvme-updated) to guarantee they execute at most once.
6. wendyos-agent.service runs after wendyos-identity.service and avahi-daemon.service. This ensures ReassertHostnameAdvertisement, which restores an explicit wendy device rename hostname over boot-time TXT records, runs after the publisher instead of racing it. These are ordering-only dependencies; packaged Linux installs that do not provide the WendyOS units continue to start normally.

Checking service status

# Overview of all WendyOS-specific services
systemctl status wendyos-*.service gadget-setup.service rpi5-eeprom-config.service

# Live journal for the agent
journalctl -fu wendyos-agent.service

# Check mount targets
systemctl status var-lib-containerd.mount home.mount

Wendy Data storage

WENDY_DATA_INGEST_URL is the cloud DataIngestService endpoint sealed episodes are uploaded to (ingest.data.wendy.sh for the dev data platform). It is required for uploads: the enrolled cloud host does not serve this service, so there is no fallback. Without it the agent logs once at Info level that uploads are disabled and sealed episodes stay queued in the local store, bounded by its quota. The device authenticates with the certificate it enrolled with, presented in the TLS handshake; no request header carries identity.

WENDY_TELEMETRY_URL enables OpenTelemetry exports to an explicitly configured OTLP gRPC collector that accepts the enrolled device's mTLS identity. Cloud's enrollment and relay endpoints no longer provide OTLP ingestion. Without this setting, the agent logs once at Info level that exports are disabled. Telemetry remains available locally within the buffer's retention limits. Set a collector host, host:port, or HTTPS URL without a path, then restart the agent.

WENDY_DATA_DIR sets the root directory for the device-local Episode store. The production default is /var/lib/wendy-agent/data/episodes. Set it in the agent service environment when Episodes should live on a larger data volume:

WENDY_DATA_DIR=/data/wendy-agent/data/episodes wendy-agent

The agent creates the directory on startup. Unprivileged developer agents that cannot create the production default fall back to their platform user configuration directory. WendyOS services should set an explicit path on the persistent /data partition when the root filesystem is small.

Agent shutdown

The agent handles SIGINT and SIGTERM before starting background workers, so termination during startup also requests resource cleanup. Its shutdown log entry is Termination requested, shutting down; it replaces Received signal, shutting down and no longer includes a signal-name field. Use the current entry when filtering logs or configuring alerts.