Live Rei Android

Live Rei Android turns an Android phone into a visible body for an AI agent.

The phone is not the brain. The brain stays on a host machine: your laptop, desktop, home server, or another box that runs the model, tools, memory, and text-to-speech path. The Android device gives that brain a place to appear: a home-screen surface, microphone, speaker, status terminal, and direct controls.

This repository contains the Android client and a tiny sample bridge.

Package: ai.hermes.liverei Target: Android 8.0+ device used as a physical surface License: MIT

Why this exists

A chat bot is easy to lose. It lives in a tab, a terminal, or a messaging app. That is fine for occasional commands, but it does not feel like a present assistant.

Live Rei Android is for a different setup:

• Keep an agent visible on a dedicated phone.
• Give the agent a stable home surface instead of another chat window.
• Use the phone for microphone, speaker, touch, and quick status.
• Keep model routing, tools, credentials, and memory on the host machine.
• Avoid root, custom ROMs, and system-level Android changes until a measured limitation requires them.

This is the app-first version of a physical AI device. The Android side is intentionally small. It should be easy to build, install, test, adapt, and remove.

System model

Android phone
  Live Rei app
  microphone, speaker, display, buttons
        |
        | HTTP bridge
        v
Host machine
  bridge on port 18790
  model runtime, tools, memory, optional TTS path

The Android app handles the body. The host handles the mind.

What the current app does

Current features:

• foreground home-surface UI
• animated Rei sprite states
• terminal-style status output
• CHECK bridge smoke request
• TALK foreground speech input
• foreground wake phrase handling while the app is visible
• bridge TTS playback when available
• Android device TTS fallback when bridge TTS fails
• NOTE one-shot spoken note cleanup and clipboard copy

The app declares only these runtime permissions:

• android.permission.INTERNET
• android.permission.RECORD_AUDIO

RECORD_AUDIO is used for visible foreground speech input. This build is not a background listener.

What this is not

This app is not:

• a local LLM runtime
• a replacement Android OS
• a root or custom ROM project
• a background always-listening assistant
• a lock-screen assistant
• a notification reader
• an image-input client

Those can be separate slices later, but they are not part of this build.

Bridge contract

The app expects a small HTTP bridge.

Required endpoints:

GET  /health
POST /v1/chat
POST /v1/tts

Chat request body:

{
  "session_id": "live-rei-android-smoke",
  "text": "Reply with OK only.",
  "history": []
}

Chat responses are read as server-sent-event style lines:

data: {"type":"delta","text":"OK"}
data: {"type":"done"}

The TTS endpoint should return audio bytes. If it fails, Android falls back to device TTS where available.

See docs/BRIDGE.md for the compact bridge reference.

Bridge routes

The client checks bridge routes in this order:

1. adb reverse: http://127.0.0.1:18790
2. android emulator: http://10.0.2.2:18790
3. lan example: http://192.168.1.100:18790
4. tailscale example: http://your-host.your-tailnet.ts.net:18790

For your own deployment, change the route constants in:

app/src/main/java/ai/hermes/liverei/bridge/BridgeClient.kt

Do not put keys in source code. If your bridge needs bearer auth, use the token provider path and keep values out of UI logs, screenshots, and commits.

Quick local bridge

For a first smoke test, run the sample bridge on your host:

python3 examples/minimal-bridge.py

Then use one of these network paths:

• physical device over USB: adb reverse tcp:18790 tcp:18790
• emulator: keep the 10.0.2.2 route
• LAN device: replace 192.168.1.100 with your host IP
• private mesh network: replace your-host.your-tailnet.ts.net with your hostname

The sample bridge returns a short text reply and intentionally does not implement real TTS audio. The app should fall back to Android device TTS.

How to adapt this to your own agent

1. Run a bridge on the host

Start a host bridge that exposes /health, /v1/chat, and /v1/tts on port 18790.

The host should own:

• model routing
• tool access
• memory
• credentials
• TTS generation if you use bridge TTS

The phone should not need direct access to those internals.

2. Choose the network path

For local debugging with USB:

adb reverse tcp:18790 tcp:18790

For an emulator, use http://10.0.2.2:18790.

For a phone on the same LAN, use the LAN route and make sure the phone can reach the host IP.

For remote demos, use a private network path such as Tailscale and set the route constants accordingly.

3. Build the APK

source scripts/android-env.sh
./gradlew --no-daemon :app:assembleDebug

Debug APK output:

app/build/outputs/apk/debug/app-debug.apk

4. Verify before installing

bash verify.sh
bash prove.sh

verify.sh checks source hygiene and compiles the debug APK. prove.sh builds the APK and inspects package, launcher, and permission boundaries.

5. Install on the Android device

adb install -r app/build/outputs/apk/debug/app-debug.apk

If Android reports a signing conflict, uninstall the old debug build and install again.

6. Use it as the agent surface

1. Open Live Rei.
2. Optionally set it as the Android home app.
3. Wait for the bridge state to settle.
4. Tap CHECK to confirm the bridge path.
5. Tap TALK, or use a foreground wake phrase while the app is visible.
6. Keep the screen on during voice input.

Accepted wake starts include:

• Hey Ray
• Hey Rei
• Wake up Ray
• Wake up Rei
• Ray, come here
• Ray, listen

Speech recognition tolerance is intentional. Ray, Rei, and Rey are treated as equivalent starts in the foreground listener.

See docs/OPERATION.md for the operator checklist.

Repository layout

app/                         Android application source and resources
docs/                        Compact bridge and operation docs
examples/minimal-bridge.py   Tiny standard-library bridge for smoke tests
gradle/                      Gradle wrapper files
scripts/android-env.sh       Local Android toolchain environment
verify.sh                    Source and build verification
prove.sh                     APK package, launcher, and permission proof

This repository is intentionally source-facing. Planning logs, review transcripts, proof screenshots, local install bundles, generated APKs, and rollback artifacts are excluded.

Contributing

See CONTRIBUTING.md before changing routes, permissions, bridge payloads, or speech behavior.

Rollback

This app is app-first. Normal device rollback is simple:

adb uninstall ai.hermes.liverei

For repository rollback, revert the commit that changed the app or docs:

git revert <commit-sha>
git push origin main