English | 中文
Bothy turns an Android tablet into a personal assistant you talk to, and, with Bothy Playground, into a car's head unit. It is the demo of Android Agent Runtime, an embeddable agent runtime for Android: everything Bothy, the assistant, does goes through the runtime's public API.
▶ Watch the 12-minute demo on Bilibili (in Chinese, with chapters)
| Install | The tablet becomes |
|---|---|
| Bothy | A personal assistant. Say "OK Bothy" over any app: it looks things up on the web, plans and reminds, plays and pauses music and video, works other apps for you (Android Use) and passes any request you like to your own cloud agent, such as Grok Bot. |
| + Bothy Playground | A head unit that cannot control a car: a car's screen with AMap navigation on the device's own location (real mode), or a simulated car and home to control (simulated mode). In a car mount it plans the pickup, the stops and the reminder on arrival. |
| + your car's controls as MCP | A real head unit. Playground's virtual car is just an MCP server (set_climate, set_seat, set_window, set_trunk, …); serve your car's own control interface the same way, add it under Connect apps by address, and Bothy controls the real car as it controls the virtual one. |
Head unit not smart enough? Mount a tablet with Bothy (and Playground in real mode) and the cabin gets an assistant that plans the trip, reminds you on arrival, plays your music and runs your errands, whatever the car came with. Want more? Bothy is MIT-licensed and made to be extended: connect any MCP server, add your own skills, or fork it and build the features you want on the same runtime.
Why it is worth a look
- It plans like a person. "A friend flies in on CZ3956, pick her up, then a late-night diner": it looks the flight up, finds a place still open when she lands, routes up to 16 stops and reworks them as plans change.
- It acts on its own. Plans watch the car, the home or any server, and speak up on arrival, at a time, or when a reading crosses a line.
- It uses your apps. Android Use reads the screen and taps, swipes and types in any app; music and video obey through their media sessions.
- It brings your own agent. Name Grok Bot (or say "cloud assistant") and Bothy passes your request, whatever it is, to your own agent over A2A; the result comes back by voice.
- It draws when words are not enough: cards, choices and control panels on screen (A2UI).
- It listens properly. On-device wake word in Chinese or English, it knows which seat is speaking, you can talk over it, and an end-to-end speech model is one switch away.
- Every step is on the record. A Codex-style console replays each run, tool call by tool call.
A bothy is a small mountain shelter, open to any traveller; Bothy lives in one.
Status: 0.x, under active development.
No development setup, one model key. Both apps show English or Chinese, following the system language unless one is chosen (Bothy: Settings → General → Language; the Playground: its settings). What Bothy says on its own stays in Mandarin Chinese, and the demos below were recorded in Chinese; what is said to Bothy in them is given here in English translation.
- Install: download the latest
bothy-*.apk(Bothy) andbothy-playground-*.apk(the virtual head unit, optional) from Releases onto an Android tablet or phone (Android 7.0 or later, arm64). - Add a DeepSeek key: open Bothy; its first screen walks you through setup. Create an API key on the DeepSeek platform, paste it and tap Save and check.
- (Recommended) Add a Doubao speech key: in the Volcano Engine Doubao speech console, under Activation enable Speech Synthesis 2.0 and End-to-end Realtime Speech, then create a key under API Key in the left menu and paste it. Bothy then speaks in a natural voice and can hold an end-to-end voice conversation. Without it, Bothy speaks with the device's own voice.
- Grant permissions from the same screen: microphone and overlay are needed; notification access (to control music) and accessibility (to let Bothy operate other apps) are optional.
- Turn on the wake word under Settings → Voice (it starts off), then say "OK Bothy" and ask for tomorrow's weather in Shenzhen, a reminder at eight tomorrow to take an umbrella, or the next song. Tapping the floating Bothy or the console's mic works too; on a phone held upright, hold the mic while you talk. With Bothy Playground in front, ask it to turn on the air conditioning, open a window or plan a route in the virtual car.
| Feature | Needs |
|---|---|
| Conversation and tasks, web search, reminders and plans, memory, operating other apps, media control, calendar, cards and panels | DeepSeek key |
| Wake word, speech recognition | Nothing (on the device) |
| Bothy's voice | Nothing (the system voice); a Doubao speech key for a natural voice |
| End-to-end voice conversation | Doubao speech key |
| Playground's virtual car and home, the weather | Nothing (without an AMap key the weather comes from Open-Meteo) |
| Playground's map, navigation and place search | Your own AMap key (below) |
The Playground's map and navigation run on AMap's SDK, with a free key of your own:
- Sign in to the AMap console (a personal developer account is enough), create an app under My Apps and add a key for the Android platform.
- Enter the package
cc.noharry.bothy.playgroundand, as both the release and the debug SHA1,02:09:D5:0D:3B:C7:52:02:A2:1A:2E:E7:EB:01:5B:21:0D:74:13:5B(the signature of the APKs in Releases). A build of your own is signed differently: the Playground's settings → AMap key show its package and SHA1, ready to copy. - Paste the key into the Playground's settings → AMap key; it restarts and the map appears.
A build of your own can also carry the key as AMAP_ANDROID_KEY in local.properties (see Running the demo).
| Module | What it does |
|---|---|
bothy-app |
The demo app's screens (tablet first): debug console, phone screens, settings, floating assistant card |
bothy-server |
Bothy's server under those screens: the runtime's app server with Bothy's voice, on-device model, checks and Playground |
bothy-protocol |
What the screens and the server say to each other: the app server's protocol plus Bothy's own methods and sections |
bothy-playground |
A second demo app: a fictional car cabin and home behind a local MCP server, for Bothy to drive (below) |
The server depends on the runtime's artifacts (cc.noharry:agent-*), its app server among them: the generic server
(agent-app-server, sessions, models, MCP and a plugin kernel for any agent app to build on) and its protocol
(agent-app-protocol, in the style of Codex's app-server: threads, turns, items), experimental, with apps on it that
have no Bothy in them, are in the runtime's repository. The model services (DeepSeek among them), screen operation
and the device tools are plugins of the runtime's own published modules (agent-app-models, agent-android-use,
agent-device-capabilities), loaded from their manifests. The server's other first-party plugins (cards, pages,
memory, pictures, plans, A2A) are source modules here, in workspace/apps/android/plugins/, not published and free of
Bothy, so another app can take them as they are. The playground depends on nothing: Bothy reaches it like any other MCP
server.
The whole demo, 12 minutes with sound and chapters, is on Bilibili. Every clip below is the demo on a tablet, asked out loud; some are sped up, as each caption says.
Say "OK Bothy" and ask. While it listens, a slim bar shows the words it hears; once it takes the request, its card shows what you asked, each tool it calls and the answer. It knows who is speaking: the seat marked Speaking is yours, so "it's hot on my side" lands on it. Here "I'm a bit cold" turns the air conditioning up from 24 to 28 °C. (Real time.)
"Shenzhen North Station first, then Window of the World": Bothy finds both places by name, plans a route through them with AMap's navigation SDK, shows it whole for a few seconds, then starts a simulated drive with turn-by-turn guidance. Stops can be added, removed, replaced or reordered while driving (up to 16), and a vague name such as "the science park" is looked for around the trip's other stops. In the demo the car starts at Shenzhen Civic Center, not where the device is. (2× speed.)
The Simulated | Real switch turns the head unit into a real one: AMap's navigation screen on the device's location, with only real navigation and Bothy. "A friend flies in to Shenzhen on China Southern CZ3956; pick her up at the airport, then take her into town for a late-night bite": Bothy looks the flight up on the web (it lands at 01:10), plans the airport and a diner, and points out that the first one closes at 23:30, offering ones open until 2; "once she's picked up, drop her bags at the Futian Shangri-La first, then go eat" adds the hotel on the way and takes the late diner. "Navigate with AMap to…" hands a route to the AMap app instead. For the recording the tablet's location was set to Shenzhen Civic Center. (2× speed, cut; web search on.)
Pair your own cloud agent, such as Grok Bot, under Connect apps through the self-hosted relay in
workspace/apps/android/tools/agent-relay. Name it ("have Grok Bot…", or "cloud assistant") and Bothy passes
the request to it, whatever you ask: research, mail, reminders, shopping, anything your agent can do with your
accounts. The task goes over A2A, the conversation carries on,
and when the agent reports back Bothy reads it out; "how is Grok doing?" asks for progress. Unpaired,
Bothy can still open the agent's own app on the screen and ask it there. (1.5× speed; the wait for the report cut.)
When an answer needs a pick or a setting, Bothy sends UI instead of words (A2UI): information cards, choices and control panels the head unit draws itself. Drag, tap, confirm, and the choice goes back to Bothy, which carries it out; here 22 °C and cooling. (1.6× speed.)
The playground also has a small flat: lights, curtains and air conditioning in four rooms, a motion sensor per room, the front door lock, a robot vacuum, and scenes (home, away, sleep, movie, morning). Readings move, so the room above cools toward 25 °C and a plan like "turn the air conditioning on when the living room passes 28 °C" fires within minutes. Away from the head unit, Bothy answers in its floating card. (1.5× speed.)
With Android Use on (an accessibility service you switch on), Bothy reads the screen and taps, swipes and types in other apps. Its avatar shows where it is about to tap, and the screen's edge glows while it is in control; here it works out 23 × 47 on the calculator. (1.3× speed.)
Bothy's own screen is a developer console in the spirit of Codex. The conversation shows each tool call with its duration and what it said along the way; the board tracks the run, token usage and cache hits, the workspace, the MCP servers, memory and skills. The Trajectory tab replays a run from its durable event log: a timeline of model and tool spans, then every event in order, from the request through each model call and token count to every tool call as the model asks for it, the backend runs it and it completes, with calls that ran side by side. Here Bothy finds the passenger seat heating already off, sets the ambient light warm and checks the doors and the trunk. (1.15× speed.)
- Bring your own model: any OpenAI- or Anthropic-compatible endpoint, configured in the app; streaming, thinking, server-side web search and prompt caching where the provider offers them.
- A model on the device: the built-in On-device model service runs a small model with llama.cpp on the Snapdragon NPU, falling back to the CPU, so nothing leaves the device. None ships with the app; Settings downloads the ones you pick: Google's Gemma 4 E4B (QAT Q4_0, 5.2 GB), Alibaba's Qwen3 4B Instruct 2507 (Q4_0, 2.4 GB) or ModelBest's MiniCPM5 2B (Q8_0, 2.7 GB, thinking on), all Apache-2.0. On an 8 Elite Gen 5 tablet a turn takes a few seconds once the model is loaded; they ask more often than a cloud model and do less.
- MCP from the public internet: Connect apps lists ready-made remote MCP servers. Open ones connect with one tap and no key: Kiwi.com flight search, DeepWiki (questions about GitHub repositories), Hugging Face Hub, Context7 (library docs). Keyed ones take your own key: AMap, DiDi, McDonald's China, Luckin Coffee, Tencent Docs. Any other Streamable HTTP MCP server can be added by address.
- Skills and subagents: a multi-day trip planner fans out to transport, stay and day-plan subagents and returns one itinerary card; the main agent decides when to delegate.
- Plans: reminders and timed tasks, and watches on a server's state, either an MCP resource or a read-only tool polled on a schedule, e.g. "remind me when the cheapest Shenzhen–Chengdu flight on 7 Nov drops below 800 yuan" runs on Kiwi.com's open search.
- Voice: on-device wake word ("OK Bothy", off until you turn it on) and recognition, turn taking (an optional judge decides when you have finished and whether you are talking to Bothy), barge-in, TTS; optionally an end-to-end speech model.
- Your own cloud agent: pair a personal agent (such as Grok Bot) through the self-hosted relay in
workspace/apps/android/tools/agent-relay, then hand it tasks that need your accounts. - Offline: the demo also runs with a simulated model and the example tools in
bothy-server/src/main/assets/mcp/tools.json.
bothy-playground is a separate app that simulates a car cabin and a small flat and serves them as two MCP servers on
the device itself (http://127.0.0.1:8790/cabin/mcp and /home/mcp, Streamable HTTP, loopback only). Nothing in it
reaches a real car or a real device.
- Cabin: climate, seat heating and ventilation, windows, doors and the trunk, door locks, screen brightness and volume, ambient light, music; who sits where and who is speaking, so "it's hot on my side" lands on the speaker's seat.
- Navigation: real routing through AMap's navigation SDK with your AMap key (above): places found by name (a vague one such as "the science park" is looked for around the trip's other stops), routes through up to 16 stops, stops added, removed, replaced or reordered while driving, search along the route, and a simulated drive. Settings can park the car at Shenzhen Civic Center instead of the device's location, for a demo in the demo's city.
- A head unit: the cabin is laid out like a car's screen (the car on the left, then three columns, the climate bar below). While it is in front it takes the assistant over: Bothy hides its floating card and lives in the head unit instead. It wakes there (the wake word, or a tap on it); while it listens only a slim bar shows the words being heard; once it takes the request its card opens with what was asked, what it thinks (in Chinese), each tool it calls and what it says as it works, then the answer; a plan coming due shows there too; the X ends voice. The map moves to each place it finds, shows the planned route whole, and only then starts driving.
- Home: lights, curtains and air conditioning in four rooms, a motion sensor per room, the front door lock, a robot vacuum, and scenes (home, away, sleep, movie, morning).
- Readings that move: temperatures drift toward the air conditioning or the weather, a simulated drive drains the
battery and counts down the route, so plans such as "close every window once the car is below 24 °C"
fire within minutes. Both servers publish their state as a resource (
playground://cabin/state,playground://home/state) that Bothy's plans watch. - Everything by hand too: tap a seat to seat a passenger, long-press it to make them the speaker, tap a room for its light; the side panel has every control and reading. Manual changes show as Manual in the log and trigger plans like real ones.
To demo it: install both apps, open Bothy Playground, then in Bothy open Connect apps and connect Virtual
cabin and Virtual home, no key needed. Keep the playground in front and talk to Bothy there. Desktop MCP
clients can reach the same servers with adb forward tcp:8790 tcp:8790.
The Simulated | Real switch at the top right of the head unit changes mode at any time: simulated is the made-up car and home above; real keeps only real navigation and Bothy, on the device's own location, so a tablet in a car works. Each switch starts a new conversation, so nothing said in the other mode carries over.
Navigation needs your own AMap Android key, typed into the Playground's settings → AMap key (how to get one is above). Without it the map's place shows the way to one, the navigation tools say what is missing, and everything else works. The head unit takes the assistant over through a signature permission, so it works only when both apps are signed with the same key (see Running the demo for signing).
To send tasks to Bothy's local A2A server (http://127.0.0.1:8766/a2a), open Settings → Connections → A2A in the console, or Settings → Connectors and A2A → A2A on the phone. Show and copy the incoming access token, then send it as the Authorization: Bearer <token> request header. Requests without the token return 401.
The apps use the runtime published on Maven Central (agentRuntimeVersion in gradle.properties, 0.5.0). To build against
its source instead, clone it beside this repository: Gradle then builds it in place of the published artifacts
(settings.gradle.kts; -PagentRuntimeDir= goes back to the published version).
git clone https://github.com/NoHarry/bothy.git
cd bothy/workspace/apps/android
./gradlew :bothy-app:assembleDebug
./gradlew :bothy-playground:assembleDebug # optional: the car and home to driveModel provider presets come from bothy-server/src/main/assets/model-provider-profiles.json, which is packaged into
the APK and therefore holds no API keys. Put keys in the Git-ignored workspace/apps/android/local.properties:
# local.properties (never committed)
AGENT_RUNTIME_PROVIDER_PROFILE_DEEPSEEK_API_API_KEY=your-keyThe key name is AGENT_RUNTIME_PROVIDER_PROFILE_{PROFILE_ID}_API_KEY, the profile id upper-cased with - as _. Keys
from local.properties are compiled into the debug build for convenience; build an APK you hand to someone else with
-PbothyEmbedLocalKeys=none (or tts), or enter keys in the app instead.
Both apps are signed with the machine's own debug key unless local.properties names a signing key of your own, which
then signs debug and release builds alike, so a build from any machine installs over the last one:
BOTHY_SIGNING_STORE_FILE=/path/outside/the/repo/bothy-release.jks
BOTHY_SIGNING_STORE_PASSWORD=…
BOTHY_SIGNING_KEY_ALIAS=bothy
BOTHY_SIGNING_KEY_PASSWORD=…Keep the key file and its passwords backed up: without them a new build no longer installs over the old one.
The on-device voice models are committed (with the sherpa-onnx native libraries in bothy-voice), so
voice works out of the box on arm64 devices; tools/voice/fetch_voice_assets.py re-downloads and verifies them.
The on-device chat model's llama.cpp libraries are committed in bothy-llm; the model itself is downloaded on request.
- Demo app:
minSdk 24,compileSdk 37(core library desugaring withdesugar_jdk_libs_nio, since the runtime usesjava.nio.file) - JDK 17, Gradle 9.6, Android Gradle Plugin 9.4, Kotlin 2.4
- Tablets first; phones work too, the way they are held. Upright (smallest width under 600 dp), Bothy shows one page at
a time: the conversation under a bar with the session and the model, a one-line composer whose mic is held to talk (in
end-to-end mode it is still tapped on and off), and a side drawer for chats, plans, A2A, the head unit and settings; a
run's steps open its trajectory. The head unit, upright, shows the map over the whole screen, with Route, Cabin and
Climate in a panel at the bottom and the home and settings in its menu. Sideways, Bothy's console takes its compact
layout with the destinations in a rail and the head unit draws at three quarters of its size. Bothy's floating card
fits the upright apps it shows over. A phone emulator (arm64 image on Apple silicon) runs both apps; AMap's map needs
software rendering there (start it with
-gpu swiftshader_indirect), or it crashes when the map opens.
- LINUX DO: a Chinese tech community
MIT. Third-party components and committed model files keep their own licenses; see THIRD_PARTY_NOTICES.md.










