Genymotion Unified Skill

This skill is the main entry point for all Genymotion virtual device management tasks. It handles both Genymotion SaaS (via gmsaas) and Genymotion Desktop (via gmtool).

Step 1 — Determine the Target Platform

If the user's request does not clearly specify Cloud or Local, ask before proceeding:

AskUserQuestion:
  "Which platform do you want to use?"
  Options:
    - "Genymotion SaaS / Cloud (gmsaas) — remote device in the cloud"
    - "Genymotion Desktop / Local (gmtool) — local device on this machine"

Keywords that imply Cloud: "cloud", "SaaS", "remote", "gmsaas", "Genymotion Cloud" Keywords that imply Local: "local", "desktop", "gmtool", "on my machine"

Step 2 — Check Prerequisites

For Genymotion SaaS (gmsaas)

Step 2a — Locate gmsaas

Detect the OS first, then check if gmsaas is available in PATH:

Linux / macOS: which gmsaas
Windows (PowerShell): where.exe gmsaas
If found in PATH: use gmsaas directly for all subsequent commands.
If NOT found in PATH: do NOT search directories yourself. Ask the user:

"gmsaas was not found in PATH. Do you have a Python virtualenv where gmsaas is installed?"

Yes — I will provide the path to the venv

No — I need to install gmsaas

If the user provides a venv path, use the appropriate binary:
- Linux / macOS: <venv_path>/bin/gmsaas
- Windows: <venv_path>\Scripts\gmsaas
If gmsaas is not installed, follow references/setup-gmsaas.md

Step 2b — Check authentication

Once gmsaas is located, run gmsaas doctor to verify the setup.

If gmsaas IS found but not authenticated, identify the issue with gmsaas doctor and guide the user through setup.

SECURITY — Never run gmsaas auth token <token> via the Bash tool. The token would be exposed in the shell history. Instead, display the command for the user to run themselves in their own terminal:
# Linux / macOS:
export GENYMOTION_API_TOKEN="your_token"

# Windows (PowerShell):
$env:GENYMOTION_API_TOKEN = "your_token"

For Genymotion Desktop (gmtool)

Run: gmtool version

If gmtool is NOT found, follow references/setup-gmtool.md

If gmtool IS found but licence inactive (exit code 9):

gmtool license info                  # Check licence status
gmtool license register <key>        # Register a licence key

Step 3 — Execute the Requested Action

Once the platform is confirmed and prerequisites are met, read the appropriate reference file and follow its instructions:

For Genymotion SaaS (gmsaas) → Read references/gmsaas-reference.md
For Genymotion Desktop (gmtool) → Read references/gmtool-reference.md

The reference files are located in the references/ directory:

references/gmsaas-reference.md
references/gmtool-reference.md

Verify Start / Stop Operations

Always verify the actual state after a start or stop command. Never assume success based solely on the command's exit code or lack of error output.

Genymotion SaaS (gmsaas)

After gmsaas instances start:

Poll until status is ONLINE using the following strategy:

Repeat up to 10 times (max ~5 minutes):
  Run: gmsaas instances get <instance_uuid>
  If status = "ONLINE"  → proceed, inform the user the instance is ready
  If status = "BOOTING" → wait 30 seconds, then retry
  If status is anything else (ERROR, DELETING, unknown) → stop polling, inform the user and suggest checking https://cloud.geny.io/instances

If still not ONLINE after 10 attempts (~5 minutes):
  → Inform the user: "The instance is taking longer than expected to start.
     You can check its status at https://cloud.geny.io/instances or run:
     gmsaas instances get <instance_uuid>"
  → Do not proceed with ADB connect or further steps

Between each poll, tell the user what you are doing: "Instance is BOOTING — checking again in 30 seconds (attempt N/10)…"

After gmsaas instances adbconnect:

adb devices
# Expected: instance appears in the list (e.g. "localhost:5555  device")
# If list is empty despite successful adbconnect:
#   → The local ADB daemon may not be running. Start it:
gmsaas adb start
#   → Then retry: adb devices
# If still empty: run gmsaas doctor to check the Android SDK path configuration

After gmsaas instances stop:

gmsaas instances list
# Expected: instance no longer appears in the list
# Or: gmsaas instances get <instance_uuid> → status = "STOPPED" / "OFFLINE"
# If instance still appears as running: retry the stop command or ask the user to check the cloud dashboard

Genymotion Desktop (gmtool)

After gmtool admin start <device>:

gmtool admin list --running
# Expected: device appears in the list with State = On
# If not listed: check exit code, try gmtool admin details <device> for more info

After gmtool admin stop <device>:

gmtool admin list --off
# Expected: device appears with State = Off
# If still listed as running: retry stop or ask the user to close Genymotion Desktop

Report the verified state to the user. Don't say "the device is started" — say "I confirmed the device is running: gmtool admin list --running shows it with State = On."

Stop a SaaS Instance

Keywords that trigger this flow: "stop", "arrêter", "delete", "supprimer", "shut down", "kill", combined with "instance", "cloud", "gmsaas"

SaaS instances are billed as long as they are running. Always offer to stop the instance when the user's task is complete, or when they ask how to avoid charges.

Stop a single instance

# List running instances to get the UUID
gmsaas instances list

# Stop the instance
gmsaas instances stop <instance_uuid>

Stop all running instances

If the user wants to stop everything at once:

# List all running instances and stop each one
gmsaas instances list
# Then for each instance UUID:
gmsaas instances stop <instance_uuid>

Proactive guidance: After any workflow that starts a SaaS instance (APK install, testing, display…), remind the user: "Don't forget to stop your instance when you're done to avoid charges: gmsaas instances stop <instance_uuid>"

Display a SaaS Instance

Keywords that trigger this flow: "display", "open", "show", "view", combined with "cloud instance", "SaaS instance" or "gmsaas instance"

When the user wants to display a running SaaS instance, offer the following options:

AskUserQuestion:
  "How would you like to display your Genymotion SaaS instance?"
  Options:
    - "Open in the Genymotion Cloud web interface"
    - "Open via gmsaas instances display (opens and copies the link to clipboard)"
    - "Embed it in a custom web page (device-web-player SDK)"

Prerequisites

A running SaaS instance (if not started yet, start it first — see Step 2)
Retrieve the instance UUID if not already known: gmsaas instances list

A recipe defines the virtual device configuration (Android version + hardware profile). Think of it as a device template. Before starting an instance, you need to pick a recipe UUID. List available recipes with: gmsaas recipes list

Option 1 — Open in the Genymotion Cloud web interface

Provide the user with the URL to open directly in their browser:

https://cloud.geny.io/instance/<instance_uuid>

The user must be logged in to https://cloud.geny.io beforehand. Remind them to log in if this is their first time or if their session may have expired.

Option 2 — Open via gmsaas instances display

gmsaas instances display <instance_uuid>

Note: this command copies the instance display link to the clipboard and may open it automatically in the default browser. Inform the user that the link has been copied to their clipboard.

Option 3 — Embed in a custom web page

→ Follow the Display a SaaS Instance in a Web Page (device-web-player) section below.

Display a SaaS Instance in a Web Page (device-web-player)

Keywords that trigger this flow: "web page", "embed", "browser", "device-web-player", "html page", "integrate", "web player", combined with "cloud instance" or "SaaS"

Read references/device-web-player-reference.md and follow the Step-by-step Workflow section.

Key behaviors to always apply:

NEVER execute curl commands via Bash tool — they return secrets
NEVER ask the user to paste tokens into the chat — display commands for them to run in their own terminal
Always offer two options: default template (templates/device-web-player.html) or custom design
Remind the user to serve via HTTP (not file://) for WebRTC to work

CI/CD Integration

Keywords that trigger this flow: "CI/CD", "pipeline", "GitHub Actions", "Jenkins", "Bitrise", "CircleCI", "continuous integration", "automated tests", "Detox", "Appium", combined with "Genymotion" or "SaaS"

CI/CD integration is only supported with Genymotion SaaS (gmsaas), not Genymotion Desktop (gmtool). If the user asks about CI/CD with Genymotion Desktop, explain this limitation and redirect to SaaS.

Read references/cicd-reference.md for platform-specific tutorials and the general integration pattern.

General Workflow Summary

1. Identify the target platform (Cloud or Local) → ask if ambiguous
2. Check prerequisites (gmsaas or gmtool installed + authenticated/licensed)
   → If missing: guide the user through installation step by step
3. Read the corresponding reference file
4. Identify the requested action
5. Collect missing parameters (name, UUID, profile…) via list + AskUserQuestion
6. Execute the command via Bash
7. Verify the result with the appropriate check command (see "Verify Start / Stop Operations")
8. Report the verified state to the user — never assume success without checking
9. Handle errors (show the message + suggest a solution)
10. [SaaS only] Remind the user to stop the instance when done to avoid charges

Examples

Example 1 — Start a Cloud instance and install an APK

User says: "Start a Pixel 8 on Genymotion Cloud and install my app.apk"

Actions:

Detect platform = Cloud → check gmsaas
gmsaas recipes list → ask user to pick a Pixel 8 recipe
gmsaas instances start <recipe_uuid> "pixel-8" --max-run-duration 3600
gmsaas instances get <instance_uuid> → verify status = ONLINE before proceeding
gmsaas instances adbconnect <instance_uuid>
adb install app.apk
Remind user: gmsaas instances stop <instance_uuid> when done

Result: APK installed and running on a live cloud instance. Instance state was verified before ADB connection. User is reminded to stop it to avoid charges.

Example 2 — Start a local Desktop device and debug

User says: "Lance un device Android 13 en local et montre-moi les logs"

Actions:

Detect platform = Local → check gmtool
gmtool admin list → identify an Android 13 device
gmtool admin start "Pixel 7 API 33"
gmtool admin list --running → verify device appears with State = On
gmtool device logcatdump -n "Pixel 7 API 33" ~/debug.log

Result: Device started and verified running before capturing logs.

Example 3 — Embed a cloud instance in a web page

User says: "I want to display my Genymotion instance in an HTML page"

Actions:

Detect flow = device-web-player
Check instance is running → gmsaas instances list
Ask user: default template or custom design?
Copy templates/device-web-player.html (or generate custom)
Display curl commands for the user to run in their terminal (webrtc_url + access token)
Instruct user to replace REPLACE_WITH_WSS_ADDRESS and REPLACE_WITH_ACCESS_TOKEN
Remind to serve via HTTP: python3 -m http.server 8080

Result: Ready-to-use HTML page streaming the device via WebRTC.

Example 4 — Set up Genymotion in a GitHub Actions pipeline

User says: "How do I use Genymotion in my GitHub Actions CI?"

Actions:

Detect flow = CI/CD → read references/cicd-reference.md
Clarify: CI/CD is only supported with Genymotion SaaS, not Desktop
Point to the GitHub Actions resource: https://github.com/marketplace/actions/genymotion-saas-action
Show the general pattern: auth → start instance → adbconnect → run tests → stop instance
Remind to store GENYMOTION_API_TOKEN as a CI secret

Result: User has a working starting point for their CI pipeline.

Troubleshooting

gmsaas not found in PATH

Cause: gmsaas is not installed or not in PATH. Solution: Run which gmsaas (Linux/macOS) or where.exe gmsaas (Windows). If missing, see references/setup-gmsaas.md. If installed in a virtualenv, provide the full path: <venv>/bin/gmsaas or <venv>\Scripts\gmsaas.

Auth error — 401 / Unauthorized

Cause: API token not set, expired, or revoked. Solution: Run gmsaas doctor to identify the issue. Set the token via environment variable (do not run via Bash tool):

Linux/macOS: export GENYMOTION_API_TOKEN="your_token"
Windows: $env:GENYMOTION_API_TOKEN = "your_token"

Instance stuck in BOOTING

Cause: Cloud instance startup can take 1–3 minutes. Rarely, the instance may fail to boot. Solution: Poll gmsaas instances get <uuid> every 30 seconds, up to 10 attempts. If still not ONLINE after 5 minutes, inform the user and point to https://cloud.geny.io/instances.

adb devices empty after adbconnect

Cause: The local ADB daemon is not running. Solution: Run gmsaas adb start, then retry adb devices. If still empty, run gmsaas doctor to verify the Android SDK path.

gmtool licence not activated (exit code 9)

Cause: Genymotion Desktop licence not registered. Solution: gmtool license info to check status, then gmtool license register <key> to activate.

gmtool device not found (exit code 5)

Cause: Device name is incorrect or the device has not been created yet. Solution: Run gmtool admin list to get the exact device names. If the device does not exist, create it first.

gmtool virtualisation engine not responding (exit code 4)

Cause: Genymotion Desktop is not running or the hypervisor crashed. Solution: Open Genymotion Desktop and wait for it to be ready, then retry.

Tools Used

Bash — to run gmsaas and gmtool
AskUserQuestion — to disambiguate the platform and collect missing parameters
Read — to read the reference files references/gmsaas-reference.md, references/gmtool-reference.md, references/device-web-player-reference.md
Glob / Read — to locate local APK files or archives

genymotion

Genymotion Unified Skill

Step 1 — Determine the Target Platform

Step 2 — Check Prerequisites

For Genymotion SaaS (gmsaas)

For Genymotion Desktop (gmtool)

Step 3 — Execute the Requested Action

Verify Start / Stop Operations

Genymotion SaaS (gmsaas)

Genymotion Desktop (gmtool)

Stop a SaaS Instance

Stop a single instance

Stop all running instances

Display a SaaS Instance

Prerequisites

Option 1 — Open in the Genymotion Cloud web interface

Option 2 — Open via gmsaas instances display

Option 3 — Embed in a custom web page

Display a SaaS Instance in a Web Page (device-web-player)

CI/CD Integration

General Workflow Summary

Examples

Example 1 — Start a Cloud instance and install an APK

Example 2 — Start a local Desktop device and debug

Example 3 — Embed a cloud instance in a web page

Example 4 — Set up Genymotion in a GitHub Actions pipeline

Troubleshooting

gmsaas not found in PATH

Auth error — 401 / Unauthorized

Instance stuck in BOOTING

adb devices empty after adbconnect

gmtool licence not activated (exit code 9)

gmtool device not found (exit code 5)

gmtool virtualisation engine not responding (exit code 4)

Tools Used