SAIR MCP server

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 and sair-wifi on PATH. The tools need an orchestrator account: sign up at sair.run to get an API key, store it as the repository secret SAIRAPIKEY, and set the repository variable SAIRPROXYURL 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.

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). SAIRAPIURL points it at another orchestrator (default https://api.sair.run).

Shortened. The full README is on GitHub.