> 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 · Midscene Test · ChatGPT subscription {#get-started}

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

## Install Node.js
Install Node.js `^20.19.0 || ^22.12.0 || >=24.0.0`, then check that `node -v` works in your terminal.
The commands below use pnpm. If it is not installed yet, run `npm install -g pnpm`.

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

## Create a test project

```bash
pnpm dlx @midscene/test create my-tests \
  --platform computer \
  --package-manager pnpm
cd my-tests
```

The command generates the project files, installs dependencies, and generates the Node Spec. It does not run tests. For the generated files, see [Project structure](/midscene-test/use.md#project-structure).

## Sign in with your ChatGPT subscription
First, run the following command in your terminal:

```bash
pnpm dlx @midscene/cli model siwc login
```

Follow the terminal instructions to sign in to ChatGPT in your browser and authorize plan usage. You can choose a name for your Agent during authorization. Once authorized, the Agent appears on your ChatGPT usage page.

The command saves credentials to `~/.midscene/siwc.json`. Complete this sign-in manually before first use.

Then, in the `my-tests` directory, copy `.env.example` to `.env`:
```bash
cp .env.example .env
```
Leave `MIDSCENE_MODEL_BASE_URL` and `MIDSCENE_MODEL_API_KEY` empty. Set `MIDSCENE_MODEL_NAME` and `MIDSCENE_MODEL_FAMILY`, and add `MIDSCENE_MODEL_AUTH_MODE`:

```bash
MIDSCENE_MODEL_AUTH_MODE="siwc"
MIDSCENE_MODEL_NAME="gpt-6-sol"
MIDSCENE_MODEL_FAMILY="gpt-6"
```
Available models depend on your ChatGPT account. For credentials and usage, see [Use a ChatGPT subscription](/chatgpt-subscription.md#usage-and-credentials).

## Verify the model and finish setup
Verify model connectivity and Midscene compatibility. The command reads `.env` from the current directory and does not need a browser or device:
```bash
pnpm exec midscene-test model verify
```
If the check fails, see [Verify model connectivity](/model-config.md#verify-model-connectivity).

To control a display other than the primary one, set `COMPUTER_DISPLAY_ID` in `.env`. On headless Linux, also set `MIDSCENE_COMPUTER_HEADLESS_LINUX=true`.

## Run the example and inspect the report

The example opens React TodoMVC in a browser on the target display and first checks that the list is empty. Do not move the mouse or type while it runs. If todos remain from an earlier run, select **All** and delete every todo, including completed ones.

```bash
pnpm test
```
The terminal prints the results and a `Report:` path. Open the HTML report, then select a case and a step to inspect screenshots, inputs, outputs, and errors. Reports are written to `midscene_run/report/` by default.
When the case passes, your model, environment, and project are all working. For execution options, see [Run tests](/midscene-test/running.md).

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

- **Test your own app**: Open the target application on the controlled display, then describe the steps with `aiAct` and `aiAssert`. To start or reset the app from a case, [develop a custom Node](/midscene-test/extend.md).

- **Write and organize cases**: [Write YAML cases](/midscene-test/writing.md) covers inputs, variables, tags, and hooks.
- **Run in CI**: [Run in GitHub Actions](/midscene-test/running.md#run-in-github-actions).