[FEATURE] Expose Appium Session ID using API or Environment or Well Known file

[ssharma007-dev]

Problem Statement

When running with the Appium driver, maestro-runner creates and manages the Appium session lifecycle internally. However, there is currently no supported API for external tools to access the Appium session ID before flow execution begins.

The Appium session ID can currently be obtained from generated report artifacts, but doing so requires external tools to poll and parse report files. This creates a dependency on internal report generation behavior rather than a stable integration interface.

Proposed Solution

Expose Appium session information immediately after session creation and before the first flow step executes through a supported integration mechanism.

Possible approaches include:

Environment variable
API endpoint
Lifecycle hook
Well-known session file

Stable and supported way for external tools to access Appium session information and integrate with the active Appium session without relying on report parsing.

Use Case

Many third-party tools can attach to an existing Appium session if the session ID is available.

Providing a supported mechanism to access Appium session information would enable integrations with visual testing, observability, reporting, debugging, and other automation tooling without requiring those tools to manage the Appium session lifecycle themselves.

Example

(1) Environment variable approach:

const sessionId = process.env.MAESTRO_APPIUM_SESSION_ID;

(2) API approach:

GET /session

{
"sessionId": "abc123",
"appiumUrl": "http://localhost:4723"
}

(3) Well-known file approach:

{
"sessionId": "abc123",
"appiumUrl": "http://localhost:4723"
}

Alternatives Considered

Polling reports/*/report.json to obtain the session ID is our current workaround.

While functional, it requires external tools to depend on generated report artifacts rather than a supported integration mechanism.

Additional Context

Exposing Appium session information would enable integrations with visual testing platforms, observability solutions, reporting tools, debugging utilities, and custom automation frameworks that need to attach to an existing Appium session.

[omnarayan]

@ssharma007-dev — thanks for the detailed feature request!

This is a well-thought-out proposal, and exposing the Appium session ID through a stable mechanism (rather than report parsing) makes a lot of sense for integrations. We'll work on it.

One thing worth adding: maestro-runner already has a cloud provider integration layer, and Sauce Labs is supported today. So if you're running against a cloud provider, that path is already available. If you're using a specific provider, we can also look into adding native support for it.

We'll pick up your request and update this thread as we make progress.

[omnarayan]

@ssharma007-dev Implemented behind a new opt-in flag: --appium-session-file <path> (env MAESTRO_APPIUM_SESSION_FILE). Off by default.

When set, maestro-runner publishes the live Appium session(s) to a single JSON file the moment each session is created (before the first flow step), so external tools can attach without polling report artifacts:

{
  "schemaVersion": 1,
  "updatedAt": "2026-06-08T07:31:51Z",
  "sessions": [
    { "deviceId": "emulator-5554", "sessionId": "d2e5...", "appiumUrl": "http://127.0.0.1:4723", "flow": "checkout.yaml", "status": "active", "updatedAt": "..." }
  ]
}

Design notes for the edge cases:

• Parallel runs → one file, one entry per device (keyed by deviceId), no clobbering.
• New session per flow → the device's entry is updated in place (new sessionId/flow), no stale accumulation.
• Lifecycle → entries are active during the run and flipped to closed when the run ends.
• Atomic → the file is rewritten in full via temp-file + rename, so a reader never sees a partial/invalid file (use an fsnotify CREATE/RENAME watch).
• Works alongside a cloud provider (Sauce, etc.) rather than instead of it.

Validated end-to-end on a parallel run across two physical/emulated Android devices — both sessions appear with the correct IDs and flip to closed at the end.

We went with the well-known file (your option 3) over an env var because an already-running external tool can read a file but not maestro-runner's process env. An optional GET /sessions HTTP endpoint over the same data could be layered on later if
there's demand.