termux-llamacpp

Universal GGUF Runtime, Model Manager & OpenAI-Compatible Local Server for Android Termux & ARM64

Notice: This project is an independent open-source tool and is not affiliated with or endorsed by Meta Platforms, Inc.

📌 Features

• 🚀 One-Click ARM64 Compilation: Auto-detects Android Termux hardware, NEON, FP16, and DotProd SIMD capabilities with -O3 compiler optimization flags.
• 📦 GGUF Model Management & Safe Interrupt: Automatic streaming download from Hugging Face with SHA-256 checksum verification, unified model caching (~/.termux-llama/models/), and explicit ModelNotFoundError interrupts.
• 🌐 Zero-Config OpenAI Server: Built-in supervisor for llama-server exposing /health, /v1/models, and /v1/chat/completions (streaming SSE & JSON).
• 🔍 Hugging Face Discovery & Playwright Bridge: Search models directly from CLI/SDK, with optional deep crawling powered by termux-playwright.
• 🔗 Seamless Ecosystem Interoperability: Plug-and-play with termux-aichain via LocalAgent.create(mode="connect", endpoint="http://127.0.0.1:8080").

⚡ Quick Start

1. Installation

# Python
pip install termux-llamacpp

# Node.js
npm install termux-llamacpp

2. Python SDK

from termux_llamacpp import LlamaRuntime

# 1. Initialize runtime
runtime = LlamaRuntime.install(preset="android-arm64")

# 2. Download curated model preset
model_path = runtime.models.download("qwen2.5-1.5b-instruct")

# 3. Start local OpenAI-compatible server
server = runtime.serve(
    model="qwen2.5-1.5b-instruct",
    host="127.0.0.1",
    port=8080
)

print(f"OpenAI API Server is ready at {server.endpoint}")

3. Connection with termux-aichain

from termux_aichain import LocalAgent

agent = LocalAgent.create(
    mode="connect",
    endpoint="http://127.0.0.1:8080"
)

response = agent.run("Analyze Android system memory and optimize background processes.")
print(response)

🛠️ CLI Usage

# System and hardware diagnostic
termux-llama doctor

# List curated models
termux-llama models

# Search Hugging Face
termux-llama find "qwen2.5 gguf"

# Download model
termux-llama download qwen2.5-1.5b-instruct

# Start server
termux-llama serve qwen2.5-1.5b-instruct --port 8080

📄 License

Licensed under the Apache License, Version 2.0.