Installation

Sandroid features a streamlined installation process with automatic Android environment setup.

🚀 Quick Start (Recommended)

One-Command Setup

# Install Sandroid from PyPI
pip install sandroid

# Initialize with automatic Android environment setup
sandroid-config init

The sandroid-config init command provides:

🔍 Automatic Android SDK detection
📱 AVD discovery and configuration
⚙️ Interactive setup with validation
🎯 Smart path detection with user overrides
✅ Ready-to-use configuration

📋 Interactive Setup Experience

When you run sandroid-config init, the system will:

Detect Android environment - Find SDK, ADB, emulator paths
Discover existing AVDs - List available virtual devices
Interactive selection - Choose or create AVD for Sandroid
Configure preferences - Set UI/headless mode, auto-start options
Validate setup - Ensure everything works correctly

$ sandroid-config init
🔧 Initializing Sandroid configuration...

🔍 Detecting Android development environment...
✓ Found Android SDK: /Users/user/Android/Sdk
✓ Found ADB: /opt/homebrew/bin/adb
✓ Found Android Emulator: /Users/user/Android/Sdk/emulator/emulator
✓ Found 3 AVDs: Pixel_6_Pro_API_31, Test_Device, sandroid_avd

📱 Found 3 existing AVDs
Choose an option:
  1. Pixel_6_Pro_API_31 (recommended)
  2. Test_Device
  3. sandroid_avd
  4. Create new 'sandroid' AVD
  5. Skip AVD configuration

✅ Configuration created successfully!

System Requirements

Prerequisites

Python 3.10 or newer
Internet connection (for automated detection)
Linux, macOS, or Windows (WSL2 recommended for Windows)

Optional Dependencies

# With AI analysis support
pip install sandroid[ai]

# With development tools
pip install sandroid[dev]

# With documentation tools
pip install sandroid[docs]

# Install everything
pip install sandroid[ai,dev,docs]
adb version

Create an Android Virtual Device (AVD):
```
# List available AVDs
```
emulator -list-avds

# Create a new AVD (recommended: Pixel_6_Pro_API_31) avdmanager create avd -n Pixel_6_Pro_API_31 -k “system-images;android-31;google_apis;x86_64”

System Dependencies

Linux (Ubuntu/Debian):

sudo apt update
sudo apt install -y sqlite3-tools python3-pip python3-dev build-essential

Linux (CentOS/RHEL):

sudo yum install -y sqlite python3-pip python3-devel gcc gcc-c++

macOS:

# Using Homebrew
brew install sqlite3

Windows:

# Install SQLite tools from https://sqlite.org/download.html
# Add to PATH

Legacy Installation (Still Supported)

For users who prefer the original installation method:

git clone https://github.com/fkie-cad/Sandroid_core.git
cd Sandroid_core
./install-requirements.sh
./sandroid.legacy

Configuration

After installation, initialize the configuration:

sandroid-config init

This creates a configuration file at ~/.config/sandroid/sandroid.toml. Edit this file to customize:

log_level = "INFO"
output_file = "sandroid.json"

[emulator]
device_name = "Pixel_6_Pro_API_31"
android_emulator_path = "~/Android/Sdk/emulator/emulator"

[analysis]
number_of_runs = 2
monitor_processes = true
monitor_network = false

[paths]
results_path = "./results/"
cache_path = "~/.cache/sandroid/"

Environment Variables

All configuration can be overridden with environment variables:

export SANDROID_LOG_LEVEL=DEBUG
export SANDROID_EMULATOR__DEVICE_NAME=Custom_Device
export SANDROID_ANALYSIS__NUMBER_OF_RUNS=5
export SANDROID_PATHS__RESULTS_PATH=/custom/results

Verification

Test your installation:

# Check version
sandroid --version

# Validate configuration
sandroid-config validate

# Test ADB connection (with emulator running)
sandroid --help

# Run in interactive mode
sandroid

Docker Installation

For containerized deployment:

# Build Docker image
./build_and_export_docker.sh

# Deploy with Docker
cd deploy
./deploy /path/to/output

Troubleshooting

Common Issues

“ADB not found” - Ensure Android SDK is installed - Add ADB to your PATH - Test with adb version
“No emulator found” - Create an AVD using Android Studio - Start the emulator before running Sandroid - Verify with adb devices
“Legacy analysis modules not available” - This was fixed in v1.1.0 - Upgrade with pip install --upgrade sandroid
Permission errors - On Linux, ensure your user is in the correct groups:
```
sudo usermod -a -G plugdev $USER
```
SQLite tools missing - Install sqlite3-tools package - Some features will be limited without it

Getting Help

Check the troubleshooting guide: Troubleshooting
Report issues: https://github.com/fkie-cad/Sandroid_core/issues
Review logs in ~/.cache/sandroid/logs/

Next Steps

After installation:

Quick Start Guide - Quick introduction to Sandroid
Configuration - Detailed configuration guide
Interactive Mode - Learn the interactive interface
Command-Line Usage - Command-line options