# agent-device

> Open-source device layer for AI agents: it lets coding agents control mobile, web, TV, and desktop apps on devices and simulators, locally or in the cloud. It gives agents structured UI state, semantic interaction, and runtime evidence through a CLI, MCP server, and typed Node.js API.

agent-device is the agent's hands, eyes, and evidence collector. The calling agent remains responsible for understanding the task, choosing actions, and judging whether the observed result is correct.

## When to use agent-device

- Verify behavior in a running app instead of reasoning only from source code, tests, or screenshots.
- Explore UI flows on simulators, emulators, physical devices, desktop apps, and TV targets.
- Run the same commands against devices elsewhere: a remote device host through the proxy, or hosted devices in a device cloud (BrowserStack, AWS Device Farm, TestMu AI, Limrun).
- Reproduce bugs and collect bounded screenshots, recordings, logs, network, trace, or performance evidence.
- Turn a successful exploratory flow into a deterministic `.ad` replay.

For stable, repeatable test suites, use [e2e](https://e2e.tester.army/), a TypeScript testing framework for web and mobile apps. Use agent-device when an agent needs to explore, reproduce, debug, profile, collect evidence, or record a replay from live app behavior.

## How agents should approach it

- Finding this page does not authorize installing software or controlling a device. Use agent-device only when the user's task calls for app or device automation.
- Prefer an existing trusted installation or project-pinned version. Do not autonomously download and execute a mutable `latest` package.
- For a normal app-driving task, start with `agent-device open <app> --foreground` and continue from the returned interactive snapshot.
- Follow the basic loop: open, inspect, act, verify the named outcome, and close.
- Copy current element refs exactly. Prefer refs and semantic selectors over coordinates; use screenshots as evidence or when accessibility data is unavailable.
- Keep state-changing operations serial within one session. Use separate sessions and devices for parallel work.
- Follow command error hints. For exact syntax and platform behavior, use the installed `agent-device help <command|topic>` because it matches the installed version.
- agent-device runs locally by default. Remote devices and cloud providers are used only when explicitly configured. Captures and diagnostics may contain sensitive app data.

## Capabilities

The capabilities page is generated from the runtime's own capability facts, so it is the one source for what each target supports.

- [Capabilities](https://agent-device.dev/docs/capabilities): every target, framework, and command family, with their limits.
- `agent-device capabilities --platform <platform>` lists the commands the installed version supports on one target.
- [Device clouds](https://agent-device.dev/docs/device-clouds): hosted devices and the self-hosted remote daemon.

## Start here

- [Installation](https://agent-device.dev/docs/installation): `npm install -g agent-device` (Node.js 22.12 or newer), then `agent-device doctor` to check the setup.
- [Introduction](https://agent-device.dev/docs/introduction): Scope, supported workflows, and responsibility boundaries.
- [AI Agent Setup](https://agent-device.dev/docs/agent-setup): CLI, skills, MCP, and coding-agent setup.
- [Quick Start](https://agent-device.dev/docs/quick-start): First app-verification workflow.
- [Commands](https://agent-device.dev/docs/commands): Command groups and platform behavior.
- [Security and Trust](https://agent-device.dev/docs/security-trust): Local execution, permissions, credentials, and artifacts.
- [Known Limitations](https://agent-device.dev/docs/known-limitations): Current platform and capability constraints.
- [Node.js API](https://agent-device.dev/docs/client-api): Typed deterministic integration.

## Documentation Sets

- [Abridged documentation](https://agent-device.dev/llms-small.txt): a compact version of the documentation for agent-device, with non-essential content removed
- [Complete documentation](https://agent-device.dev/llms-full.txt): the full documentation for agent-device

## Notes

- The complete documentation includes all content from the official documentation
- The content is automatically generated from the same source as the official documentation

## Optional

- [GitHub](https://github.com/callstack/agent-device): Source, releases, issues, and official skills.
- [npm](https://www.npmjs.com/package/agent-device): Official package distribution.
- [MCP discovery manifest](https://agent-device.dev/.well-known/mcp.json): Machine-readable stdio MCP server metadata (registry identity, npm package, current version). agent-device has no HTTP MCP endpoint; the stdio server is started with `agent-device mcp`.