Installation
What are the minimum system requirements?
A Raspberry Pi 4 (2 GB RAM) or any ARM64/AArch64 Linux board with Python 3.11+, 1 GB of free
disk space, and kernel 5.10 or newer. The compiler backend requires a C++17 toolchain
(g++ or clang++) for native hot-path generation.
How do I install the Edge SDK and Runtime?
pip install pyvorin-edge
python3 -c "from pyvorin_edge.pipeline import Pipeline; print(Pipeline)"
Can I run the Edge Agent on x86_64 for development?
Yes. Install the SDK on your workstation and use the simulator adapters. When you compile
hot-paths with CompilerBridge.compile_hotpath(), the resulting .so
is architecture-specific. Re-compile on the target device or use a cross-compilation
environment.
The agent fails to start with "Permission denied" on port 8080.
Ports below 1024 require CAP_NET_BIND_SERVICE or root. The safest fix is to use
a high port in config.toml:
[health]
port = 18080
How do I uninstall everything cleanly?
pip uninstall pyvorin-edge pyvorin
rm -rf /var/lib/pyvorin /var/log/pyvorin ~/.cache/pyvorin
Configuration
Where does the Edge Agent look for config.toml?
It defaults to ./edge_config.toml in the working directory. Override with:
python3 -m pyv_edge_agent --config /etc/pyvorin/config.toml
How do I add a new sensor without restarting the agent?
Edit config.toml and call agent.reload_config(). The agent
re-initialises adapters and ring buffers without dropping the sync queue. See
EdgeAgent.reload_config() in edge_runtime/pyv_edge_agent/main.py.
from pyv_edge_agent.main import EdgeAgent
agent = EdgeAgent(config_path="/etc/pyvorin/config.toml")
agent.start()
# ... later ...
agent.reload_config()
Can I use environment variables in config.toml?
Yes. The runtime expands ${VAR} syntax at load time. For example:
[cloud]
api_key = "${PYVORIN_API_KEY}"
endpoint = "https://api.pyvorin.com/v1/ingest"
How do I change the default rolling window size?
[windows]
default_size = 200
default_dtype = "float"
What is the difference between rolling and tumbling windows?
RollingWindow (defined in edge_sdk/pyvorin_edge/windows.py) overlaps
with adjacent windows and is useful for trend detection. TumblingWindow partitions
time into disjoint buckets and is useful for hourly or daily summaries.
Performance
How do I reduce CPU usage on a Raspberry Pi 4?
Three levers: increase poll_interval_seconds, compile rule conditions to native
code with CompilerBridge.compile_hotpath(), and reduce the number of active
adapters.
What is the expected latency per reading?
Interpreted rules average ~0.05 ms per reading on a Pi 4. Compiled hot-paths reduce this to ~0.005 ms. Measure your own pipeline with:
from pyvorin_edge.pipeline import Pipeline
result = pipeline.run(readings)
print(f"Avg latency: {result.latency_ms:.4f} ms")
My pipeline drops readings under heavy load.
Check the RingBuffer capacity in config.toml. If the buffer is full,
old readings are overwritten. Increase default_size or use a dedicated buffer per
sensor with a larger capacity.
How do I benchmark my pipeline?
from pyvorin_edge.pipeline import Pipeline
pipeline = Pipeline(name="benchmark")
# ... add sensors and rules ...
report = pipeline.run_simulation(duration_seconds=3600.0, interval_seconds=1.0, seed=42)
print(f"Generated {report['readings_generated']} readings")
print(f"Events: {len(report['events'])}")
Why does cpu_percent() return 0.0 on the first call?
SystemMetrics.cpu_percent() in
edge_runtime/pyv_edge_agent/health_monitor/metrics.py computes a delta between
two /proc/stat samples. The first call establishes the baseline; the second call
returns the true utilisation. Use metrics.snapshot() in a loop to get continuous
readings.
Privacy & Security
How do I redact a field before it leaves the device?
from pyvorin_edge.policies import PrivacyPolicy
privacy = PrivacyPolicy(
redact_fields=["patient_id", "ssn"],
retain_hours=72.0,
)
pipeline.add_policy(privacy)
What hashing algorithm does BundleSigner use?
Ed25519 for cryptographic signatures and SHA-256 for per-file integrity digests. See
edge_sdk/pyvorin_edge/packaging/signer.py for the implementation.
How can I verify the audit chain has not been tampered with?
from pyv_edge_agent.privacy_firewall.audit import PrivacyAudit
audit = PrivacyAudit(db_path="edge_store.db")
assert audit.verify_chain(), "Audit chain integrity check failed!"
Can I disable cloud sync entirely for a GDPR-sensitive deployment?
Yes. Set enabled = false under [cloud] in config.toml and
add sensitive sensors to local_only_sensors in the privacy policy. No data will
leave the device.
Is SNMP v3 supported for custom adapters?
Yes. The example SNMP adapter in the telecom tower tutorial uses pysnmp, which
supports SNMP v3 with UsmUserData, auth protocols (MD5, SHA), and priv protocols
(DES, AES).
Cloud Sync
How does the agent behave when the cloud is unreachable?
Items are persisted in CloudSyncQueue (SQLite-backed) and retried with
exponential backoff. No data is lost during outages. See
edge_runtime/pyv_edge_agent/cloud_sync/queue.py.
Can I prioritise critical alerts over telemetry?
from pyv_edge_agent.cloud_sync.queue import CloudSyncQueue, Priority
queue = CloudSyncQueue(db_path="sync_queue.db")
queue.enqueue(payload, priority=Priority.CRITICAL, ttl_seconds=86400)
How do I flush the queue manually?
from pyv_edge_agent.cloud_sync.uploader import HTTPCloudUploader
uploader = HTTPCloudUploader(endpoint="...", api_key="...")
flushed = queue.maybe_flush(uploader=uploader)
print(f"Flushed {flushed} items")
What happens when the queue grows beyond disk capacity?
Items expire based on ttl_seconds. When a record's TTL is reached, it is silently
skipped during dequeue. Critical events should use short TTLs (hours) and telemetry can use
long TTLs (days), so that low-priority data is shed first.
Can I sync to multiple cloud endpoints?
The built-in agent supports one primary endpoint. For multi-destination sync, instantiate
multiple HTTPCloudUploader objects and call maybe_flush() with each
uploader in sequence.
Licensing
Do I need a licence to run the Edge Agent?
The open-source runtime is Apache-2.0 licensed. Advanced compiler backends and cloud analytics dashboards require a valid Pyvorin licence key.
Where do I enter my licence key?
Set the environment variable PYVORIN_LICENSE_KEY or add it to
config.toml:
[license]
key = "${PYVORIN_LICENSE_KEY}"
What happens if the licence expires while the agent is running?
The agent continues to ingest, evaluate rules, and store data locally. Compiler hot-path generation and cloud analytics are disabled until the licence is renewed.
Can I transfer a licence between devices?
Yes. Deactivate the old device in the Pyvorin portal, then activate the new device within 24 hours. The licence is bound to a hardware fingerprint, not a user account.
Is there a free tier for development?
Yes. The Community tier includes the full SDK, simulator adapters, local pipeline execution, and health endpoints. Cloud egress and native compilation are limited to 1,000 events/month.
Still Stuck?
If your question is not answered above, check the
Troubleshooting Installation guide,
read the Understanding the Agent article,
or open an issue on the Pyvorin GitHub repository with your config.toml, agent
version, and the output of curl http://localhost:8080/health.