Deployment Architecture¶
Guide to deploying Adaptive Sentience in production environments.
Deployment Models¶
1. Development¶
Single-machine setup for testing and development.
┌──────────────────────────────┐
│ Developer Laptop │
│ │
│ ┌────────────────────────┐ │
│ │ Gateway (8787) │ │
│ └────────────────────────┘ │
│ ↓ │
│ ┌────────────────────────┐ │
│ │ Edge Node (8000) │ │
│ └────────────────────────┘ │
└──────────────────────────────┘
Use case: Tool development, workflow testing, debugging
Setup:
# Terminal 1: Start gateway
python -m gateway.http_gateway --host 127.0.0.1 --port 8787 --dev-token
# Terminal 2: Start edge node
cd edge_node && NODE_PORT=8000 python node.py
2. Small Team¶
Single gateway with multiple edge nodes on LAN.
┌─────────────────────────────────────────┐
│ Local Network (LAN) │
│ │
│ ┌─────────────────┐ │
│ │ Gateway │ │
│ │ (Server/Mac) │ │
│ └────────┬────────┘ │
│ │ │
│ ┌──────┴──────┬─────────────┐ │
│ ↓ ↓ ↓ │
│ ┌────┐ ┌────┐ ┌────┐ │
│ │Mac │ │Linux│ │RPi │ │
│ │Node│ │Node│ │Node│ │
│ └────┘ └────┘ └────┘ │
└─────────────────────────────────────────┘
Use case: Team of 5-20 users, office/lab environment
Features: - TOFU pairing for simplicity - Shared capability tokens - UDP multicast discovery - Local audit logging
3. Field Operations¶
Mobile gateway with heterogeneous edge devices.
┌──────────────────────────────────┐
│ Field Site (Construction) │
│ │
│ ┌────────────────┐ │
│ │ Gateway │ │
│ │ (Laptop/Tablet)│ │
│ └───────┬────────┘ │
│ │ │
│ ┌──────┼──────┬─────────┐ │
│ ↓ ↓ ↓ ↓ │
│ ┌────┐ ┌────┐ ┌────┐ ┌────┐ │
│ │Phone│ │Tab │ │Cam │ │RPi │ │
│ └────┘ └────┘ └────┘ └────┘ │
│ │
│ Offline-first, sync when online │
└──────────────────────────────────┘
Use case: Construction, utilities, emergency response
Features: - Offline-capable execution - Store-and-forward messaging - Geographic targeting - Mobile device support
4. Enterprise¶
Multi-region deployment with high availability.
┌────────────────────────────────────────────┐
│ Enterprise Network │
│ │
│ ┌──────────┐ ┌──────────┐ │
│ │ Gateway │ │ Gateway │ │
│ │ Primary │←→│ Secondary│ │
│ └────┬─────┘ └────┬─────┘ │
│ │ │ │
│ ┌────┴───────────────┴────┐ │
│ │ Load Balancer │ │
│ └────┬───────────┬─────────┘ │
│ │ │ │
│ ┌────▼────┐ ┌────▼────┐ │
│ │ Region A│ │ Region B│ │
│ │ Nodes │ │ Nodes │ │
│ └─────────┘ └─────────┘ │
│ │
│ + PKI-based trust │
│ + Role-based capability tokens │
│ + SIEM integration │
└────────────────────────────────────────────┘
Use case: Large organizations, compliance requirements
Features: - High availability gateways - PKI-based node pairing - Fine-grained capability tokens - Full audit logging to SIEM - Multi-region distribution
5. Air-Gapped¶
Isolated network with no external connectivity.
┌──────────────────────────────┐
│ Isolated Network │
│ (No Internet) │
│ │
│ ┌────────────────────────┐ │
│ │ Gateway │ │
│ └────────┬───────────────┘ │
│ │ │
│ ┌──────┴──────┐ │
│ ↓ ↓ │
│ ┌────┐ ┌────┐ │
│ │Node│ │Node│ │
│ │ A │ │ B │ │
│ └────┘ └────┘ │
│ │
│ Physical media for updates │
└──────────────────────────────┘
Use case: Classified operations, maximum security
Features: - No external network access - Manual updates via physical media - One-way data diodes (optional) - Maximum security posture
Component Deployment¶
Gateway Deployment¶
Hardware Requirements¶
Minimum: - 2 CPU cores - 4GB RAM - 10GB storage - Network connectivity
Recommended: - 4+ CPU cores - 8GB+ RAM - 50GB SSD storage - Redundant network interfaces
Installation¶
# Clone repository
git clone https://github.com/adaptivesentience/agent_mesh.git
cd agent_mesh
# Install dependencies
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
# Configure environment
cp .env.example .env
# Edit .env with your settings
# Start gateway
python -m gateway.http_gateway \
--host 0.0.0.0 \
--port 8787 \
--dev-token
Configuration¶
# .env file
GATEWAY_HOST=0.0.0.0
GATEWAY_PORT=8787
DEV_TOKEN_ENABLED=false
TRUST_MODE=pki # or 'tofu'
AUDIT_LOG_PATH=/var/log/agent_mesh/audit.log
MESH_MULTICAST_IP=239.255.42.99
MESH_MULTICAST_PORT=9999
Systemd Service (Linux)¶
# /etc/systemd/system/agent-mesh-gateway.service
[Unit]
Description=Adaptive Sentience Gateway
After=network.target
[Service]
Type=simple
User=agent-mesh
WorkingDirectory=/opt/agent_mesh
Environment="PATH=/opt/agent_mesh/venv/bin"
ExecStart=/opt/agent_mesh/venv/bin/python -m gateway.http_gateway --host 0.0.0.0 --port 8787
Restart=on-failure
RestartSec=10
[Install]
WantedBy=multi-user.target
# Enable and start
sudo systemctl enable agent-mesh-gateway
sudo systemctl start agent-mesh-gateway
sudo systemctl status agent-mesh-gateway
Edge Node Deployment¶
Hardware Requirements¶
Varies by platform:
| Platform | CPU | RAM | Storage |
|---|---|---|---|
| Desktop/Laptop | 2+ cores | 2GB+ | 5GB |
| Raspberry Pi | 4 cores | 2GB+ | 8GB |
| Android | 4+ cores | 2GB+ | 4GB |
| Server | 8+ cores | 16GB+ | 50GB |
Installation¶
See platform-specific guides: - Gateway Setup - Edge Nodes - Android Deployment
Network Configuration¶
Port Requirements¶
| Service | Port | Protocol | Purpose |
|---|---|---|---|
| Gateway HTTP | 8787 | TCP | API requests |
| Gateway MCP | 8790 | TCP | MCP server (optional) |
| Edge Node | 8000+ | TCP | Tool execution |
| Mesh Discovery | 9999 | UDP | Multicast discovery |
Firewall Rules¶
# Gateway (allow incoming on 8787)
sudo ufw allow 8787/tcp comment "Agent Mesh Gateway"
# Edge nodes (allow incoming on 8000-8010)
sudo ufw allow 8000:8010/tcp comment "Agent Mesh Edge Nodes"
# Multicast discovery (allow UDP 9999)
sudo ufw allow 9999/udp comment "Agent Mesh Discovery"
Network Requirements¶
- Multicast support for UDP discovery (can be disabled)
- Low latency < 100ms between nodes (for real-time workflows)
- Bandwidth minimum 1 Mbps (higher for large payloads)
Security Configuration¶
Trust Mode¶
TOFU (Trust On First Use)¶
Setup:
Use when: - Development/testing - Trusted network (office LAN) - Quick setup needed
Trade-offs: - ✅ Zero configuration - ✅ Automatic trust establishment - ❌ Vulnerable to MITM on first contact
PKI (Public Key Infrastructure)¶
Setup:
# Generate gateway keys
python -m provisioning.generate_keys --output gateway_identity.pem
# Generate provisioning bundle
python -m provisioning.create_bundle \
--gateway-key gateway_identity.pem \
--node-id edge_node_1 \
--output bundle.json
# Start gateway with PKI
python -m gateway.http_gateway \
--trust-mode pki \
--identity gateway_identity.pem
Use when: - Production deployment - Untrusted network - Compliance requirements
Trade-offs: - ✅ Strong security - ✅ Explicit trust establishment - ❌ Manual key management
Monitoring & Observability¶
Health Checks¶
# Gateway health
curl http://127.0.0.1:8787/health
# Node health
curl http://127.0.0.1:8000/health
# Mesh status
curl http://127.0.0.1:8787/v1/mesh_scan | jq
Metrics¶
# Gateway metrics
curl http://127.0.0.1:8787/v1/metrics
# Node metrics
curl http://127.0.0.1:8000/metrics
Audit Logs¶
# View audit log
tail -f audit/audit.log
# Filter by workflow
cat audit/audit.log | jq 'select(.workflow_id == "feedback_safe_summary")'
# Count executions
cat audit/audit.log | jq -r '.workflow_id' | sort | uniq -c
High Availability¶
Gateway Redundancy¶
Run multiple gateways with shared state:
# Gateway 1
python -m gateway.http_gateway --port 8787 --shared-state redis://localhost:6379
# Gateway 2
python -m gateway.http_gateway --port 8788 --shared-state redis://localhost:6379
Load balancer configuration:
# nginx.conf
upstream agent_mesh_gateways {
server 127.0.0.1:8787;
server 127.0.0.1:8788;
}
server {
listen 80;
location / {
proxy_pass http://agent_mesh_gateways;
}
}
Backup & Recovery¶
Backup Requirements¶
Critical data:
- Trust store (trust/trust_store.json)
- Identity keys (*.pem files)
- Audit logs (audit/audit.log)
- Configuration files (.env, config files)
Backup script:
#!/bin/bash
BACKUP_DIR=/backup/agent_mesh/$(date +%Y%m%d)
mkdir -p $BACKUP_DIR
# Backup trust store
cp trust/trust_store.json $BACKUP_DIR/
# Backup keys
cp -r keys/ $BACKUP_DIR/
# Backup audit logs
cp audit/audit.log $BACKUP_DIR/
# Backup config
cp .env $BACKUP_DIR/
# Create archive
tar czf $BACKUP_DIR.tar.gz $BACKUP_DIR
Next Steps¶
- Gateway Setup - Detailed gateway configuration
- Edge Nodes - Edge node deployment
- Android Deployment - Mobile device setup
- API Reference - API documentation