# Agent Device Preflight > This skill should be used when the user asks to "connect my phone to agent-device", "attach a device to agent-device", "why can't agent-device see my iPhone/iPad", "why can't agent-device see my Pixel/Android phone", "agent-device doctor passes but open fails", "developer disk image could not be mounted", "No Account for Team", "this provisioning profile cannot be installed on this device", "xcodebuild build-for-testing failed", "No Android devices found", "adb says unauthorized", "agent-device snapshot times out", "Daemon request timed out", "agent-device is targeting the simulator instead of my phone", "the same signing error repeats after I fixed it", or is setting up agent-device against a physical iOS or Android device for the first time. Resolves the environment prerequisites that must hold before `agent-device open` can attach; hands command-level work back to the CLI. Pass the user's request verbatim — this skill reads a free-form request, not a subcommand. - Skill: `jongwony/agent-device-preflight` (Agent Skill, multi-file: 4 files) - Install (CLI): `npx skillmds@latest add jongwony/agent-device-preflight` - Raw SKILL.md: https://api.skillmd.com/api/skills/jongwony/agent-device-preflight/raw - Safety review: pending (external: skill-scanner PASS, skillspector PASS) - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: AI & ML - Author: jongwony (https://skillmd.com/u/jongwony) - Updated: 2026-09-10 - Page: https://skillmd.com/skills/jongwony/agent-device-preflight --- # agent-device Preflight Bring the local environment to the state `agent-device` needs, then get out of the way. ## Scope Guard This skill covers **attachment prerequisites only** — what must hold before `agent-device open` can reach a device. Some of it is one-time setup (toolchain, signing, developer mode); the rest is per-run state that goes stale on its own — lock state, session identity, ownership claims, and the daemon's captured environment. It deliberately holds **no post-attachment command catalog**. The few commands here exist to establish or inspect the preconditions themselves. Once preflight passes, defer to `agent-device help `. Do not duplicate the command surface here — it moves faster than any static copy. Three reasons this layer exists rather than being covered by what already ships: - `agent-device doctor` covers almost none of the platform checks — on iOS it reaches only the CLI's own presence. - The MCP server does not expose the connection surface, so a shell must drive attachment. - Failures in this set are reported with actively misleading text on both platforms. iOS blames the screen for a signing failure; Android reports "no devices found" for a device that is connected and listed. Following either wastes the session. ## Platform Run the shared checks below, then read **exactly one** platform file: | Target | Read | |---|---| | Physical iPhone or iPad | `references/ios-preflight.md` | | Physical Android device | `references/android-preflight.md` | Read only the one you need, and do not carry conclusions across. The two platforms disagree at nearly every corresponding step — which selector works, whether signing exists at all, how a locked device announces itself, what a slow first snapshot means. Applying an iOS habit on Android (or the reverse) produces failures whose error text points somewhere else entirely. ## Shared checks ### CLI present and recent enough ```bash agent-device --version # must be >= 0.20.0 ``` Missing or older than 0.20.0 → **stop.** Do not run `npm install -g agent-device@latest` or `npx -y agent-device@latest` autonomously, and do not put a version or upgrade command in a plan — upstream's own skill forbids both. Ask the user to upgrade their trusted install, or to approve an exact-version command they run themselves. Requires Node 22.12+ (24+ for web). ### A matching `version` field does not mean matching code `package.json` keeps the last released version until the next bump, so a `main` checkout and an installed npm build can both read `0.20.3` and differ. Verify behaviour against the installed `dist/`, not the repository, when the two could disagree. ### Sessions are named from the working directory With no `--session`, the default session name derives from a hash of the current directory (`cwd::default`). The same command run from a different directory therefore targets a *different* session, and `doctor` will say so: ``` - session: No active session named cwd::default. Doctor will use device inventory only. ``` Pass `--session ` explicitly for any multi-step run, so the session does not move when the shell does. Device ownership claims can also outlive their owner: ```bash agent-device device status # summarises; hides stale entries agent-device device status --stale # shows them, e.g. owner-process-dead ``` A dead-owner claim from an earlier session lingers in this state. It is advisory, so it does not block on its own — but read it before concluding that something else is holding the device. ### The daemon captures the environment it was spawned with The daemon starts lazily on the first command and keeps the environment it was spawned with. Exporting a corrected `AGENT_DEVICE_*` value into your shell does nothing for an already-running daemon. ```bash agent-device daemon stop # there is no `daemon start`; the next command respawns it ``` `references/ios-preflight.md` item 7 covers which variables this actually bites on there, and how to confirm what the daemon used. Android sets none of the `AGENT_DEVICE_*` variables this matters for, so its file carries no counterpart. ### Sandbox The daemon binds to localhost, and in one sandboxed agent shell that failed with `listen EPERM`. Because `doctor` starts the daemon too, the failure strands everything downstream of it. It is not a property of every sandbox — a full run has since gone through one untouched. So treat `listen EPERM` as the signal to re-run that shell unsandboxed, rather than moving all agent-device work out of the sandbox pre-emptively. ## Handoff Each platform file contains a Verify step. The snapshot is the real gate — `doctor` passing proves considerably less. Once it passes, hand off: `agent-device help workflow`. ## Scope not covered Web, the remote/cloud lease providers, and `proxy` are outside this preflight on every platform. Platform-specific exclusions are named in each platform file, alongside the verification domain that file's evidence actually ranged over.