Remote Runs on the Cloud Grid

kane-cli testrun run --remote sends a suite of _test.md files to HyperExecute instead of running it on your machine. The grid sets up the runtime, runs every test in the suite (each one is a member), and streams the job back to your terminal. You get one job, one exit code, one sealed evidence pack, and the same recordings and evidence as a run on your own machine. Remote runs cover every kind of test:

Web suites run in Chrome on a HyperExecute macOS runner. Your machine or CI runner needs no Chrome, the run is always headless, and --parallel N spreads the members across N grid runners.
Mobile suites (target: emulator or target: simulator) run on a virtual Android emulator or iOS simulator on a HyperExecute macOS host, so you can author and run mobile tests from any machine: Linux, Windows, Intel Macs, or a Mac without Xcode or Android Studio. The macOS Apple Silicon requirement applies only to emulator and simulator runs on your own machine.
Real-device suites (target: android or target: ios) run on real devices in the cloud, driven from a HyperExecute Linux runner. See Real-Device Suites on the Grid.

kane-cli plugin install remote-execution                                          # once
kane-cli testrun run --tags smoke --remote --parallel 4                           # a web suite on 4 grid runners
kane-cli testrun run --match '^tests/app/' --remote --device-name "Pixel 7" --os-version 14  # an Android suite
kane-cli testrun run --match '^tests/ios/' --remote --device-name "iPhone 15" --os-version 17.5
kane-cli testrun run --match '^tests/devices/' --remote --parallel 2                        # real devices

--remote is different from --ws-endpoint and --cdp-endpoint. Those flags connect a remote browser to a run that still executes on your machine (kane-cli run, kane-cli testmd run). --remote moves the whole suite to the grid. Kane CLI itself runs there, and your machine needs only Node and the plugin.

Prerequisites

You need	Why	How to check
A plan that includes HyperExecute, with macOS runner concurrency for web, emulator, and simulator suites, or Linux runner concurrency for real-device suites	Every remote run is a HyperExecute job	Ask your account owner, or open the HyperExecute dashboard for your organisation
For real-device suites: KaneAI Max (one real device) or KaneAI credits + Real Device Plus Automation Cloud	The devices come from your real-device plan	See Real Devices: Plan Requirements
The `remote-execution` plugin	It owns the HyperExecute binary kane-cli dispatches with	`kane-cli plugin install remote-execution`, then `kane-cli plugin doctor remote-execution`
A username and access key	HyperExecute authenticates with basic auth. An OAuth profile is exchanged for them automatically; otherwise pass `--username` and `--access-key`	`kane-cli whoami`
A project directory that contains the tests	The current directory is zipped and shipped as the job payload	Run from the repository root, or any parent of the tests
Recordings not gitignored	The payload respects `.gitignore`, and an ignored `output-<stem>/` never reaches the grid. Builds are not payload, see The app under test on the grid	`--dry-run` reports `gitignored_inputs`; un-ignore with, for example, `!output-*/`

The run uploads to the project and folder configured on your profile (kane-cli config project and kane-cli config folder). Kane CLI passes them to the login on the grid.

How a remote run works

Preflight, then remote preflight. Kane CLI builds the normal testrun plan (one organisation, one project, see Preflight). It then checks that the selection fits in one grid job (see What one job can hold) and, for mobile, looks up the device in the grid catalog. If anything is wrong, the run stops here with exit 2 and nothing is dispatched.
Payload. Kane CLI zips the current directory, respecting .gitignore, and uploads it with a generated job definition. Dispatching leaves .hyperexecute/, hyperexecute-cli.log, and .updatedhyperexecute.yaml in that directory. They are not inputs, so add them to .gitignore.
On the grid (a macOS runner, or a Linux runner for real-device suites), a setup step installs Kane CLI and logs in with your credentials and project. For mobile, it also installs the device tooling and boots the device. Then each member runs as its own kane-cli testmd run, headless, exactly as it would on your machine. A member with recordings replays them. A member without recordings is authored on the grid.
Back to you. The job streams its progress and the dashboard link to your terminal. When it ends, the members’ output-<stem>/ recordings and the sealed evidence pack are downloaded into your project, and the pack is published to Test Manager. The suite summary and exit code match a local testrun.

Allow some time beyond the tests themselves: about 15 seconds of setup for a web job, and a minute or more for a mobile job to boot the device and install the app. In CI, a wall-clock timeout of 10 minutes is a safe starting point.

Dispatching a run

--remote takes the normal testrun selection (paths, --match, --tags).

kane-cli testrun run --tags smoke --remote --dry-run          # both preflights, nothing dispatched
kane-cli testrun run --tags smoke --remote --parallel 4

--dry-run runs both preflights and resolves any device without creating a job. It costs nothing, so use it before every new selection. A real run prints the job id and dashboard link, then follows the job until it completes:

job 24fc58b2-… dispatched → https://hyperexecute.lambdatest.com/hyperexecute/task?jobId=24fc58b2-…

Flag	On the grid
`--parallel <n>`	Sets the job’s concurrency. The members are split automatically across `n` grid runners, and each runner works through its share one member at a time. Device suites run in parallel the same way, and every task has its own VM and device
`--headless`	Not needed. Every member runs headless on the grid
`--author`, `--no-adaptive-heal`	Forwarded to grid member runs
`--username`, `--access-key`	Used for the grid login and the Test Manager upload

Web suites on the grid

A web suite needs nothing beyond the prerequisites. The grid runner has Chrome, and Kane CLI finds it and runs each member headless. Use the grid when your runner cannot have Chrome, when you want the suite off your laptop, or when you need more parallel capacity than one machine offers.

kane-cli plugin install remote-execution
kane-cli testrun run --match '^tests/web/' --remote --parallel 4

You get a normal testrun summary, plus two extra lines for the dispatch and the job link. A member that is authored on the grid returns its output-<stem>/ recordings, so the next run, on the grid or on your machine, replays them. Commit those recordings as you would after a local run. Web tests and device tests cannot share a job (mobile_remote_mixed). Run them as two separate suites.

Choosing a grid device (emulator and simulator)

Remote devices come from the grid catalog, not from the AVDs or simulators on your machine. To see what the grid can provide:

kane-cli devices list --target emulator --remote                    # Android emulators
kane-cli devices list --target simulator --remote                   # iOS simulators
kane-cli devices list --target simulator --remote --os-version 17.5 # only that OS version

Each row shows a device name and the OS versions available for it. Select a device with both:

Flag or key	Purpose
`--device-name "<name>"`	The name exactly as the catalog prints it (`"Pixel 7"`, `"iPhone 15"`). Validated before dispatch
`--os-version <v>`	The OS version (`14`, `17.5`). On its own, it means any catalog device running that version
`device_name:` or `os_version:` in a `_test.md`	Per-test defaults, used when the flags are absent. See Mobile target

Kane CLI resolves each test’s device on your machine. It picks the device name and the OS version separately, each in this order:

--device-name / --os-version
The test file’s device_name: / os_version:
Your saved device (kane-cli config set-device-name / set-os-version), when it is the same kind (emulator or simulator) and the grid has it. A saved device the grid does not have is skipped with a saved_device_unavailable note.
The default: Pixel 8 Pro · Android 15 for emulators, iPhone 17 Pro Max · iOS 26.0 for simulators.

Before dispatch, Kane CLI prints where each test’s device came from:

Devices:
  tests/app/login_test.md  Emulator · Pixel 8 Pro · Android 15  (default)
  tests/app/cart_test.md   Emulator · Pixel 7 · Android 14  (test file)

The two platforms assign devices differently:

Emulator: the job uses one device for all its members, so they must all ask for the same Android version. If they differ, the preflight refuses with mobile_os_version_split. To force one version, pass --os-version. If a member names an AVD from your own machine, Kane CLI ignores it and shows a device_name_ignored note, because a remote job’s device name comes from the catalog.
Simulator: each task boots a simulator inside its own VM, so each member uses its own device_name: and os_version:, checked against the catalog. If you pass --device-name and --os-version, they apply to every member. Members can ask for different iOS versions as long as their major versions belong to the same HyperExecute pool. The catalog decides the pools: iOS 17 and 18 share one, and iOS 26 is in another. If members need different pools, the preflight refuses with mobile_pool_split.

Real-device suites on the grid

target: android and target: ios tests run on real devices in the cloud. The job runs on a HyperExecute Linux runner, and each member opens its own device session, so:

--parallel N runs N members at once, up to the real devices your plan allows. A session beyond that queues for up to 15 minutes (see Plan Requirements).
Android and iOS real-device members can share one job.
A job cannot mix real-device members with web, emulator, or simulator members (mobile_remote_mixed).

Kane CLI resolves each member’s device on your machine. It picks the device name and the OS version separately, each in this order:

--device-name / --os-version
The test file’s device_name: / os_version:
The hub picks any free device. The hub is the service that assigns real devices to sessions.

You can set the name alone or the version alone, and a name can be a pattern. To list the real devices the cloud has:

kane-cli devices list --target android --remote
kane-cli devices list --target ios --remote

Kane CLI checks each name and version against that list before dispatch and prints the Devices: block:

Devices:
  tests/devices/login_test.md  Real device · any Android device · Android 15  (test file)
  tests/devices/cart_test.md   Real device · iPhone 15 · any iOS version  (flag)

If Kane CLI cannot read the device list, it dispatches the job anyway with a real_device_list_unavailable note, and the hub decides which device each member gets. Before you dispatch a real-device suite, check these rules:

Every member needs an app: in its file: .apk or .aab for Android, .ipa for iOS, or an APP… id. Without one, the run stops with mobile_app_required. testrun has no --app flag.
--device-slug is refused for real devices.
Adaptive heal is off on real devices, so a failed replay step fails the test.

For the TUI, live view, settings, and limits on real devices, see Real Devices.

The app under test on the grid

The grid machine has to get the app from somewhere. A build is never part of the payload. It reaches the grid by id:

`app:` in the test	What happens
A local build, anywhere on disk: `.apk` for `emulator`, a `.zip` of the `.app` for `simulator`, `.apk` or `.aab` for `android`, or `.ipa` for `ios`	Uploaded from your machine during preflight, once per distinct file, and passed to the grid as `--app <id>`. A cache on each machine skips builds your account already has. The build may be gitignored or outside the project. `--dry-run` uploads nothing
An uploaded `APP…` id	Used as is, and the grid downloads it

Each member gets its own id, so members in one run can use different builds. An .ipa is refused for emulator and simulator tests, because it is a device build. Use it with target: ios. Every upload is reported, as app: <file> → APP… (uploaded) in the terminal or as the remote_app event for agents. kane-cli apps list --target emulator|simulator|android|ios shows the uploaded builds your account can use. Put a value from the APP ID column in app:. There is no separate upload command: any run with a local build, on the grid or on your machine, uploads it and prints the APP… id. Uploads belong to an organisation, so apps list for your current profile is the definitive list of ids a run can use.

What one job can hold

Each remote run is one HyperExecute job, and a job provides one kind of runtime. The remote preflight refuses a selection that needs more than one, and tells you how to split it with --match or --tags:

Reason	Meaning	Fix
`mobile_remote_mixed`	More than one kind of test in one selection: web, emulator or simulator, real device	One run per kind
`mobile_remote_mixed_platform`	Emulator and simulator tests in one selection	Two runs, one per platform
`mobile_os_version_split`	Emulator tests asking for different Android versions	One run per version, or `--os-version` to force one
`mobile_pool_split`	Simulator tests whose iOS versions need different HyperExecute pools	One run per pool, or `--os-version` to force one
`mobile_remote_unsupported`	A device target the grid cannot provide	Run it on your own machine, or deselect it
`mobile_app_required`	A real-device test has no `app:`	Add `app: <path-to-build \| AppId>` to the file
`mobile_app_missing`	A device test names a local build that is not on this machine	Fix the path, or use an `APP…` id
`mobile_app_not_uploadable`	The build is not one the cloud takes for that target	`.apk` for emulator, a `.zip` of the `.app` for simulator, `.apk` or `.aab` for android, `.ipa` for ios, or an `APP…` id
`mobile_app_upload_failed`	Uploading the build from your machine failed	Fix the upload (network, auth), or use an `APP…` id
`member_outside_payload`	A test lives outside the dispatched directory	Run from a directory that contains it
`gitignored_inputs`	Required recordings are gitignored	Un-ignore them (for example `!output-*/`) or commit them
`on_grid`	Already running on a HyperExecute grid	`--remote` cannot re-dispatch from inside a job

Each reason comes with the paths that caused it, both in the terminal and in a remote_error event for agents.

What comes back

Recordings: the output-<stem>/ directories of authored members land in your project exactly as a run on your machine would leave them, so the next run replays from cache.
Evidence: one sealed pack for the suite in .testmuai/evidence/, published to your project’s execution history in Test Manager.
Job logs: the per-member session logs under ~/.testmuai/kaneai/sessions/remote/<job-id>/, and the full stage logs on the HyperExecute dashboard at the printed job link.
Exit code: the same as a local testrun. 0 all passed, 1 a member failed or broke, 2 preflight, auth or usage (nothing dispatched), 3 cancelled.

When a remote run fails

A member failed or broke (exit 1): read it like any other failure. output-<stem>/Result.md names the failing step and reason, and the evidence pack has the screenshots and logs. See Debugging from a Pack.
A member is broken with no steps and nothing was published: Kane CLI on the grid refused to start. Open the job link and read the scenario stage log. For mobile, the usual cause is an APP… id that belongs to a different organisation than the account running the job.
Nothing was dispatched (exit 2): the printed reason is one of the preflight codes above. Run kane-cli plugin doctor remote-execution to see whether the plugin, binary, or login is missing.

In CI

A remote run needs no Chrome, Xcode, or Android Studio on the CI runner, only Node and the plugin:

npm install -g @testmuai/kane-cli
kane-cli plugin install remote-execution

# a web suite
kane-cli testrun run --match '^tests/web/' --remote --parallel 4 \
  --username "$LT_USERNAME" --access-key "$LT_ACCESS_KEY"

# a mobile suite
kane-cli testrun run --match '^tests/app/' --remote \
  --device-name "Pixel 7" --os-version 14 \
  --username "$LT_USERNAME" --access-key "$LT_ACCESS_KEY"

# a real-device suite
kane-cli testrun run --match '^tests/devices/' --remote --parallel 2 \
  --username "$LT_USERNAME" --access-key "$LT_ACCESS_KEY"

Archive .testmuai/evidence/*.evidence as the build artifact. More pipeline shapes are in CI/CD.

For agents: NDJSON events

In agent or non-TTY mode, a remote run wraps the normal testrun_* stream in additional typed events (see For agents):

`type`	Payload	Notes
`remote_start`	`backend`, `env`	Dispatch begins
`remote_device`	`platform`, `slug`, `name`, `os_version`, `avd_id?`, `pool?`	The resolved grid device, emulator and simulator only. Web and real-device runs have none
`remote_member_device`	`path`, `kind`, `platform`, `name?`, `os_version?`, `name_source`, `os_version_source`	One per device member, before dispatch. `kind` is `emulator`, `simulator`, or `real-device`. Sources are `flag`, `file`, `config` (your saved device), `default`, or `hub` (left for the hub to pick, so that half has no value)
`remote_device_hint`	`reason`, `detail`	`device_name_ignored` (emulator only, a local AVD name was dropped), `catalog_stale`, `saved_device_unavailable` (your saved device is not on the grid), or `real_device_list_unavailable` (devices not checked before dispatch)
`remote_app`	`path`, `app_id`, `source`	One per distinct local build uploaded from your machine, mobile only. `source` is `uploaded`, `cache` (already uploaded by this machine) or `dry-run` (`app_id` empty, nothing sent)
`remote_dispatched`	`job_id`, `job_url`	The HyperExecute job exists, and the link opens the dashboard
`remote_error`	`code`, `detail`	Remote preflight refused the selection (codes above), followed by `testrun_done` and exit `2`
`remote_exec_sync`, `remote_coverage`	`status`, `reason`, `detail?`	Informational: assurance graph sync and coverage, skipped when the project has no `.context` store
`remote_done`	`status`, `exit`, `job_id`, `sessions_path`	Terminal for the remote wrapper, and follows `testrun_done`

testrun_summary also carries a remote object (backend, jobId, jobUrl, sessionsPath). When you parse the stream of a dispatched run, keep reading after testrun_done until remote_done and the process exit, and keep the remote status and the session-log path. A preflight refusal or a dry run can end without remote_done.

Known limitations

--bug-detection is not forwarded. Remote dispatch does not pass --bug-detection to the member commands, so do not rely on it for bug detection in a remote run.
--on-failure is not applied. Remote dispatch does not map --on-failure into the job template, so do not rely on it for fail-fast behavior in a remote run.
--name names the suite only. It is suite metadata and is not passed to member commands.

Next Steps

Batch Runs (testrun) for selection, preflight, flags and exit codes
Mobile Testing for setup on your own machine, or skip it with --remote
Real Devices for real Android and iOS devices, plans, live view and limits
Writing test.md files for target:, app:, device_name: and os_version:
Evidence Packs for what comes back and how to view it
CI/CD for pipeline patterns, including runners with no Chrome

​Prerequisites

​How a remote run works

​Dispatching a run

​Web suites on the grid

​Choosing a grid device (emulator and simulator)

​Real-device suites on the grid

​The app under test on the grid

​What one job can hold

​What comes back

​When a remote run fails

​In CI

​For agents: NDJSON events

​Known limitations

​Next Steps

Prerequisites

How a remote run works

Dispatching a run

Web suites on the grid

Choosing a grid device (emulator and simulator)

Real-device suites on the grid

The app under test on the grid

What one job can hold

What comes back

When a remote run fails

In CI

For agents: NDJSON events

Known limitations

Next Steps