Get Void running on a fresh Android/Termux environment or desktop development workstation with a single command:
curl -sSL https://raw.githubusercontent.com/ashishsinghbora/void/main/install.sh | bash
[!TIP] To perform a clean reinstall or upgrade to the latest version on Termux:
rm -rf ~/void && curl -sSL https://raw.githubusercontent.com/ashishsinghbora/void/main/install.sh | bash
termux-api, python, python-cryptography (native binary avoiding Rust compilation), git, clang, libffi, openssl, jq, and curl.termux-setup-storage for ~/storage file links and cleans up dangling wake-locks to prevent notification spam.--system-site-packages): Provisions a dedicated virtual environment that inherits native system packages without requiring pip C/Rust builds.void command to $PREFIX/bin/void (or ~/.local/bin/void).If you prefer to install packages manually or inspect every command:
# 1. Update Termux and install system prerequisites
pkg update -y
pkg install -y termux-api python python-cryptography git clang libffi openssl jq curl
# 2. Setup storage access and background wake-lock
termux-setup-storage
termux-wake-lock
# 3. Clone the repository
git clone https://github.com/ashishsinghbora/void.git ~/void
cd ~/void
# 4. Create virtual environment with system site-packages
python3 -m venv --system-site-packages .venv
source .venv/bin/activate
# 5. Install pure-Python dependencies
pip install --no-cache-dir -r requirements.txt
# 6. Enable global launcher
chmod +x bin/void
ln -sf ~/void/bin/void $PREFIX/bin/void
# 7. Start Void
void
Once installed, the global void command gives you instant control:
# 1. Interactive ReAct Terminal Assistant (default)
void
# or explicitly:
void cli
# 2. Start Full Production Stack (Waitress WSGI + Daemons + Web UI)
void start
# Start with custom network options:
void start --host 0.0.0.0 --port 8080 --threads 4
# Start with authenticated Telegram remote bot:
void start --telegram <BOT_TOKEN> --admin-id <TELEGRAM_USER_ID>
# Start without background proactive daemons:
void start --no-daemons
# Start without CPU wake-lock (suppresses Termux wake-lock notification):
void start --no-wake-lock
# 3. Start Void as a 24/7 Background Service (detached nohup)
void start-bg
# Start background service with wake-lock suppressed:
void start-bg --no-wake-lock
# 4. View Active Service Status, Process PID, Memory RSS & Battery Telemetry
void status
# 5. Stop Running Background Service Cleanly
void stop
# 6. Reclaim Storage via System Cleaner Plugin
void clean
# 7. Inspect Android Permissions Status, Rationale & Privacy
void permissions
# 8. Run Full Automated Test Suite (37 Tests)
void test
# 9. Pull Updates from GitHub and Sync Dependencies
void update
# 10. View CLI Help & Options
void help
Void interprets natural language and speech commands dynamically via its deterministic ReAct routing engine and local LLM runtime:
| Category | Supported Directives & Example Queries | Triggered Tool |
|---|---|---|
| Battery Telemetry | “What is my battery level?”, “Battery health”, “Is phone charging?” | get_battery_status |
| Torch / Flashlight | “Turn on the flashlight”, “Switch off the torch” | set_torch |
| Haptic Vibration | “Vibrate the phone”, “Vibrate for 2 seconds” | vibrate_device |
| Speech (TTS) | “Speak out loud: task completed”, “Say hello to the user” | text_to_speech |
| Camera Photo | “Take a photo using camera”, “Take a selfie photo” | take_camera_photo |
| SMS Messaging | “Send SMS to +123456789 saying Meeting at 5pm” | send_sms |
| Voice Dialing | “Call +123456789”, “Dial voice call to 911” | make_phone_call |
| SMS Reader | “Show my recent text messages”, “List latest SMS” | get_sms_messages |
| Contacts | “List phone contacts”, “Search contacts for Alice” | get_contacts |
| Call Log | “Check recent call history”, “Who called me today?” | get_call_log |
| Clipboard | “What is on my clipboard?”, “Copy secret token to clipboard” | get_clipboard / set_clipboard |
| GPS Location | “Where am I right now?”, “Get current GPS location coordinates” | get_location |
| Wi-Fi Diagnostics | “What Wi-Fi network is connected?”, “Scan nearby Wi-Fi networks” | get_wifi_info / scan_wifi_networks |
| App Launcher | “Open WhatsApp”, “Launch YouTube”, “Open Chrome”, “Open Settings” | open_app |
| Audio & Volume | “Set media volume to 10”, “Get audio volume status” | set_volume / get_volume_info |
| Display Brightness | “Set brightness to 200”, “Set screen brightness auto” | set_screen_brightness |
| Audio Recorder | “Start recording microphone audio”, “Stop audio recording” | record_audio_start / record_audio_stop |
| System Share | “Share this text via Android share sheet” | share_content |
| Notifications | “Show notification with title Alert and message Complete” | show_notification |
| Screen Toast | “Show a toast saying Hello Void” | show_toast |
| Crypto Tracker | “Check bitcoin price”, “What is ethereum trading at?”, “Speak solana price” | track_crypto (Plugin) |
| GitHub Monitor | “Check github repo ashishsinghbora/void”, “Show issues on void repo” | monitor_github (Plugin) |
| Storage Cleaner | “Clean temporary cache files”, “Free up device storage space” | clean_system (Plugin) |
flowchart TB
subgraph ClientInterfaces ["Client & Control Interfaces"]
CLI["Interactive CLI (termux_void.py)"]
WebUI["Glassmorphic Dashboard (docs/index.html)"]
TG["Telegram Remote Bot (bot_controller.py)"]
end
subgraph SecurityLayer ["Security & Privilege Sandbox"]
Sanitizer["Whitelist InputSanitizer"]
Vault["AES-256-GCM Vault (PBKDF2)"]
RateLimiter["Token-Bucket Rate Limiter"]
end
subgraph AgentCore ["Core Agentic Engine"]
ReAct["Autonomous ReAct State Machine"]
Fallback["Hardware Fallback Engine"]
LRU["O(1) Bounded LRU Cache"]
EventBus["Pub-Sub EventBus (SSE)"]
end
subgraph HardwareExecution ["Execution & Extension Layer"]
Registry["Hash-Indexed ToolRegistry"]
CmdExec["SecureCommandExecutor (list[str])"]
Simulator["TermuxHardwareSimulator (Desktop Mode)"]
Plugins["Modular Plugins (Crypto, GitHub, Cleaner)"]
end
subgraph AndroidOS ["Android OS / Hardware Subsystem"]
TermuxAPI["Termux:API Unix Socket Bridge"]
Hardware["Camera • Battery • Torch • Haptics • SMS • GPS • Wi-Fi"]
SQLite["SQLite WAL (log_pruner.py)"]
end
ClientInterfaces --> SecurityLayer
SecurityLayer --> AgentCore
AgentCore --> HardwareExecution
HardwareExecution --> AndroidOS
__slots__ declared across all high-frequency data structures, events, and response models.camera_id=1).termux-share)./sdcard and ~), URLs, and strings. Terminal ANSI escape sequences and null-byte injection attacks are stripped automatically.list[str]), completely banning shell=True to render shell metacharacter and command injection attacks impossible.PRAGMA synchronous = NORMAL and thread-local connections.Void features a plugin architecture located in the extensions/ directory. Developers can build custom Python extensions that plug into Void dynamically with zero changes to core code.
| Extension | Tool Name | Description | Example Query |
| :— | :— | :— | :— |
| CryptoTracker | track_crypto | Fetches live coin prices (CoinGecko / Binance) with optional TTS voice announcement. | “What is the price of bitcoin?” |
| GitHubMonitor | monitor_github | Tracks repository stars, forks, open issues, and pull requests via GitHub REST API. | “Check github repo ashishsinghbora/void” |
| SystemCleaner | clean_system | Scans and reclaims storage from stale cache, temporary files, and __pycache__ with dry_run safety. | “Clean temporary cache files” |
Create extensions/my_extension.py:
from extensions.base import ExtensionPlugin
from tools.base import ToolStrategy
from core.types import ToolExecutionResult
class HelloStrategy(ToolStrategy):
def __init__(self):
super().__init__(name="say_hello", description="Say hello to a given user name.")
def execute(self, name: str = "World", **kwargs):
return ToolExecutionResult(success=True, output=f"Hello, {name} from custom plugin!", error=None, duration_ms=0)
class MyExtension(ExtensionPlugin):
def __init__(self):
super().__init__(name="my_extension", version="1.0.0", description="Custom greeting extension.")
def initialize(self, context=None):
pass
def get_strategies(self):
return [HelloStrategy()]
Void’s ExtensionManager automatically discovers and loads your plugin at startup!
Void includes a self-contained web dashboard located in docs/index.html styled with Tailwind CSS (Obsidian & Cyan dark theme):
https://ashishsinghbora.github.io/void/
https://github.com/<your-username>/voidDeploy from a branchmain/docshttps://<your-username>.github.io/void/.http://<PHONE_IP>:5000.cloudflared tunnel --url http://localhost:5000
Open the GitHub Pages UI, click Gateway in the top navigation bar, and enter your public tunnel URL (e.g., https://xyz.trycloudflare.com). The dashboard will seamlessly stream ReAct deliberations and trigger hardware commands over CORS-enabled endpoints.
If you encounter Failed to build cryptography or Target triple not supported by rustup:
[!NOTE] PyPI does not provide pre-compiled wheels for Android Bionic libc. Do not compile cryptography via pip. Install Termux’s official pre-compiled package instead:
pkg install -y python-cryptographyAnd always create your virtual environment with
--system-site-packages:python3 -m venv --system-site-packages .venvThe
install.shscript does this automatically.
[!IMPORTANT] Both Termux and Termux:API must be installed from F-Droid (or GitHub Releases), never the Google Play Store.
Why? Google Play Termux was deprecated due to Android target SDK 29 restrictions. Mixing a Google Play Termux build with an F-Droid Termux:API build causes an
INSTALL_FAILED_UPDATE_INCOMPATIBLEsignature mismatch and completely breaks the Unix IPC socket between Termux and Android hardware sensors.
- Install Termux: F-Droid Package or GitHub Releases
- Install Termux:API: F-Droid Package or GitHub Releases
- CRITICAL STEP (Awaken Termux:API Bridge): After installing Termux:API from F-Droid, open the “Termux:API” app once from your Android app drawer. On modern Android versions (Android 10+), newly installed APKs remain in a dormant “stopped” state until opened manually at least once; opening it once allows Android to route IPC sensor broadcasts from Void without socket timeout hangs.
Navigate to your device’s Android Settings $\to$ Apps $\to$ Termux:API $\to$ Permissions and enable:
take_camera_photo)get_location)send_sms, make_phone_call, get_sms_messages)get_contacts)When running background daemons, Termux holds an Android CPU wake-lock (termux-wake-lock) to prevent the operating system from suspending Python execution during deep sleep. Android 8.0+ enforces a persistent foreground notification (“Termux wake lock held”), which can cause audible alert chimes or clutter the drawer depending on OEM settings.
You can handle this in one of two ways:
Keep the CPU wake-lock active for continuous background operation, but silence the alert permanently:
If you only run Void during active foreground terminal sessions and do not want wake-locks acquired:
# Foreground server with wake-lock disabled:
void start --no-wake-lock
# Background service with wake-lock disabled:
void start-bg --no-wake-lock
# Disable globally via environment variable:
export VOID_NO_WAKE_LOCK=1
# Clear any active dangling wake-lock immediately:
termux-wake-unlock
Execute the following to map Android shared storage to Termux:
termux-setup-storage
When prompted on your phone screen, tap “Allow”.
The repository contains an enterprise-grade automated test suite:
pytest -v
============================== test session starts ==============================
collected 37 items
tests/test_api_sse.py::test_flask_app_routes PASSED [ 2%]
tests/test_api_sse.py::test_event_bus_pub_sub PASSED [ 5%]
tests/test_api_sse.py::test_sse_stream_pep3333_compliance PASSED [ 8%]
tests/test_api_sse.py::test_port_availability_and_fallback PASSED [ 10%]
tests/test_daemons.py::test_notification_otp_classification PASSED [ 13%]
tests/test_daemons.py::test_notification_spam_classification PASSED [ 16%]
tests/test_daemons.py::test_routine_crontab_generation PASSED [ 18%]
tests/test_extensions.py::test_extension_manager_lifecycle PASSED [ 21%]
tests/test_extensions.py::test_crypto_tracker_strategy PASSED [ 24%]
tests/test_extensions.py::test_github_monitor_strategy PASSED [ 27%]
tests/test_extensions.py::test_system_cleaner_strategy PASSED [ 29%]
tests/test_extensions.py::test_custom_dynamic_plugin PASSED [ 32%]
tests/test_extensions.py::test_react_agent_extension_heuristics PASSED [ 35%]
tests/test_extensions.py::test_api_extensions_route PASSED [ 37%]
tests/test_lru_cache.py::test_lru_cache_basic_ops PASSED [ 40%]
tests/test_lru_cache.py::test_lru_eviction PASSED [ 43%]
tests/test_lru_cache.py::test_lru_cache_thread_safety PASSED [ 45%]
tests/test_react_agent.py::test_hardware_fallback_camera PASSED [ 48%]
tests/test_react_agent.py::test_hardware_fallback_sms PASSED [ 51%]
tests/test_react_agent.py::test_react_agent_execution PASSED [ 54%]
tests/test_security.py::test_phone_number_sanitization PASSED [ 56%]
tests/test_security.py::test_url_sanitization PASSED [ 59%]
tests/test_security.py::test_string_sanitizer PASSED [ 62%]
tests/test_security.py::test_arg_vector_validation PASSED [ 64%]
tests/test_security.py::test_aes256_credential_vault PASSED [ 67%]
tests/test_security.py::test_rate_limiter PASSED [ 70%]
tests/test_security.py::test_session_timeout_manager PASSED [ 72%]
tests/test_security.py::test_permission_manager_governance PASSED [ 75%]
tests/test_simulator.py::test_simulator_hardware_status PASSED [ 78%]
tests/test_simulator.py::test_simulator_actions PASSED [ 81%]
tests/test_storage.py::test_sqlite_wal_mode PASSED [ 83%]
tests/test_storage.py::test_sliding_window_log_pruning PASSED [ 86%]
tests/test_storage.py::test_clipboard_repository_deduplication PASSED [ 89%]
tests/test_tools.py::test_tool_registry_registration PASSED [ 91%]
tests/test_tools.py::test_battery_strategy_execution PASSED [ 94%]
tests/test_torch_strategy_execution PASSED [ 97%]
tests/test_tools.py::test_sms_strategy_execution PASSED [100%]
============================== 37 passed in 15.23s ==============================
Void enforces rigorous memory constraints to sustain operation on devices with limited RAM:
| Metric | Target | Verified Benchmark | Mechanism |
|---|---|---|---|
| Allocated Python Memory | < 25 MB |
11.24 MB |
__slots__ class layout, zero unnecessary object trees |
| Peak Heap Allocation | < 50 MB |
11.51 MB |
Generator stream parsing for JSON outputs |
| Cache Memory Ceiling | Bounded | O(1) Space |
Doubly-linked list + hash map LRU eviction |
| Database Disk Footprint | Bounded | < 2.5 MB |
SQLite WAL mode + sliding-window index pruning |
Void provides an authenticated remote control plane via Telegram. To connect:
void start --telegram <BOT_TOKEN> --admin-id <YOUR_NUMERIC_ID>
Void is open-source software licensed under the Apache License 2.0.
Contributions, plugin submissions, and bug reports are welcome! Please open an issue or submit a pull request on GitHub.