# Run QH Pixels locally

## Before you start

Install Node.js 24 or newer and Git. FFmpeg is needed for GIF and MP4 export. QH Pixels currently runs from source; there is no packaged application installer linked here.

## Start the development studio

1. [Clone the source](https://github.com/qentrah/qh-pixels):

   ```sh
   git clone https://github.com/qentrah/qh-pixels.git
   cd qh-pixels
   ```

2. Install the locked dependencies:

   ```sh
   npm ci
   ```

3. Start the API and development preview:

   ```sh
   npm run dev
   ```

4. Open [the local studio](http://127.0.0.1:8094). The API runs at `http://127.0.0.1:8095`.

You should see the workspace sidebar, character motions, preview, and frame timeline. Use [the MCP guide](/docs/qh-pixels/connect-agent) to connect an authoring agent.

## Run the production bundle

Stop the development server before using the same API port:

```sh
npm run build
npm start
```

Open [the bundled studio](http://127.0.0.1:8095).

## Check the installation

```sh
npm test
npm run build
```

If a server reports that its port is already in use, stop your earlier QH Pixels process before restarting it. If dependencies fail to install, check `node --version` and use Node.js 24 or newer. GIF and MP4 export also require FFmpeg; see the [repository checks and recording instructions](https://github.com/qentrah/qh-pixels#checks-and-reproducible-assets).