Skip to content

Android Deployment

Guide to deploying Adaptive Sentience on Android devices using Termux or the native Android app.

Deployment Options

Option 1: Edge Node (Termux)

Run a full edge node in Termux for tool execution.

Use cases: - Mobile edge computing - Field data collection - Distributed tool execution

Option 2: Android App (Native)

Use the native Jetpack Compose app for agentic chat and workflow execution.

Use cases: - User-facing interface - Mobile chat client - Decision trace viewing

Option 1: Edge Node via Termux

Prerequisites

  • Android device (Android 7.0+)
  • 2GB+ RAM
  • F-Droid app store
  • Network connectivity

Step 1: Install Termux

  1. Download Termux from F-Droid (NOT Google Play):

  2. https://f-droid.org/packages/com.termux/

  3. Open Termux and update packages: 

    pkg update && pkg upgrade

  4. Install required packages: 

    pkg install python openssh git

Step 2: Setup SSH (Optional)

Enable SSH for remote setup:

# Start SSH server
sshd

# Find device IP
ifconfig | grep "inet "

# Set password (optional)
passwd

SSH will run on port 8022. From your computer:

ssh -p 8022 u0_a129@192.168.1.100

Step 3: Install Edge Node

Option A: Remote Transfer (from Mac/Linux)

# On your computer
cd /path/to/agent_mesh
scp -P 8022 -r edge_node u0_a129@192.168.1.100:~/

# SSH into Android
ssh -p 8022 u0_a129@192.168.1.100

Option B: Clone on Device

# On Android (Termux)
cd ~
git clone https://github.com/adaptivesentience/agent_mesh.git
cd agent_mesh/edge_node

Step 4: Install Dependencies

cd ~/agent_mesh/edge_node

# Install Python packages
pip install -r requirements.txt

# Verify installation
python -c "import fastapi; import uvicorn; print('✓ Dependencies installed')"

Step 5: Start Edge Node

cd ~/agent_mesh/edge_node

# Start in foreground
NODE_PORT=8000 python node.py

# Or start in background
nohup python node.py > node.log 2>&1 &

Expected output: 

============================================================
Edge Node Starting
============================================================
Node ID: local:android_abc123
Host: 0.0.0.0:8000
Platform: android
============================================================
INFO:     Uvicorn running on http://0.0.0.0:8000

Step 6: Verify Node is Running

From Android (Termux):

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

# Capabilities
curl http://localhost:8000/capabilities | python -m json.tool

From your computer:

# Replace with your Android IP
curl http://192.168.1.100:8000/health

Option 2: Native Android App

Prerequisites

  • Android Studio (for building)
  • Android device or emulator
  • Gateway running (local or remote)
  • ADB installed

Step 1: Build APK

cd agent_mesh/android_app

# Build debug APK
./gradlew assembleDebug

# APK location:
# app/build/outputs/apk/debug/app-debug.apk

Step 2: Install on Device

# Connect device via USB
adb devices

# Install APK
adb install -r app/build/outputs/apk/debug/app-debug.apk

Step 3: Configure Gateway Connection

For Emulator

Gateway must run on host machine:

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

# Set up port forwarding
adb reverse tcp:8787 tcp:8787

App will connect to http://127.0.0.1:8787.

For Physical Device (Same Network)

Gateway runs on network:

# On gateway machine
python -m gateway.http_gateway --host 0.0.0.0 --port 8787 --dev-token

Configure app to use gateway IP:

  1. Open app settings
  2. Set Gateway URL: http://192.168.1.50:8787
  3. Save

Step 4: Launch App

  1. Open "Agentic Chat" app
  2. Pre-filled prompt should appear
  3. Tap "Send" to execute workflow
  4. View decision trace for execution details

Configuration

Termux Edge Node

# 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
NODE_PORT=8000 python node.py

Android App

Gateway URL configured in app settings:

// res/values/strings.xml
<string name="default_gateway_url">http://127.0.0.1:8787</string>

Or via UI: Settings → Gateway URL

Auto-Start on Boot (Termux)

Install Termux:Boot

  1. Download from F-Droid:

  2. https://f-droid.org/packages/com.termux.boot/

  3. Open app once to grant permissions

Create Startup Script

mkdir -p ~/.termux/boot

cat > ~/.termux/boot/start-edge-node.sh << 'EOF'
#!/data/data/com.termux/files/usr/bin/bash

# Wait for network
sleep 30

# Start edge node
cd ~/agent_mesh/edge_node
nohup python node.py > node.log 2>&1 &

# Log startup
echo "Edge node started at $(date)" >> ~/agent_mesh/edge_node/boot.log
EOF

chmod +x ~/.termux/boot/start-edge-node.sh

Test

Reboot device and verify node starts automatically:

# After reboot
curl http://localhost:8000/health

Performance Considerations

Android Node Characteristics

Strengths: - ✅ Built-in battery backup - ✅ Mobile connectivity option - ✅ GPS and sensors available - ✅ Low power consumption - ✅ Can run 24/7 if plugged in

Limitations: - ⚠️ Limited CPU (slower than desktop) - ⚠️ Limited RAM (2-4GB typically) - ⚠️ Android kills background processes - ⚠️ Network may be less stable

Best Use Cases: - Light tool execution - Mobile data collection - Field sensor data - Demo scenarios

Not Recommended For: - Heavy compute tasks - Large model inference - High-throughput workloads

Troubleshooting

Termux Node Issues

Node Crashes or Gets Killed

Android may kill background processes:

Solution 1: Keep Termux in foreground - Don't close Termux app - Disable battery optimization for Termux

Solution 2: Use wake lock 

termux-wake-lock
# Run your node
# When done: termux-wake-unlock

Solution 3: Auto-restart script 

while true; do
    python node.py 2>&1 | tee -a node.log
    echo "Node crashed at $(date), restarting..." | tee -a node.log
    sleep 5
done

Can't Connect from Gateway

# On Android: Check node is listening on all interfaces
netstat -tuln | grep 8000
# Should show 0.0.0.0:8000, not 127.0.0.1:8000

# On gateway machine: Test connectivity
ping 192.168.1.100
nc -zv 192.168.1.100 8000

# Check Android firewall (if using firewall app)
# Make sure port 8000 is allowed

Permission Errors

# Fix permissions
chmod -R 755 ~/agent_mesh/edge_node
chmod 600 ~/agent_mesh/edge_node/keys/*

# Recreate keys
rm -rf ~/agent_mesh/edge_node/keys
mkdir ~/agent_mesh/edge_node/keys
python node.py  # Will regenerate keys

Android App Issues

Can't Connect to Gateway

  1. Check gateway is running: 

    curl http://gateway-ip:8787/health

  2. Check network connectivity:

  3. Device on same network as gateway?

  4. Firewall blocking port 8787?

  5. For emulator: Set up port forwarding: 

    adb reverse tcp:8787 tcp:8787

  6. Check app settings:

  7. Settings → Gateway URL
  8. Should match gateway address

Execution Fails

  1. Check gateway logs: 

    tail -f gateway.log

  2. View decision trace:

  3. Tap "View Decision Trace" in app

  4. Check for error steps

  5. Test from command line: 

    curl -X POST http://gateway:8787/v1/orchestrate \
  -d '{"text": "Test: redact PII from test@example.com"}'

Security Notes

Termux Edge Node

  • Node listens on 0.0.0.0 (all interfaces) by default
  • Use firewall to restrict access if needed
  • Consider VPN for remote access
  • Keep Termux and packages updated

Android App

  • Uses HTTPS for gateway communication (if configured)
  • Capability tokens included in requests
  • Trust verification for node responses
  • No sensitive data stored locally

Demos

Offline Multi-Node Demo

Test workflow execution across Android and other nodes:

# 1. Start gateway on Mac/Linux
python -m gateway.http_gateway --host 0.0.0.0 --port 8787 --dev-token

# 2. Start edge node on Android (Termux)
NODE_PORT=8000 python node.py

# 3. Run demo
python demos/offline_multinode_demo.py

Agentic Chat Demo

Test chat interface with agent selection:

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

# 2. Set up port forwarding (for emulator)
adb reverse tcp:8787 tcp:8787

# 3. Launch Android app
adb shell am start -n com.dwo.agentic_chat/.MainActivity

# 4. Send message from app
# Watch decision trace for agent selection details

Next Steps