Implementing Pyvorin at the Edge

Running compiled Python at the edge with Pyvorin Native 1.0.9 comes down to three moves: compile on a machine you control, ship the compiled artefacts to the constrained device inside your normal deployment, and activate once at provisioning so the device can run dark within its offline grace window. This page is the implementation companion to the edge and IoT deployment overview. It states the platform limits plainly — one of them, the absence of an ARM wheel, decides the architecture on its own — and then walks through the build, provisioning and licensing steps in order.

The platform reality first

Every design decision on this page follows from the shipped wheel. pyvorin-native 1.0.9 ships exactly one binary build: CPython 3.12 on Linux x86_64. The package metadata declares CPython 3.11 and 3.12 support, and the codebase contains Windows path handling, but no Windows wheel was found — treat Windows as unverified. There is no ARM wheel. Compilation on a Raspberry Pi or an ARM64 gateway with the native package is not a supported path in this release, and any plan that assumes it will stall at the install step.

The consequence is not that edge deployment is impossible. It is that the device and the build host are different machines by design. The honest shape: an x86_64 build host does the compiling; the x86_64 devices do the running. For ARM64 gateways, the on-device product is the separate Pyvorin Edge SDK with its EdgeAgent daemon and compiler bridge; this page refers to that product by name only and makes no claims about its internals — those belong to its own documentation.

Local compile, remote device

The compile-then-deploy pattern works because the compiled artefacts are ordinary files in a known location. Compiling the application on the build host populates <site-packages>/.pyvorin_cache/disk_compile with checksum-validated shared objects, indexed by cache_index.json with LRU eviction capped at 500 entries. Shipping that directory with the package gives the deployed interpreter a warm cache from its first start; there is no separate export step because the cache is the artefact.

Respect the cache key. It hashes the source, the function name, the compilation options and the modification times of the runtime and compiler, so artefacts are bound to the exact package build and flags that produced them. Ship the same package version, the same compiler options and byte-identical application source to every device. A drifted device simply misses the cache and recompiles — harmless on a server, painful on fanless hardware with a slow CPU, and a support call you do not need.

The failure order this gives you is worth stating explicitly, because it is the right one for hardware you cannot easily reach. If the cache directory is corrupted in transit, per-entry checksum validation rejects the bad entries and the affected functions recompile on the device rather than loading damaged code. If a function was edited in the field and its entry misses, the same thing happens: a slow first call, then native speed. If the compiler declines a function entirely, the recorded fallback keeps the device correct at interpreter speed while you schedule a re-provision. Nothing in this list bricks the device, and every failure mode degrades towards the interpreter, never towards an error.

On the device the usual safety properties hold. A function the compiler cannot take runs as its original Python through the recorded fallback path rather than failing, which matters more at the edge than anywhere else because nobody reads stack traces off a sensor gateway at 3 a.m. The fallback mechanism is documented on the unsupported code and fallback page.

The build and provisioning pipeline

Three stages, each on the side of the wire that can afford it:

# On the x86_64 build host — compile and verify
python -m pyvorin compile app/pipeline.py
python -m pyvorin run app/pipeline.py --function run --compare --runs 5

# Package: wheel + application + .pyvorin_cache/disk_compile
# On the device, at provisioning time — activate while the link is up
pyvorin activate YOUR-LICENSE-KEY
pyvorin check

The --compare run times the same loop under CPython and Pyvorin on the same inputs, so the number that enters your capacity model is measured on your code, not quoted from a suite. The full speed-proof procedure, including the CI gate, is on the how to run a speed proof page, and the cache-shipping scheme on the warm-up and caching strategies page.

Activate at provisioning, while the device still has a reliable link, and verify with pyvorin check, which runs the hard licence gate. From that point the device needs the network only inside its grace windows, covered next.

Licensing per device

Two verified facts drive the licensing design. First, activation is device-bound: pyvorin activate sends a single POST to api.pyvorin.com carrying the key and a device fingerprint computed as the first 32 characters of a SHA256 hash over hostname, username and /etc/machine-id. Two devices are two activations; an image cloned across devices is one activation bound to an identity none of them shares, which fails. Plan one activation per physical device and perform it at provisioning. The complete activation and entitlement semantics, including the Ed25519-signed lease and its anti-rollback watermark, are on the activation and entitlement page.

Second, the offline grace windows, verified from the installed build, are tier-dependent once the lease expires: 24 hours on demo and trial, 72 hours on basic and professional, and 90 days on enterprise, plus a server-issued offline permit that budgets additional offline hours. Telemetry — the only other traffic the package generates — batches event metadata on a 5-second timeout, fails silently, and can be reduced to security events only via the in-process privacy API, which is the right setting on metered links; there is deliberately no environment variable for it, so set it in application start-up code. The full endpoint list is on the network requirements page; the compile path itself sends nothing at all, ever, which is the property that makes this architecture viable on intermittent links.

What the measured IoT workloads say

The canonical 2026-09-13 benchmark run includes two IoT-shaped sensor workloads, both completed with correctness checks:

The spread is the lesson. Anomaly detection over a window of readings is a tight numeric loop — precisely the ground a native compiler takes. A rolling average over a handful of values is mostly fixed overhead, and the win is modest. Both results are honest, and neither transfers automatically to your firmware: edge functions skew small, and the suite's worst cases are micro-workloads so tiny that compilation overhead dominates, at 0.05x. Measure the actual loop on a representative host before assuming the 45.85x row applies to it; the commands above take minutes.

A worked judgement call

The recurring question is which devices deserve the native path at all. Our working rule, formed from the numbers above: compile the loop that dominates the device's duty cycle, and leave everything else to the interpreter. A gateway aggregating readings from a hundred sensors per second has a real inner loop, and 45.85x on that loop converts directly into a cheaper CPU or a smaller power budget — at the edge, watts are money. A sensor node that wakes, reads one value and sleeps has no loop worth the name; its result sits near the 1.95x row, and its compile cost at provisioning buys almost nothing at runtime. Do not compile the fleet. Compile the hotspots, one activation per device, and spend the provisioning minutes only where the duty cycle justifies them.

Where to go next

• Edge and IoT deployment — the architecture overview: platform support, offline behaviour and measured sensor workloads.
• Activation and entitlement — device binding, signed leases and grace windows in full.
• Network requirements — every endpoint, payload and timeout in pyvorin-native 1.0.9.
• Warm-up and caching strategies — shipping a warm cache to constrained devices.

Last reviewed 11 June 2026 against pyvorin-native 1.0.9 installed at /root/pvfinal (verified build of 12 September 2026). Platform statements reflect the shipped cp312-linux_x86_64 wheel; no ARM wheel exists in this release and none is claimed. Grace windows and fingerprint semantics are read from the installed licensing build. IoT figures are from the canonical 2026-09-13 benchmark run with memory caps active.