> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# Get started: Desktop · Playground · Model API Key {#get-started}

These are the setup steps for Midscene on **Desktop** with **Playground** and a **Model API Key**. To choose another combination, see [all setup paths](/get-started.md#all-setup-paths).

## Grant desktop permissions
- **macOS**: Grant two separate system permissions to the terminal or IDE that launches Playground or runs your scripts (such as Terminal, iTerm2, VS Code, Cursor, or WebStorm):
  1. **Accessibility** (for mouse and keyboard control): Enable your terminal or IDE in **System Settings > Privacy & Security > Accessibility** (see [nut.js macOS setup](https://github.com/nut-tree/nut.js#macos)).
  2. **Screen Recording** (for desktop screenshots): Enable your terminal or IDE in **System Settings > Privacy & Security > Screen Recording**. **After granting access, completely quit and relaunch the terminal or IDE** before starting Playground.
- **Windows**: No extra setup is required for standard applications. However, Windows User Interface Privilege Isolation (UIPI) blocks non-elevated processes from injecting mouse clicks or keystrokes into windows running **as Administrator** (the cursor still moves to the target coordinates, but clicks and key presses are silently dropped). Prefer running the target app without Administrator privileges; if it must run elevated, launch the terminal or Node.js process running Midscene **as Administrator** as well (see [Windows: clicks have no effect on some apps](/platforms/desktop.md#windows-clicks-have-no-effect-on-some-apps)).
- **Linux (desktop GUI)**: Install [ImageMagick](https://imagemagick.org/script/download.php) for screen capture support.
- **Linux (headless server / CI)**: To run desktop automation on a headless Linux host (such as GitHub Actions), install Xvfb and ImageMagick, then enable headless mode to start a virtual display automatically:

```bash
# Install dependencies
sudo apt-get install -y xvfb x11-xserver-utils imagemagick
```

When using Xvfb, make sure the target application is started inside the same virtual display environment (not needed on machines with a physical display).
To control a remote Windows desktop over RDP, see [Desktop environment setup](/platforms/desktop.md#connect-device).

## 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.

The configuration below is for Doubao-Seed-2.1 Turbo. Other recommended models:

- [Qwen3.7 Plus](/model-api-setup.md#qwen) (Alibaba)
- [DeepSeek V4.1 Flash](/model-api-setup.md#deepseek) (DeepSeek)
- [Gemini 3.5 Flash](/model-api-setup.md#gemini) (Google)
- [GPT-6 Sol](/model-api-setup.md#gpt) (OpenAI)
- [Kimi K3](/model-api-setup.md#kimi) (Moonshot AI)
- [MiMo V2.6 Pro](/model-api-setup.md#xiaomi-mimo) (Xiaomi)
- [GLM-5V-Turbo](/model-api-setup.md#glm-v) (Zhipu AI)
- [Ling-3.0-flash-VL](/model-api-setup.md#ant-ling) (Ant Group)

**Volcano Engine** ([Get API key](https://console.volcengine.com/ark))

```bash
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"
```

**OpenRouter** ([Get API key](https://openrouter.ai/settings/keys))

```bash
MIDSCENE_MODEL_BASE_URL="https://openrouter.ai/api/v1"
MIDSCENE_MODEL_API_KEY="......"
MIDSCENE_MODEL_NAME="bytedance-seed/seed-2-1-turbo"
MIDSCENE_MODEL_FAMILY="doubao-seed"
```

For other versions and usage notes, see [Doubao Seed series](/model-api-setup.md#doubao-seed-model).

To compare models, see the [Model selection guide](/model-selection.md). For compatible models such as UI-TARS, see [Use a model API key](/model-api-setup.md#supported-models).

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

## 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 Desktop Playground CLI:

```bash
pnpm dlx @midscene/computer-playground
```

On headless Linux, enable a virtual display with the following command and run the target application in that same display:

```bash
MIDSCENE_COMPUTER_HEADLESS_LINUX=true pnpm dlx @midscene/computer-playground
```

2. In the Playground window that opens, click the gear icon in the top-right corner, paste your model configuration, and save.
3. If your browser does not open automatically, visit the local Playground URL printed in the terminal, and keep the terminal process running.
4. In the connection panel on the left, select the target **Display** to control, create the Agent, and place the target application window on that display.
5. Confirm that the preview area shows the live screen of the selected display. If the preview is blank or fails to load, check the Screen Recording permission or Linux dependencies above.

## Run an action and verify the result

Open a browser window on the target display and enter the following TodoMVC URL in the address bar:

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

Position the windows so that the Playground tab does not cover the TodoMVC page.

1. In Playground, select `aiAct`, enter the following instruction, and run it (avoid moving the mouse or typing while the action is running):

```text
Add a todo named "Try Midscene", then mark it as completed.
```

2. Once the completed todo item appears on the page, switch to `aiAssert`, enter the following assertion, and run it:

```text
The list contains a todo named "Try Midscene", and it is marked as completed.
```

3. Confirm that the assertion passes and inspect the step-by-step screenshots in the results panel. At this point, desktop screen capture, mouse/keyboard input, and model calls have all been verified together.

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

```text
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 mouse/keyboard input, see the [FAQ](/platforms/desktop.md#faq); for model request errors, see [Verify model connectivity](/model-config.md#verify-model-connectivity).

After verification, delete the "Try Midscene" item in TodoMVC. If you plan to run the Midscene Test Desktop 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.

## Next steps
- **Explore more examples**: [Showcases](/showcases.md) includes demo videos and full execution reports across platforms.

- **Write repeatable cases**: [Create a Midscene Test project](/get-started/desktop-test-api-key.md) with the same platform and model. Cases are YAML files that you can run locally or in CI.

- **Add to Vitest**: [Call Midscene from your Vitest tests](/get-started/desktop-sdk-api-key.md) with the same platform and model.

- **Learn how Midscene works**: [The Basics](/basics.md) explains the vision-based approach and when to use `aiAct`, instant actions, and insight APIs.