Edge Node Deployment¶

Guide to deploying edge nodes across different platforms.

Overview¶

Edge nodes are the execution environment for tools. They:

Execute tools in sandboxed environments
Validate capability tokens
Generate execution evidence
Handle offline operation
Report capabilities to gateway

Supported Platforms¶

Platform	Status	Use Case
macOS	✅ Supported	Development, field command centers
Linux	✅ Supported	Servers, workstations, Raspberry Pi
Android	✅ Supported	Mobile data collection, field devices
Windows	⚠️ Experimental	Desktop workstations

macOS Deployment¶

Prerequisites¶

macOS 10.15+
Python 3.9+
2GB+ RAM

Installation¶

# Clone repository
git clone https://github.com/adaptivesentience/agent_mesh.git
cd agent_mesh/edge_node

# Install dependencies
pip install -r requirements.txt

Configuration¶

# Set environment variables
export NODE_PORT=8000
export DWO_NODE_LAT=37.7749
export DWO_NODE_LON=-122.4194
export DWO_NODE_ACCURACY_M=50

Start Node¶

cd edge_node
NODE_PORT=8000 python node.py

Expected output:

============================================================
Edge Node Starting
============================================================
Node ID: local:abc123
Host: 0.0.0.0:8000
Public Key: ed25519:...
============================================================
INFO:     Uvicorn running on http://0.0.0.0:8000

Verify¶

# Health check
curl http://localhost:8000/health

# Capabilities
curl http://localhost:8000/capabilities | jq

Linux Deployment¶

Ubuntu/Debian¶

# Update system
sudo apt update && sudo apt upgrade -y

# Install Python
sudo apt install python3 python3-pip python3-venv -y

# Clone repository
git clone https://github.com/adaptivesentience/agent_mesh.git
cd agent_mesh/edge_node

# Create virtual environment
python3 -m venv venv
source venv/bin/activate

# Install dependencies
pip install -r requirements.txt

# Start node
NODE_PORT=8000 python node.py

Raspberry Pi¶

Hardware Requirements: - Raspberry Pi 4 (2GB+ RAM recommended) - MicroSD card (16GB+) - Power supply - Network connectivity (WiFi or Ethernet)

Setup:

# Update system
sudo apt update && sudo apt upgrade -y

# Install dependencies
sudo apt install python3-pip python3-venv git -y

# Clone repository
cd ~
git clone https://github.com/adaptivesentience/agent_mesh.git
cd agent_mesh/edge_node

# Install
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

# Start node
NODE_PORT=8002 python node.py

Systemd Service¶

# Create service file
sudo nano /etc/systemd/system/agent-mesh-node.service

[Unit]
Description=Adaptive Sentience Edge Node
After=network.target

[Service]
Type=simple
User=pi
WorkingDirectory=/home/pi/agent_mesh/edge_node
Environment="PATH=/home/pi/agent_mesh/edge_node/venv/bin"
Environment="NODE_PORT=8002"
Environment="DWO_NODE_LAT=37.7749"
Environment="DWO_NODE_LON=-122.4194"
ExecStart=/home/pi/agent_mesh/edge_node/venv/bin/python node.py
Restart=on-failure
RestartSec=10

[Install]
WantedBy=multi-user.target

# Enable and start
sudo systemctl enable agent-mesh-node
sudo systemctl start agent-mesh-node
sudo systemctl status agent-mesh-node

Multi-Node Setup¶

Run multiple nodes on the same machine:

Terminal 1: Node A¶

cd edge_node
NODE_PORT=8000 python node.py

Terminal 2: Node B¶

cd edge_node
NODE_PORT=8001 python node.py

Terminal 3: Node C¶

cd edge_node
NODE_PORT=8002 python node.py

Gateway will automatically discover all three nodes.

Configuration Options¶

Environment Variables¶

# Required
NODE_PORT=8000                      # Port to listen on

# Optional
DWO_NODE_LAT=37.7749                # GPS latitude
DWO_NODE_LON=-122.4194              # GPS longitude
DWO_NODE_ACCURACY_M=50              # GPS accuracy in meters
NODE_ID=custom_node_id              # Override auto-generated ID
TRUST_MODE=tofu                     # Trust mode (tofu or pki)
IDENTITY_PATH=node_identity.pem     # Path to identity key

Node Identity¶

Nodes generate Ed25519 identity keys on first run:

# Keys stored in edge_node/keys/
ls edge_node/keys/
# Output: node_identity.pem

To use a specific identity:

# Generate identity
python -m provisioning.generate_keys --output custom_identity.pem

# Start node with identity
IDENTITY_PATH=custom_identity.pem NODE_PORT=8000 python node.py

Tool Installation¶

Built-in Tools¶

Nodes come with default tools: - pii_redact - PII redaction - summarize - Text summarization - validate_schema - Schema validation - unit_convert - Unit conversion

Custom Tools¶

Add custom tools to edge_node/tools/:

# edge_node/tools/custom_tool.py

from typing import Dict, Any
from pydantic import BaseModel

class CustomToolInput(BaseModel):
    input_data: str

class CustomToolOutput(BaseModel):
    result: str

async def execute(input: CustomToolInput) -> CustomToolOutput:
    """Custom tool implementation."""
    result = input.input_data.upper()  # Example: convert to uppercase
    return CustomToolOutput(result=result)

# Tool metadata
TOOL_CONTRACT = {
    "tool_id": "tool:custom_tool",
    "name": "custom_tool",
    "version": "1.0.0",
    "description": "Example custom tool",
    "input_schema": CustomToolInput.schema(),
    "output_schema": CustomToolOutput.schema(),
    "required_capabilities": ["tool:custom_tool"],
    "deterministic": True
}

Restart node to load new tool:

NODE_PORT=8000 python node.py
# Tool will be auto-discovered

Security Configuration¶

TOFU Mode¶

Automatically trust gateway on first contact:

TRUST_MODE=tofu NODE_PORT=8000 python node.py

PKI Mode¶

Explicit trust establishment:

# 1. Receive provisioning bundle from gateway
# 2. Save as bundle.json
# 3. Import trust bundle
curl -X POST http://localhost:8000/v1/trust/import \
  -d @bundle.json

# 4. Start node in PKI mode
TRUST_MODE=pki IDENTITY_PATH=node_identity.pem NODE_PORT=8000 python node.py

Monitoring¶

Health Check¶

curl http://localhost:8000/health

Response:

{
  "status": "healthy",
  "node_id": "local:abc123",
  "uptime_seconds": 3600
}

Capabilities¶

curl http://localhost:8000/capabilities | jq

Response:

{
  "node_id": "local:abc123",
  "tools": [
    {
      "tool_id": "tool:pii_redact",
      "name": "pii_redact",
      "version": "1.0.0",
      "deterministic": true
    }
  ],
  "platform": "macos",
  "location": {
    "lat": 37.7749,
    "lon": -122.4194,
    "accuracy_m": 50
  }
}

Logs¶

# View logs
tail -f edge_node/logs/events.jsonl

# Filter by tool
cat edge_node/logs/events.jsonl | jq 'select(.tool_name == "pii_redact")'

Troubleshooting¶

Node Won't Start¶

Error: Port already in use

# Find process using port
lsof -i :8000

# Kill process
kill -9 <PID>

# Or use different port
NODE_PORT=8001 python node.py

Gateway Not Discovering Node¶

Problem: Node not appearing in mesh scan

Solutions:

Check multicast:

# Node should be broadcasting on UDP 9999
netstat -an | grep 9999

Check firewall:

# Allow incoming on node port
sudo ufw allow 8000/tcp

# Allow multicast
sudo ufw allow 9999/udp

Manual registration at gateway:

curl -X POST http://gateway:8787/v1/nodes/register \
  -d '{
    "node_id": "local:abc123",
    "endpoint": "http://node:8000"
  }'

Permission Errors¶

# Fix permissions on keys directory
chmod 700 edge_node/keys
chmod 600 edge_node/keys/*.pem

Tool Execution Failures¶

# Check tool is loaded
curl http://localhost:8000/capabilities | jq '.tools[].name'

# Check logs for errors
tail -f edge_node/logs/events.jsonl | jq 'select(.level == "ERROR")'

# Test tool directly
curl -X POST http://localhost:8000/v1/tool/execute \
  -H "Content-Type: application/json" \
  -d '{
    "tool_name": "pii_redact",
    "tool_args": {"text": "Test john@example.com"}
  }'

Performance Tuning¶

Resource Limits¶

# Limit CPU usage (Linux)
cpulimit -p $(pgrep -f "python node.py") -l 50

# Limit memory (systemd)
[Service]
MemoryLimit=1G
CPUQuota=50%

Concurrent Executions¶

Configure in edge_node/config.py:

MAX_CONCURRENT_EXECUTIONS = 4  # Adjust based on CPU cores
EXECUTION_TIMEOUT_SECONDS = 300  # 5 minutes

Next Steps¶

Android Deployment - Mobile node setup
Gateway Setup - Connect to gateway
Tool Contracts - Create custom tools
API Reference - API documentation