Native-Bridge

Break the Chroot isolation. Control Android Host directly from your Linux Environment.

Native-Bridge establishes a direct, high-performance communication channel between a Chrooted Linux Environment (like Ubuntu/Debian via Termux) and the Android Host System.

Originally written in Rust, this project has been completely rewritten in pure C. It now boasts a zero-dependency architecture, a tiny memory footprint (a few KBs), dynamic path configurations, and AI Agent support via the Model Context Protocol (MCP).

Why Native-Bridge?

By default, a Chroot Environment is strictly isolated. It lives in a separate filesystem "jail" and cannot access the Android System, hardware inputs, or global settings.

Native-Bridge solves this by creating a secure tunnel (Unix Domain Socket) that allows you to:

• Bypass Isolation: Execute commands on the Android System directly from your Chroot Terminal.
• Direct Kernel Injection: Perform high-speed input injection (Tap/Swipe) by writing directly to /dev/input/event*, bypassing the heavy Android Framework (Java) for near zero-latency.
• Zero Dependencies: No heavy binaries, no external libraries. Uses a custom lightweight TLV binary protocol.
• Dynamic Configuration: No more hardcoded paths! Configure sockets and touch devices on the fly via CLI arguments and Environment Variables.
• AI-Ready: Includes an optional MCP (Model Context Protocol) server, allowing AI Agents (like Claude or Cursor) to directly interact with your Android device.

Architecture

graph LR
   A[Android Host / Root] -- Listens on Unix Socket --> B((nativeb_server))
   C[Chroot Linux / Client] -- Sends Binary Payload via 'andro' --> B
   D[AI Agent / Claude] -- Sends JSON-RPC via 'nativeb_mcp' --> B
   B -- Direct Kernel Write / Shell Exec --> A
   A -- Returns Output --> C & D

Loading

Prerequisites

• Rooted Android Device (KernelSu / Magisk / APatch).
• Chroot Environment (Ubuntu, Debian, Kali, Fedora, etc).
• GCC & Make (sudo apt install build-essential).

Building from Source

Since we use pure C (POSIX standard), compiling is extremely fast and straightforward.

1. Standard Build

Build the Server (nativeb_server) and the Client CLI (andro).

make

2. Build with MCP (AI Support)

If you want to allow AI Agents to control your Android device, build the optional MCP target:

make mcp

3. Clean Build

make clean

All compiled binaries will be located in the build/ directory.

---

Installation & Setup

1. Setup Server (Android Host)

The server must run on the Android Host (outside the Chroot) as root.

First, copy the compiled server binary to a location Android can execute:

# [Inside Chroot Terminal]
cp build/nativeb_server /tmp/nativeb_server

Now, open a separate terminal (Termux or ADB Shell) that is NOT inside Chroot:

# [Inside Android Termux/ADB]
su
cp /data/local/tmp/chrootubuntu/tmp/nativeb_server /data/local/tmp/
chmod +x /data/local/tmp/nativeb_server

# Run the server in the background
# -s : Path to the shared socket (MUST be inside your chroot directory)
# -d : (Optional) Path to your touchscreen event device
/data/local/tmp/nativeb_server -s /data/local/tmp/chrootubuntu/tmp/bridge.sock -d /dev/input/event2 &

Tip: Use getevent -pl in Termux to find your correct /dev/input/eventX for the touchscreen.

2. Setup Client (Chroot)

The client lives inside your Chroot environment.

# [Inside Chroot Terminal]
sudo cp build/andro /usr/local/bin/andro

# Tell the client where the socket is by adding this to your ~/.bashrc or ~/.zshrc
echo 'export BRIDGE_SOCKET="/tmp/bridge.sock"' >> ~/.bashrc
source ~/.bashrc

---

Usage

Simply call andro followed by the subcommand.

1. General Execution

Run any command as if you were in the Android Root Shell.

# Check User Identity
andro -e id

# Check Battery Status
andro -e dumpsys battery

# Capture Screenshot to Chroot
andro -e screencap -p > /home/user/capture.png

# Stream Logcat Real-Time
andro -s logcat

2. Direct Input (Kernel Injection)

Requires the server to be started with the -d /dev/input/eventX flag.

# Tap (Instant click at X=500, Y=500)
andro tap 500 500

# Swipe (Scroll down)
# Format: swipe <x1> <y1> <x2> <y2> <duration_ms>
andro swipe 500 1500 500 500 300

3. Utilities

# Check if server is alive
andro ping

---

MCP Integration (For AI Agents)

Native-Bridge includes nativeb_mcp, a zero-dependency JSON-RPC server that translates AI commands into Android Host actions safely.

To use it with Claude Desktop or Cursor, add the following to your MCP configuration file (e.g., claude_desktop_config.json):

{
  "mcpServers": {
    "android-bridge": {
      "command": "/path/to/your/chroot/build/nativeb_mcp",
      "env": {
        "BRIDGE_SOCKET": "/tmp/bridge.sock"
      }
    }
  }
}

Security Note: The MCP server includes a command blacklist that blocks destructive commands from the AI agent. The blacklist is configurable via a JSON file (see below) — by default it is empty (nothing is blocked), so configure it before exposing the MCP server to agents.

Configuring the command blacklist

The MCP server loads its blacklist at startup from ~/.config/native-bridge/blacklist.json (on where nativeb_mcp runs). You can override the path with the NATIVE_BRIDGE_CONFIG environment variable. If no config file is found, the built-in default applies (an empty list — nothing is blocked). If an explicitly-specified config file is missing or malformed, the server refuses to start; an auto-discovered malformed file is ignored with a warning and the defaults are used.

Format (copy blacklist.example.json for a starter):

{
  "blocked_commands": ["reboot"]
}

Entries replace the default — an empty list blocks nothing. Commands are matched by exact name or by basename. Restart the MCP server after editing. Keep the file readable only by you (e.g. chmod 600) since it defines the agent's command policy.

Troubleshooting

"Failed to connect to /tmp/bridge.sock"

• Ensure nativeb_server is running on the Android Host.
• Ensure the BRIDGE_SOCKET environment variable in your Chroot matches the -s path you provided to the server.

Tap/Swipe not working

• Did you pass the -d argument when starting the server?
• Is it the correct event number? Use getevent -pl to verify which event ID corresponds to your touchscreen.

License

This project is licensed under the Apache License 2.0 - see theLICENSE file for details.