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.

The patch envelope metadata service is pull-only. There is no push, no notification, no interrupt to the guest. So if the app wants to discover that a new config exists, it has to poll description.json. There is no way around that.

Two different things are worth separating:

• “Constant polling” in the sense of a tight curl loop hammering the endpoint many times a second — not needed.
• “Polling at all” — this is required if you want the app to notice a change on its own. EVE will not tell it.

So the accurate statement is: yes, the app must poll — you just choose the interval (every 30 s, every 5 min, whatever your freshness tolerance is), and you compare SHA hashes to avoid re-applying unchanged blobs. It is still polling; it is just cheap polling.

The only way to avoid polling entirely is to not have the app auto-discover updates — i.e. only fetch on startup, and force a re-fetch by some external action (redeploy/restart the instance, or bump the app so its entrypoint runs again). That is not the app “noticing” a new config — that is you pushing a lifecycle event.

• Want the running app to pick up config changes on its own → it must poll (description.json, SHA-compare, re-download on change). Pick a sane interval.
• Don't want polling → fetch once at boot only, and treat any config change as “restart/redeploy the instance.”

There is no server-push option in the current patch-envelope design.

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