Skip to content

Installation

This guide covers installing Adaptive Sentience on different platforms.

System Requirements

Minimum Requirements

  • Python: 3.9 or higher
  • RAM: 512MB per edge node
  • Storage: 100MB for runtime + tool storage
  • Network: UDP multicast support (for auto-discovery)

Supported Platforms

  • Linux: Ubuntu 20.04+, Debian 11+, RHEL 8+
  • macOS: 11.0 (Big Sur) or higher
  • Windows: 10 or higher (via WSL2)
  • Android: 8.0 (API level 26) or higher
  • Raspberry Pi: Raspberry Pi 3B+ or higher (Raspbian Buster+)

Installation Methods

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

# Create virtual environment
python3 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

Option 2: Install via pip (Coming Soon)

pip install adaptive-sentience

Verify Installation

Test Gateway

python -m gateway.http_gateway --host 127.0.0.1 --port 8787 --dev-token

Expected output: 

Gateway running on http://127.0.0.1:8787
Dev token enabled

Test Edge Node

cd edge_node
NODE_PORT=8000 python3 node.py

Expected output: 

Edge node running on port 8000
Node ID: local:abc123

Platform-Specific Instructions

Ubuntu/Debian

# Install system dependencies
sudo apt-get update
sudo apt-get install python3 python3-pip python3-venv git

# Clone and install
git clone https://github.com/adaptivesentience/agent_mesh.git
cd agent_mesh
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

macOS

# Install Homebrew (if not installed)
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# Install Python 3
brew install python3 git

# Clone and install
git clone https://github.com/adaptivesentience/agent_mesh.git
cd agent_mesh
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

Windows (WSL2)

# Install WSL2 (PowerShell as Administrator)
wsl --install

# Inside WSL2, follow Ubuntu instructions
sudo apt-get update
sudo apt-get install python3 python3-pip python3-venv git
git clone https://github.com/adaptivesentience/agent_mesh.git
cd agent_mesh
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

Raspberry Pi

# Update system
sudo apt-get update
sudo apt-get upgrade

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

# Clone and install
git clone https://github.com/adaptivesentience/agent_mesh.git
cd agent_mesh
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

Android

See Android Deployment Guide for detailed instructions on building and installing the Android app.

Environment Variables

Gateway Configuration

Variable Description Default
GATEWAY_HOST Gateway bind address 127.0.0.1
GATEWAY_PORT Gateway HTTP port 8787
DEV_TOKEN Enable dev token mode false

Edge Node Configuration

Variable Description Default
NODE_PORT Node HTTP port 8000
NODE_ID Custom node ID Auto-generated
DWO_NODE_LAT Node latitude Not set
DWO_NODE_LON Node longitude Not set
DWO_NODE_TYPE Node type (laptop/desktop/pi/android) Auto-detected

Firewall Configuration

Required Ports

Port Protocol Purpose Required For
8787 TCP Gateway HTTP API Gateway
8000+ TCP Edge node HTTP Edge nodes
9999 UDP Mesh discovery (multicast) Auto-discovery
8790 TCP MCP server (optional) MCP integration

Example: UFW (Ubuntu)

# Allow gateway
sudo ufw allow 8787/tcp

# Allow edge nodes (adjust range as needed)
sudo ufw allow 8000:8010/tcp

# Allow multicast discovery
sudo ufw allow 9999/udp

# Allow MCP server (optional)
sudo ufw allow 8790/tcp

Troubleshooting

Python Version Issues

Problem: python: command not found or version < 3.9

Solution: 

# Check Python version
python3 --version

# If < 3.9, install newer version
# Ubuntu/Debian
sudo apt-get install python3.11

# macOS
brew install python@3.11

Permission Denied

Problem: PermissionError: [Errno 13] Permission denied

Solution: 

# Don't use sudo with pip in virtual environment
# Instead, make sure you've activated the venv:
source venv/bin/activate
pip install -r requirements.txt

Port Already in Use

Problem: Address already in use

Solution: 

# Find process using the port
lsof -i :8787  # Or netstat -tulpn | grep 8787

# Kill the process or use a different port
python -m gateway.http_gateway --port 8788

Next Steps