For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt, and this page is available as Markdown at /get-started/harmonyos-playground-api-key.md.
  • English

      • Get started: HarmonyOS · Playground · Model API Key

      These are the setup steps for Midscene on HarmonyOS with Playground and a Model API Key. To choose another combination, change the answers below or see all setup paths.

      Which platform do you want to automate?
      What do you want to do first?
      How will you connect a model?

      Step 1

      Connect the HarmonyOS device

      Midscene uses hdc on your computer to communicate with the target HarmonyOS NEXT device. If hdc is already installed and your device is connected, skip directly to Verify the device connection.

      Install HDC

      HDC (HarmonyOS Device Connector) is the official command-line tool for communicating with HarmonyOS devices. Install it using either of the following methods:

      Run the following command to verify the installation:

      hdc version

      A version number in the terminal output confirms a working installation.

      Configuring the HDC path

      If hdc is not in your system PATH, set the HDC_HOME environment variable to the directory containing the hdc executable:

      export HDC_HOME=/path/to/hdc/directory

      Enable debugging and connect the device

      1. On your HarmonyOS device, open Settings > System > Developer options and enable USB debugging.
      2. Connect the device to your computer using a USB cable that supports data transfer.
      3. Keep the device unlocked and accept the debugging authorization prompt on the screen.

      Verify the device connection

      Run the following command to check the connection status:

      hdc list targets

      A device ID in the output confirms that the device is connected and ready:

      0123456789ABCDEF

      If multiple devices are connected, note the target device ID so you can select it in Playground or your project configuration. If the output is empty or [Empty], check the USB cable, USB connection mode, USB debugging toggle, and the authorization prompt on the device.

      Step 2

      Configure a model

      Choose a model below. Its configuration has four values. Open Get API key to create a key with the provider, then replace ...... in MIDSCENE_MODEL_API_KEY with it.

      Which model do you want to use?
      Provider
      Get API key ↗
      MIDSCENE_MODEL_BASE_URL="https://ark.cn-beijing.volces.com/api/v3"
MIDSCENE_MODEL_API_KEY="......"
MIDSCENE_MODEL_NAME="doubao-seed-2-1-turbo-260628"
MIDSCENE_MODEL_FAMILY="doubao-seed"

      For other versions and usage notes, see Doubao Seed series.

      To compare models, see the Model selection guide. For compatible models such as UI-TARS, see Use a model API key.

      Keep the configuration at hand. You will paste it into Playground in a later step.

      Step 3

      Launch Playground

      Make sure Node.js (^20.19.0 || ^22.12.0 || >=24.0.0) is installed and node -v works in your terminal. The command below uses pnpm. If it is not installed yet, run npm install -g pnpm.

      1. Start the HarmonyOS Playground CLI:
      pnpm dlx @midscene/harmony-playground
      1. In the Playground window that opens, click the gear icon in the top-right corner, paste your model configuration, and save.
      2. If your browser does not open automatically, visit the local Playground URL printed in the terminal, and keep the terminal process running.
      3. In the connection panel on the left, select your target HDC device (matching the ID from hdc list targets) and create the Agent.
      4. Confirm that the preview area displays your device's current screen. If no screen appears, check the HDC connection and device debugging authorization first.

      Step 4

      Run an action and verify the result

      On your HarmonyOS device, open the system browser and complete any first-run prompts. Enter the following TodoMVC URL in the address bar:

      https://todomvc.com/examples/react/dist/#/

      Keep the device unlocked with the browser in the foreground.

      1. In Playground, select aiAct, enter the following instruction, and run it:
      Add a todo named "Try Midscene", then mark it as completed.
      1. Once the completed todo item appears on the page, switch to aiAssert, enter the following assertion, and run it:
      The list contains a todo named "Try Midscene", and it is marked as completed.

      1. Confirm that the assertion passes and inspect the step-by-step screenshots in the results panel. At this point, HDC connectivity, screen capture, touch input, and model calls have all been verified together.

      2. (Optional) Switch to aiQuery, enter the following query, and run it:

      Return the visible todo items as {name: string, completed: boolean}[].

      The result contains each todo item's name and completion status. aiQuery extracts data from the current UI without changing the page.

      If execution fails, check the failed step and error message: for missing screenshots or unresponsive touch input, see the FAQ; for model request errors, see Verify model connectivity.

      After verification, delete the "Try Midscene" item in TodoMVC. If you plan to run the Midscene Test HarmonyOS example next, switch to the All filter and make sure the list is completely empty (including completed items), as the example template checks for an empty list before running and does not overwrite existing items.

      Step 5

      Next steps

      • Explore more examples: Showcases includes demo videos and full execution reports across platforms.
      • Learn how Midscene works: The Basics explains the vision-based approach and when to use aiAct, instant actions, and insight APIs.

      Want to try another platform or way to use Midscene? Back to top to change your selections.