Android Bridge

Overview

The Allternit Android Bridge is a local HTTP service that exposes a real Android device to the Allternit runtime. It wraps the phone-harness-android ADB harness and lets agents and sidecars send SMS, read messages, take screenshots, tap elements, type text, and press hardware keys — all through a small REST API. The bridge is typically consumed by the Open Connector sidecar so that agents can interact with mobile apps and messaging workflows without handling ADB directly.

The Android Bridge runs on a host with an authorized Android device attached over USB or ADB-over-network. Screenshots, messages, and device state stay on that host.

How it works

An Android device is connected to a host machine and authorized for ADB.
The phone-harness-android harness provides low-level ADB helpers such as screenshot, tap_text, and _adb.
The Android Bridge exposes those helpers as FastAPI endpoints on 127.0.0.1.
The Allternit runtime or sidecar calls the bridge over HTTP to perform mobile actions remotely.

Installation

Requirements

Python 3.10+
ADB installed and on the host PATH
An Android device with USB debugging enabled and authorized
The phone-harness-android harness checked out on the host

Install dependencies

cd /Users/joe/Desktop/allternit-workspace/allternit/services/android-bridge
pip install fastapi pydantic uvicorn

Start the service

HARNESS_PATH=/Users/joe/phone-harness-android PORT=8020 python main.py

By default the service binds to 127.0.0.1:8020 and looks for the harness at /Users/joe/phone-harness-android.

Configuration

Variable	Default	Description
`HARNESS_PATH`	`/Users/joe/phone-harness-android`	Directory containing `harness.py`
`PORT`	`8020`	HTTP listen port

The harness directory must contain a harness.py module with at least the following helpers:

check_device() — returns True when an authorized Android device is connected
press_home() — presses the home key
wait_stable(seconds) — waits briefly for the UI to settle
_adb(args, **kwargs) — runs an adb command and returns the result
screenshot(path) — writes a PNG screenshot to path
tap_text(text, screenshot_path) — OCR-taps the first matching text on screen

Endpoints

Method	Path	Description
GET	`/health`	Service and device readiness
POST	`/send-sms`	Send an SMS to a phone number
GET	`/messages`	Read recent SMS from the inbox
GET	`/screenshot`	Capture the device screen as a base64 PNG
POST	`/tap`	Tap OCR-matched text or absolute coordinates
POST	`/type`	Type text into the focused field
POST	`/press-key`	Press a hardware or navigation key

Health check

curl http://127.0.0.1:8020/health

Response:

{
  "ok": true,
  "ready": true,
  "harness_dir": "/Users/joe/phone-harness-android"
}

ready is true only when the harness loaded successfully and an authorized device is connected.

Send an SMS

curl -X POST http://127.0.0.1:8020/send-sms \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+15551234567",
    "body": "Hello from Allternit"
  }'

Response:

{
  "sent": true,
  "to": "+15551234567"
}

The endpoint opens the default SMS app, focuses the message body, types the text, and presses send. The device must have an active SMS plan.

Read messages

curl "http://127.0.0.1:8020/messages?limit=10"

Response:

{
  "messages": [
    {
      "address": "+15551234567",
      "date": "1712345678901",
      "body": "Hello from Allternit"
    }
  ]
}

Reading SMS uses the content://sms/inbox provider. Some devices require root access for this query to succeed.

Screenshot

curl http://127.0.0.1:8020/screenshot

Response:

{
  "image": "iVBORw0KGgoAAAANSUhEUgAA...",
  "format": "png"
}

The image is returned as a base64-encoded PNG and can be passed directly to vision-capable agents or saved to disk.

Tap

Tap by OCR text:

curl -X POST http://127.0.0.1:8020/tap \
  -H "Content-Type: application/json" \
  -d '{"text": "Send"}'

Tap by absolute coordinates:

curl -X POST http://127.0.0.1:8020/tap \
  -H "Content-Type: application/json" \
  -d '{"x": 540, "y": 1200}'

Response:

{
  "tapped": true,
  "text": "Send"
}

When text is provided, the bridge takes a screenshot and uses the harness to locate and tap the first matching text. If the text is not found, the endpoint returns HTTP 404.

Type text

curl -X POST http://127.0.0.1:8020/type \
  -H "Content-Type: application/json" \
  -d '{"text": "hello world"}'

Response:

{
  "typed": true,
  "length": 11
}

Spaces are escaped for ADB input (%s) before the command is sent.

Press a key

Supported keys: home, back, recent, power, menu.

curl -X POST http://127.0.0.1:8020/press-key \
  -H "Content-Type: application/json" \
  -d '{"key": "home"}'

Response:

{
  "pressed": "home"
}

Error handling

HTTP	Message	Meaning
200	—	Request succeeded
400	`Provide text or x/y coordinates`	Tap request missing both fields
400	`Unknown key: ...`	Key not in the supported key map
404	`Text '...' not found on screen`	OCR tap target not visible
500	`Failed to send SMS: ...`	SMS flow failed on the device
500	`Could not read SMS: ...`	Content provider query failed
503	`Android harness unavailable: ...`	Harness could not be imported
503	`No authorized Android device connected`	Device offline or not authorized

Integrating with the runtime

The Android Bridge is normally consumed through the Open Connector sidecar as an action or MCP tool. A minimal tool registration maps each bridge endpoint to a typed function:

import { ToolRegistry } from '@allternit/sdk/ai-runtime/tools';

registry.register({
  name: 'android_screenshot',
  description: 'Take a screenshot of the connected Android device',
  inputSchema: { type: 'object', properties: {} },
  execute: async () => {
    const res = await fetch('http://127.0.0.1:8020/screenshot');
    return res.json();
  },
});

For local-only use, you can also call the bridge directly from a custom tool or workflow step.

Security considerations

The bridge binds to 127.0.0.1 by default and has no built-in authentication. Only run it on trusted hosts or behind a gateway that enforces auth.
ADB authorization is handled by the Android device itself. An unauthorized device cannot be controlled until the RSA key dialog is accepted on the device.
SMS and screenshots contain sensitive data. Keep the bridge on the same host as the device and avoid exposing it to untrusted networks.

Get Started

Core Concepts

Gizzi Code CLI

Tools & ACI

Security & Enterprise

Admin API

BYOC Runtime

Surfaces

CI CD

Guides

Cookbooks

Release Notes

Overview

How it works

Installation

Requirements

Install dependencies

Start the service

Configuration

Endpoints

Health check

Send an SMS

Read messages

Screenshot

Tap

Type text

Press a key

Error handling

Integrating with the runtime

Security considerations

​Overview

​How it works

​Installation

​Requirements

​Install dependencies

​Start the service

​Configuration

​Endpoints

​Health check

​Send an SMS

​Read messages

​Screenshot

​Tap

​Type text

​Press a key

​Error handling

​Integrating with the runtime

​Security considerations

​Related pages

Overview

How it works

Installation

Requirements

Install dependencies

Start the service

Configuration

Endpoints

Health check

Send an SMS

Read messages

Screenshot

Tap

Type text

Press a key

Error handling

Integrating with the runtime

Security considerations

Related pages