SAIR

SAIR — Shared Android Instrumented Runner

SAIR lets CI pipelines safely share physical Android devices. It provides device locking, ADB protocol translation, and per-runner isolation so multiple jobs never collide on the same device.

Why

Without SAIR, every CI job that can see a phone uses it at the same time:

CI job 1 ──┐

├──▶ adb ──▶ Phone ✗ both jobs install / uninstall the same APK CI job 2 ──┘ ✗ one job's reboot or settings change breaks the other's tests mid-run ✗ connectedCheck runs on every attached phone, including ones another job is using

With SAIR, a job must hold a lock before it sees a device, and waiting jobs queue:

CI job 1 ──┐                 ┌──▶ Phone A (locked by job 1)

├──▶ Proxy ───────┤ CI job 2 ──┘ ▲ └──▶ Phone B (locked by job 2) │ locks CI job 3 ··· Orchestrator: job 3 waits in the queue until a phone is released

GitHub Action

This repo is also a GitHub Action that puts sair-acquire, sair-release, sair-wifi, sair-bluetooth, sair-locks and sair-label on PATH. The tools need an orchestrator account: sign up at sair.run to get an API key, store it as the repository secret SAIR_API_KEY, and set the repository variable SAIR_PROXY_URL to your bench's proxy (see Run). Then:

steps:

• uses: actions/checkout@v4
• uses: compscidr/sair@v0.1.18
• run: sair-acquire --count 1 > /dev/null env: SAIR_PROXY_URL: ${{ vars.SAIR_PROXY_URL }} SAIR_API_KEY: ${{ secrets.SAIR_API_KEY }}
• run: ./gradlew connectedCheck
• if: always() run: sair-release --status ${{ job.status }} env: SAIR_API_KEY: ${{ secrets.SAIR_API_KEY }}

The full workflow example explains each step.

A runner with no proxy of its own (e.g. GitHub-hosted, using phones other accounts share) can have the action start one, at the same release as the action. Leave SAIR_PROXY_URL unset; the proxy listens on the default localhost:8550, and its log is at $RUNNER_TEMP/sair-proxy.log:

  - uses: compscidr/sair@v0.1.18

with: proxy: true env: SAIR_API_KEY: ${{ secrets.SAIR_API_KEY }}

Used at a branch or SHA rather than a release tag, the action warns and starts the latest release instead.

AI agents (MCP)

sair-mcp is an MCP server (stdio) for coding agents. It can run an app's instrumented tests on a real phone in one call, or lease a phone and install APKs, run shell commands, take screenshots and read logcat on it. It talks to the orchestrator's agent API with an API key from sair.run. The agent's machine needs no proxy or adb.

Install it with go install github.com/compscidr/sair/cmd/sair-mcp@latest, take sair-mcp from a release tarball, or use sair-mcp.mcpb from a release (an MCP Bundle for clients such as Claude Desktop). Then add it to your agent, e.g. Claude Code:

claude mcp add sair -e SAIR_API_KEY=sair_... -- sair-mcp

or any client's JSON config:

{ "mcpServers": { "sair": { "command": "sair-mcp", "env": { "SAIR_API_KEY": "sair_..." } } } }

The server heartbeats the leases it takes, so an agent that thinks for a while between calls keeps its phone. A lease still ends at the plan's maximum (free 15 min, solo 1 h, team 2 h, enterprise 4 h). On a phone shared by another user, shell commands are limited to a safe set (see the orchestrator README). SAIR_API_URL points it at another orchestrator (default https://api.sair.run).

It is listed in the official MCP registry as io.github.compscidr/sair. Every release publishes it: the release workflow builds sair-mcp.mcpb, fills server.json's version, download URL and SHA-256 (the values in the repo are placeholders), and publishes it with mcp-publisher, logged in through GitHub OIDC. Check it with curl "https://registry.modelcontextprotocol.io/v0/servers?search=io.github.compscidr/sair".

Quick Start

Install

curl -fsSL https://raw.githubusercontent.com/compscidr/sair/main/install.sh | bash

This detects your OS and architecture, downloads the latest release, and installs all binaries to ~/.local/bin.

Prerequisites

• adb installed on the machine with Android devices
• One or more Android devices connected via USB with USB debugging enabled (don't sign them in to a personal account: see Securing a bench)

Run

# 1. Start a real ADB server on a non-default port (5038), so it doesn't

conflict with the proxy which will own the standard port (5037).

adb -P 5038 start-server

2. Set your API key (shared by proxy and device-source)

export SAIR_API_KEY=your-api-key

3. Start the proxy and device source

sair-proxy & sair-device-source

The proxy connects to the hosted orchestrator at orchestrator.sair.run by default (with TLS). Override with ORCHESTRATOR_ADDR for local development.

Use

Acquire a device lock (blocks until one is available), run your tests, then release:

ACQUIRE_OUTPUT=$(sair-acquire)

eval "$ACQUIRE_OUTPUT" ./gradlew connectedCheck sair-release

After eval, stock adb automatically talks to the proxy through the scoped port and only sees the locked devices.

When the bench sets WIFI_SSID on the device source, Wi-Fi is managed for you:

• On acquire each phone joins the bench Wi-Fi and the acquire returns only once the phone is *online* (below); it fails otherwise. --no-wifi hands it over *offline* instead, verified the same way rather than trusting the previous release. --wifi-band 2.4|5|6 (also sair-wifi on --band) joins on that GHz band: the phone scans, the suggestion is pinned to the strongest BSSID of WIFI_SSID it sees in the band, and the join fails if it sees none. The phone's cmd wifi status shows the BSSID and frequency it joined.
• On release, and when a lock expires or is cancelled, each phone is reset: every suggestion added through adb shell and every saved network is forgotten and the radio is toggled, and the reset waits until the phone is offline with the radio back on. The next job never inherits the last one's network. The phone then rejoins the bench Wi-Fi, so it is online between leases and app updates can install (see the Play Store below); the next acquire puts it in the state that job asked for either way.
• Also on release, every third-party package the phone did not have when the device source first saw it is uninstalled (test APKs and .test packages included, with their app data and signed-in accounts), and the browser and mail apps are force-stopped; see BASELINE_PACKAGES, RESET_FORCE_STOP and RESET_CLEAR_PACKAGES. What was removed is written to the proxy log and the lock's log on the orchestrator, naming any Wi-Fi suggestion that went with a package. This runs before the Wi-Fi reset, so a suggestion a test app leaked for the bench network is gone before the reset waits for the phone to be offline.
• A phone relayed to a borrower resets differently: the first relay under a lock lists its third-party packages, and when the lock ends only what is not on that list is uninstalled, for the primary user only. An app on the phone before a lock's first relay stays; one installed during the lock goes, whoever installed it. BASELINE_PACKAGES has no effect on this reset, but a local or guest-key lock on the same phone still resets to the baseline, so list apps to keep in BASELINE_PACKAGES. What was removed goes to the proxy log and the bench events, not the lock's log, which is on the holder's proxy. Without that list (it could not be read, the device source is older than the proxy, or no relay got that far) nothing is uninstalled: the proxy logs a warning and reports a failed package reset. Leftovers can then survive until a local lock, because the next borrower's list includes them, as it does when a relay under a new lock arrives before the previous lock's reset (the proxy warns, naming what it suspects).
• On acquire the same cleanup runs first (reverse forwards, packages), before the Wi-Fi check. A job that never released, because it had no if: always() release step, its runner died, or the proxy was down when the lock expired, is cleaned up by the next job, whose lock log then shows sair: uninstalled … (left by an earlier job). This is local locks only: a relayed lock's next job cleans up nothing.
• No leaked UiAutomation, on release and on acquire: a killed am instrument or a leftover uiautomator server can leave a UiAutomation registered, failing every later instrumentation with UiAutomationService … already registered!. A uiautomator dump probe detects it; sair then kills the shell user's app_process/uiautomator processes, which unregisters it, and reboots only if the probe still fails (never a phone with a secure lock). The lock log gets sair: cleared a leaked UiAutomation registration (killed … | rebooted).
• Awake and unlocked, on acquire and again after the release reset: the screen is woken and the keyguard dismissed, then verified (dumpsys power says Awake, dumpsys window policy says the keyguard is not showing), with up to three attempts since a one-shot dismiss can race on some phones. A phone whose keyguard stays up fails the acquire with screen locked; that means a PIN, pattern or password is set, which sair cannot dismiss, so set the phone's screen lock to Swipe or None. The reason is also reported as the device's warning (proxy /status, device report) until a wake succeeds. A phone with stay_on_while_plugged_in off is logged as a warning, since it will sleep and re-lock between steps. Android 4.x phones (no wm) are verified through their own mShowingLockscreen field; a dump in a format sair does not know is logged once and treated as unlocked.
• Rebooted on release once its uptime is over REBOOT_UPTIME_HOURS (24 by default), while the phone is unacquired: the reset waits for the boot and the wake above before the next acquire of that phone can proceed, and the phone is not offered while it is down. The lock log gets sair: rebooted after release (uptime …) and the proxy's /status lists each phone's last_reboot. This runs before the Wi-Fi reset, so the offline wait is not spent twice. A phone with a PIN, pattern or password is never rebooted this way, since it would come back on "unlock to start" and need a human; the device source logs that with the fix. The wake and the reboot run whether or not the bench manages Wi-Fi.
• Bluetooth cycled on release, after the Wi-Fi reset: svc bluetooth disable, wait until dumpsys bluetooth_manager says the adapter is fully OFF, svc bluetooth enable, wait until it says ON (30 s each). A BLE stack an earlier job wedged (stuck advertisers, a scanner that neve