AutoGineer
Generated banner for Agent Device
Generated logo for Agent Device

Agent Device

CallstackOfficialPublished by Callstack

  • Skill
  • Tool integration
  • Software development
  • MIT
  • No issues found
Download ZIP

From the author

Automates interactions for Apple-platform apps (iOS, tvOS, macOS) and Android devices. Use when navigating apps, taking snapshots/screenshots, tapping, typing, scrolling, or extracting UI info across mobile, TV, and desktop targets.
— the description by Callstack

AutoGineer summary

Written by AutoGineer from the skill’s own files, not by the author

The agent-device skill provides a structured framework for automating device interactions, including navigation, UI inspection, and input simulation. It enforces a deterministic workflow by requiring setup via bootstrap references before proceeding to exploration and interaction. The skill emphasizes read-only inspection and selector-based targeting to ensure stability, while providing specific guidance for handling different device types and platforms.

What it does

  • Manages app sessions, including launching, installing, and relaunching applications.
  • Performs UI inspection through snapshots and element referencing.
  • Executes user-like interactions such as tapping, typing, and scrolling.
  • Supports cross-platform automation for mobile, TV, and desktop environments.
  • Provides structured paths for debugging, verification, and environment setup.
  • Enforces safe interaction patterns by prioritizing read-only checks before mutations.

When to use it

  • When you need to automate UI testing or interaction on mobile, TV, or desktop apps.
  • When you need to verify app state or extract UI information from a running session.
  • When you need to perform repeatable setup tasks like installing or launching specific app versions.
  • When you need to perform bug hunting or pass/fail QA against acceptance criteria.

Advantages

  • Promotes deterministic behavior by separating environment setup from UI interaction.
  • Reduces errors by favoring selector-based targeting over fragile coordinate-based actions.
  • Provides a consistent interface across diverse platforms like iOS, Android, and macOS.
  • Encourages safe, reversible UI actions to prevent unintended state changes.

Usage examples

“Open the test app on my iPhone simulator and check if the login button is visible.”
The agent will use bootstrap-install to ensure the simulator is ready, open the app, and then use exploration to verify the presence of the login button.
“Install the latest build of my Android app and navigate to the settings menu.”
The agent will use the install command to deploy the APK, open the app, and perform the necessary navigation steps to reach the settings screen.

Install

  1. Download the skill as a ZIP:

    https://mp-staging.autogineer.com/agent-skills/callstackincubator/agent-device/download

  2. Unzip it into the cross-client skills folder of your project:

    mkdir -p .agents/skills && unzip agent-device.zip -d .agents/skills

Documentation by Callstack

agent-device

Use this skill as a router with mandatory defaults. Read this file first. For normal device tasks, always load references/bootstrap-install.md and references/exploration.md before acting. Use bootstrap to confirm or establish deterministic setup. Use exploration for UI inspection, interaction, and verification once the app session is open.

Default operating rules

  • Start conservative. Prefer read-only inspection before mutating the UI.

  • Use plain snapshot when the task is to verify what text or structure is currently visible on screen.

  • Use snapshot -i only when you need interactive refs such as @e3 for a requested action or targeted query.

  • Avoid speculative mutations. You may take the smallest reversible UI action needed to unblock inspection or complete the requested task, such as dismissing a popup, closing an alert, or clearing an unintended surface.

  • Do not browse the web or use external sources unless the user explicitly asks.

  • Re-snapshot after meaningful UI changes instead of reusing stale refs.

  • Prefer @ref or selector targeting over raw coordinates.

  • Ensure the correct target is pinned and an app session is open before interacting.

  • Keep the loop short: open -> inspect/act -> verify if needed -> close.

Default flow

  1. Load references/bootstrap-install.md and references/exploration.md before acting on a normal device task.

  2. Use bootstrap first to confirm or establish the correct target, app install, and open app session.

  3. Once the app session is open and stable, use exploration for inspection, interaction, and verification.

  4. Start with plain snapshot if the goal is to read or verify what is visible.

  5. Escalate to snapshot -i only if you need refs for interactive exploration or a requested action.

  6. Use get, is, or find before mutating the UI when a read-only command can answer the question.

  7. End by capturing proof if needed, then close.

QA modes

Required references

  • For every normal device task, after reading this file, load references/bootstrap-install.md first, then references/exploration.md, before acting.

  • Use bootstrap to confirm or establish deterministic setup, especially in sandbox or cloud environments.

  • Use exploration once the app session is open and stable.

  • Load additional references only when their scope is needed.

Decision rules

  • Use plain snapshot when you need to verify whether text is visible.

  • Use snapshot -i mainly for interactive exploration and choosing refs.

  • Use get, is, or find when they can answer the question without changing UI state.

  • Use fill to replace text.

  • Use type to append text.

  • When a task asks to "go back", use plain back for predictable app-owned navigation and reserve back --system for platform back gestures or button semantics.

  • Use type --delay-ms or fill --delay-ms for debounced search fields that drop characters when typed too quickly.

  • If there is no simulator, no app install, or no open app session yet, switch to bootstrap-install.md instead of improvising setup steps.

  • Use the smallest unblock action first when transient UI blocks inspection, but do not navigate, search, or enter new text just to make the UI reveal data unless the user asked for that interaction.

  • Do not use external lookups to compensate for missing on-screen data unless the user asked for them.

  • If the needed information is not exposed on screen, say that plainly instead of compensating with extra navigation, text entry, or web search.

  • Prefer @ref or selector targeting over raw coordinates.

Additional references

Files

references/remote-tenancy.md

Remote Tenancy

When to open this file

Open this file for remote daemon HTTP flows, including --remote-config launches, that let an agent running in a Linux sandbox talk to another agent-device instance on a remote macOS host in order to control devices that are not available locally. This file covers daemon URL setup, authentication, lease allocation, and tenant-scoped command admission.

Main commands to reach for first

  • agent-device open <app> --remote-config <path> --relaunch

  • AGENT_DEVICE_DAEMON_BASE_URL=...

  • AGENT_DEVICE_DAEMON_AUTH_TOKEN=...

  • curl ... agent_device.lease.allocate

  • curl ... agent_device.lease.heartbeat

  • curl ... agent_device.lease.release

  • agent-device --tenant ... --session-isolation tenant --run-id ... --lease-id ...

Most common mistake to avoid

Do not run a tenant-isolated command without matching tenant, run, and lease scope. Admission checks require all three to line up.

Preferred remote launch path

Use this when the agent needs the simplest remote control flow: a Linux sandbox agent talks over HTTP to agent-device on a remote macOS host and launches the target app through a checked-in --remote-config profile.

agent-device open com.example.myapp --remote-config ./agent-device.remote.json --relaunch

  • This is the preferred remote launch path for sandbox or cloud agents.

  • For Android React Native relaunch flows, install or reinstall the APK first, then relaunch by installed package name.

  • Do not use open <apk|aab> --relaunch; remote runtime hints are applied through the installed app sandbox.

Lease flow example

export AGENT_DEVICE_DAEMON_BASE_URL=http://mac-host.example:4310
export AGENT_DEVICE_DAEMON_AUTH_TOKEN=<token>

curl -sS "${AGENT_DEVICE_DAEMON_BASE_URL}/rpc" \
  -H "content-type: application/json" \
  -H "Authorization: Bearer <token>" \
  -d '{"jsonrpc":"2.0","id":"alloc-1","method":"agent_device.lease.allocate","params":{"tenantId":"acme","runId":"run-123","ttlMs":60000}}'

agent-device \
  --tenant acme \
  --session-isolation tenant \
  --run-id run-123 \
  --lease-id <lease-id> \
  session list --json

Heartbeat and release example:

curl -sS "${AGENT_DEVICE_DAEMON_BASE_URL}/rpc" \
  -H "content-type: application/json" \
  -H "Authorization: Bearer <token>" \
  -d '{"jsonrpc":"2.0","id":"hb-1","method":"agent_device.lease.heartbeat","params":{"leaseId":"<lease-id>","ttlMs":60000}}'

curl -sS "${AGENT_DEVICE_DAEMON_BASE_URL}/rpc" \
  -H "content-type: application/json" \
  -H "Authorization: Bearer <token>" \
  -d '{"jsonrpc":"2.0","id":"rel-1","method":"agent_device.lease.release","params":{"leaseId":"<lease-id>"}}'

Session-locked RPC command example:

curl -sS "${AGENT_DEVICE_DAEMON_BASE_URL}/rpc" \
  -H "content-type: application/json" \
  -H "Authorization: Bearer <token>" \
  -d '{"jsonrpc":"2.0","id":"cmd-1","method":"agent_device.command","params":{"session":"qa-ios","command":"snapshot","positionals":[],"meta":{"lockPolicy":"reject","lockPlatform":"ios","tenantId":"acme","runId":"run-123","leaseId":"<lease-id>"}}}'

Transport prerequisites

  • Start the daemon in HTTP mode with AGENT_DEVICE_DAEMON_SERVER_MODE=http|dual.

  • Point the client at the remote host with AGENT_DEVICE_DAEMON_BASE_URL=http(s)://host:port[/base-path].

  • Use AGENT_DEVICE_DAEMON_AUTH_TOKEN or --daemon-auth-token when the client should send the shared daemon token automatically.

  • Direct JSON-RPC callers can authenticate with request params, Authorization: Bearer <token>, or x-agent-device-token.

  • Prefer an auth hook such as AGENT_DEVICE_HTTP_AUTH_HOOK when the host needs caller validation or tenant injection.

Lease lifecycle

Use JSON-RPC methods on POST /rpc:

  • agent_device.lease.allocate

  • agent_device.lease.heartbeat

  • agent_device.lease.release

Keep the lease alive for the duration of the run and release it when the tenant-scoped work is complete.

Host-level lease knobs:

  • AGENT_DEVICE_MAX_SIMULATOR_LEASES

  • AGENT_DEVICE_LEASE_TTL_MS

  • AGENT_DEVICE_LEASE_MIN_TTL_MS

  • AGENT_DEVICE_LEASE_MAX_TTL_MS

Command admission contract

For tenant-isolated command execution, pass all four CLI flags together:

agent-device \
  --tenant acme \
  --session-isolation tenant \
  --run-id run-123 \
  --lease-id <lease-id> \
  session list --json

The CLI sends AGENT_DEVICE_DAEMON_AUTH_TOKEN in both the JSON-RPC request token field and HTTP auth headers so existing daemon auth paths continue to work.

Failure semantics and trust notes

  • Missing tenant, run, or lease fields in tenant-isolation mode should fail as INVALID_ARGS.

  • Inactive or scope-mismatched leases should fail as UNAUTHORIZED.

  • Inspect logs on the remote host during remote debugging. Client-side --debug does not tail a local daemon log once AGENT_DEVICE_DAEMON_BASE_URL is set.

  • Treat daemon auth tokens and lease identifiers as sensitive operational data.

Requirements and compatibility

Works with: Claude Code, Claude apps, OpenAI Codex, GitHub Copilot, Cursor, Gemini CLI, Kiro, OpenCode, Goose, Amp, Roo Code, JetBrains Junie, Factory Droid, Devin (ex-Windsurf), Mistral Vibe, OpenHands, Letta

“Works with” means the tool reads the open Agent Skills format; a skill written for one tool may use features others lack.

Security

No issues found by our static scan· No issues found

A static scan is not a guarantee. Skills are third-party content: review a skill before you let an agent use it.

Attribution and licence

Published by
Callstack
Publisher
Callstack (Official)
Source
callstackincubator/agent-skills · plugins/vendored/.agents/skills/agent-device · commit 59e9d17
Licence
MIT License (redistribution allowed)
  • LICENSE (added by AutoGineer from LICENSE)
  • ATTRIBUTION.md (written by AutoGineer)
Synced

AutoGineer is not affiliated with or endorsed by Callstack.

Download ZIP

The ZIP holds the skill’s files, its licence files and an ATTRIBUTION.md. Download agent-device.zip