A patch envelope is EVE-OS's mechanism for delivering/updating data to a running edge app instance at runtime — without rebooting the VM, recreating the image, or redeploying the app. It is a container of one or more binary artifacts (blobs): base64-encoded objects that can be anything — a config file, a YAML, certs, a license key, a small binary, etc.

The core use case is decoupling mutable data/config from the immutable app image. Instead of baking config into the image (and re-rolling the image every time something changes), you attach a patch envelope to the app instance and update just that data. Typical scenarios:

• Pushing updated configuration to a running app without downtime
• Rotating credentials, certs, tokens, license keys
• Delivering site-specific or device-specific parameters to a generic image
• Any case where “recreating the image doesn't make sense” or downtime is unacceptable

You manage it from the controller (the PatchEnvelopeConfiguration API), and EVE exposes it to the app locally.

No — you do not need constant/continuous polling. That is the key point.

The metadata service at 169.254.169.254 is a pull, on-demand interface, not a stream you have to hammer. The normal pattern is:

• The app queries it when it needs the data — typically once at startup (in your entrypoint/init script), and then again only when it expects an update (e.g. a periodic check every N minutes, or triggered by some signal).
• It is not required to be a tight curl loop. You pull, you get the current artifacts, you write them to disk / apply them, done.

Note: the metadata server is only reachable by app instances attached to a local network
instance (the same 169.254.169.254 link-local service used for cloud-init/ECO metadata).
An app on a pure switch NI with no local-NI path will not see it.

How to detect changes without busy-polling: fetch description.json and compare the SHA hashes of the blobs to what you already applied. If unchanged, do nothing. A lightweight periodic check (e.g. every few minutes) is enough — no constant querying.

There are two flavors, which affects how the data reaches the device:

1. Inline artifacts (≤ 10 KB) — carried inside the EdgeDevConfig itself and served directly by the metadata server. Good for small configs.
2. External artifacts — represented as volumes, pulled by EVE's volume manager from a configured datastore, and referenced via VolumeRefs in description.json. Use this for larger blobs. These inherit the datastore's ACL/access requirements, so the datastore must be reachable and permissioned correctly.

• In the app's entrypoint: curl description.json once, download the artifact(s), write them where the app expects them, then start.
• For live updates, add a modest timer (or a reload trigger) that re-fetches description.json, compares SHAs, and re-downloads only on change. No continuous polling needed.
• The app must be on a local network instance to reach 169.254.169.254.
• EVE does not auto-mount the envelope into the guest filesystem — the app is responsible for pulling from the metadata service. For external/volume-backed artifacts EVE downloads the volume on the host side, but your app still discovers/retrieves it via the metadata endpoints. There is always an app-side fetch step; it does not “just appear as a file” without your app (or its init script) doing the pull.

• EVE PATCH-ENVELOPES.md (lf-edge/eve)
• EVE metadata service (LF Edge wiki)
• ECO Metadata — EVE-OS