Installing Pyvorin Edge

Introduction

This article walks you through installing Pyvorin Edge on your ARM64 gateway. We cover two methods: the automated curl install script (fastest), and the manual pip-based install (most transparent). We also explain exactly what gets installed where, how to verify the installation, and how to fix the most common errors beginners encounter.

Method 1: Automated Install with Curl

The fastest way to get started is the official install script. This script creates a Python virtual environment, installs the edge runtime and SDK, sets up default directories, and creates a starter configuration file.

Step 1: Run the Install Script

# Create the installation directory
mkdir -p ~/pyvorin-edge
cd ~/pyvorin-edge

# Download and run the installer
curl -fsSL https://install.pyvorin.com/edge/setup.sh | bash
  

What the script does behind the scenes:

1. Checks that Python 3.12+ is available.
2. Creates a virtual environment at ~/pyvorin-edge/.venv.
3. Upgrades pip, setuptools, and wheel.
4. Installs pyvorin-edge-runtime and pyvorin-edge-sdk from PyPI.
5. Installs optional dependencies (paho-mqtt) if requested.
6. Creates default directories: config/, data/, logs/, cache/, kernels/.
7. Generates a starter config.toml at ~/pyvorin-edge/config.toml.
8. Prints next-step instructions.

Step 2: Activate the Environment

source ~/pyvorin-edge/.venv/bin/activate

# Verify the CLI is available
pyv-edge --help
  

Method 2: Manual Installation with Pip

If you prefer to see every step, or if you need to install from a private package index, use the manual method.

Step 1: Install System Dependencies

# Raspberry Pi OS / Debian 12
sudo apt update
sudo apt install -y python3.12 python3.12-venv python3.12-dev \
    build-essential gcc g++ libffi-dev

# Ubuntu 24.04
sudo apt update
sudo apt install -y python3.12-venv python3.12-dev build-essential libffi-dev
  

Step 2: Create the Virtual Environment

mkdir -p ~/pyvorin-edge
cd ~/pyvorin-edge
python3.12 -m venv .venv
source .venv/bin/activate
  

Step 3: Install Pyvorin Edge

# Upgrade packaging tools
pip install --upgrade pip setuptools wheel

# Install the runtime and SDK
pip install pyvorin-edge-runtime pyvorin-edge-sdk

# Optional: MQTT support
pip install paho-mqtt
  

Step 4: Create Directory Structure

mkdir -p ~/pyvorin-edge/{config,data,logs,cache,kernels}
  

Step 5: Create a Starter Config

cat > ~/pyvorin-edge/config.toml << 'EOF'
[sensors]
poll_interval_seconds = 5.0

[[sensors.devices]]
name = "demo_temp"
ingest_type = "simulator"
sensor_type = "temperature"
unit = "°C"
min_value = 0.0
max_value = 100.0
noise_std = 0.5
baseline = 21.0

[windows]
default_size = 100
default_dtype = "float"

[rules]
evaluation_interval_seconds = 10.0
items = []

[policies]
default_action = "allow"
rules = []

[cloud]
enabled = false
endpoint = ""
api_key = ""
batch_size = 100
flush_interval_seconds = 60.0

[privacy]
enabled = true
rules = []

[logging]
level = "INFO"
format = "json"

[health]
port = 8080
enabled = true
EOF
  

What Gets Installed Where

Understanding the file layout helps when you need to debug, back up, or upgrade.

Installation Paths

Python Package Locations

Inside the virtual environment, the key packages live here:

# Runtime code
~/.venv/lib/python3.12/site-packages/pyv_edge_agent/

# SDK code
~/.venv/lib/python3.12/site-packages/pyvorin_edge/

# Key modules
pyv_edge_agent/main.py          # EdgeAgent daemon
pyv_edge_agent/config.py        # Config loader
pyv_edge_agent/privacy.py       # PrivacyPolicy
pyv_edge_agent/cloud_sync/      # Queue and uploader
pyv_edge_agent/ingest/          # Sensor adapters
pyvorin_edge/pipeline.py        # Pipeline class
pyvorin_edge/compiler_bridge.py # CompilerBridge
  

Verifying the Installation

Test 1: Import the Packages

source ~/pyvorin-edge/.venv/bin/activate
python3 -c "from pyv_edge_agent.main import EdgeAgent; print('Runtime OK')"
python3 -c "from pyvorin_edge.pipeline import Pipeline; print('SDK OK')"
python3 -c "from pyvorin_edge.compiler_bridge import CompilerBridge; print('Compiler OK')"
  

Test 2: Check the CLI

pyv-edge --help
# Expected output:
# usage: pyv-edge [-h] [--config CONFIG] [--once]
# Pyvorin Edge Agent
  

Test 3: Run a Single Iteration

cd ~/pyvorin-edge
pyv-edge --config config.toml --once
  

If this completes without errors and prints a JSON log line with "level": "INFO" and "msg": "EdgeAgent stopped", the core runtime is functional.

Test 4: Verify Health Endpoint

# In one terminal, start the agent
pyv-edge --config config.toml

# In another terminal, query health
curl http://localhost:8080/health | python3 -m json.tool
  

You should see a JSON response with "status": "healthy", system metrics, and queue depth.

Post-Install Checks

1. Compiler Toolchain

gcc --version
# Should print something like: gcc (Debian 12.2.0-14) 12.2.0

# Check that Python headers are present
ls $(python3 -c "import sysconfig; print(sysconfig.get_path('include')")/Python.h
# Should exist
  

2. NEON Support

# On ARM64 Linux, check CPU flags
grep -i neon /proc/cpuinfo | head -1
# Should contain 'neon' or 'asimd'
  

3. SQLite Version

python3 -c "import sqlite3; print(sqlite3.sqlite_version)"
# Should be 3.35.0 or newer for WAL mode support
  

4. Disk Space

df -h ~/pyvorin-edge
# Ensure at least 2 GB free for compilation and data growth
  

Troubleshooting Common Installation Errors

Error: "No module named 'pyv_edge_agent'"

Cause: You are running Python outside the virtual environment.

Solution: Always activate the venv first.

source ~/pyvorin-edge/.venv/bin/activate
  

Error: "Python 3.12 is required"

Cause: The system default Python is older.

Solution: Install Python 3.12 (see System Requirements article) and recreate the venv explicitly:

python3.12 -m venv ~/pyvorin-edge/.venv
  

Error: "Failed building wheel for ..."

Cause: Missing build dependencies (build-essential, libffi-dev, Python headers).

Solution:

sudo apt install -y build-essential libffi-dev python3.12-dev
  

Error: "Permission denied" during pip install

Cause: You are trying to install into the system Python without sudo, or the virtual environment was created with a different user.

Solution: Use a virtual environment. Never use sudo pip.

Error: "Could not find a version that satisfies the requirement pyvorin-edge-runtime"

Cause: PyPI is unreachable, or you are on an unsupported platform (e.g., 32-bit ARM).

Solution: Confirm your architecture:

uname -m
# Should print: aarch64
  

Next Steps

With Pyvorin Edge installed and verified, you are ready to run your first pipeline. Continue to the Edge Quick Start article for a complete "Hello World" walkthrough.