> For the complete documentation index, see [llms.txt](https://guides.moonlight.zip/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://guides.moonlight.zip/getting-started.md).

# Getting Started!

## Getting Started with Moonlight

Follow these steps in order. Basic Moonlight setup takes only a few minutes. Capture hardware, network video, and Moonlink wiring can take longer.

### Before You Begin

On the PC that will run Moonlight:

* Install current Windows updates.
* Install the latest stable driver for your NVIDIA, AMD, or Intel GPU.
* Sync the Windows clock: **Settings > Time & language > Date & time > Sync now**.
* Use a stable internet connection for login, model access, and Marketplace content.
* Download the latest complete release for your purchased edition from the official dashboard.
* Close other capture, serial, flashing, and device-control applications during setup.

Use [Optimize Windows for Moonlight](https://guides.moonlight.zip/optimize/optimize-windows-for-moonlight) for the current Windows preparation instructions.

The customer release does **not** require Python, PyTorch, Visual Studio, the CUDA Toolkit, or developer source files.

### Understand the Setup

* The **Moonlight PC** runs Moonlight and processes the video feed.
* The **target PC or console** runs the game and receives the configured mouse or controller output.

### Confirm Your Edition

Use the edition that matches your purchase and intended setup.

| Edition               | Detection           | Capture choices                                                    | Output choices                                |
| --------------------- | ------------------- | ------------------------------------------------------------------ | --------------------------------------------- |
| **Moonlight AI**      | AI detection models | Capture Card, Magewell SDK, NDI-V2, Screenshot, UDP, Chiaki Bridge | Supported mouse and controller output devices |
| **Moonlight Color**   | Color detection     | Capture Card, Magewell SDK, NDI-V2, Screenshot, UDP, Chiaki Bridge | Supported mouse and controller output devices |
| **Moonlight Console** | AI detection models | Capture Card or Magewell SDK                                       | Titan Two or Makcu Controller                 |

Moonlight Console hides capture and output choices that it does not support. Moonlight Color uses its color detector and does not require an AI detection model.

Different purchased editions can run concurrently. Opening the **same edition** on another PC can end the first PC's session.

### Step 1: Install and Sign In

1. Close Moonlight and any old companion/device processes.
2. Extract the **entire** official release to `C:\MoonLightAI`.
3. Confirm the launcher is `C:\MoonLightAI\Moonlight.exe`.
4. Open `Moonlight.exe` normally.
5. Select the purchased edition and complete the in-app login.

Do not run Moonlight from inside the downloaded archive, from a nested `MoonLightAI\MoonLightAI` folder, or by opening an individual DLL, `.pyd`, Python file, or `Loader.py`.

Do not make **Run as administrator** a permanent blanket step. Moonlight requests Windows administrator approval for the individual system changes that require it.

#### Updating an Existing Installation

1. Back up personal configuration files if the release notes tell you that migration is required.
2. Stop Moonlight and close companion/device utilities.
3. Install the complete new release using the instructions supplied with that release.
4. Do not combine files from different versions.
5. Confirm the version shown by Moonlight before testing.

Never repair a customer release by copying an old `runtime` folder, DLL, `.pyd`, or file from a developer machine.

### Step 2: Run the Windows Setup Check

From the login screen, select **Install / Optimize This PC**.

The setup tool scans the PC and presents the applicable options. Select the changes you want and approve the Windows administrator prompt only when it appears. Some actions do not require elevation.

If the tool changes Hardware-Accelerated GPU Scheduling or another Windows-level option, restart Windows before performance testing.

### Step 3: Set Up the Output Device

The output device sends movement from Moonlight to the target PC or console. Configure and test it before tuning detection.

| Device               | Initial setup                                                                                                           |
| -------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| **Moonlink Direct**  | Install the current Moonlink companion, connect the supported hardware, and flash the firmware intended for that board. |
| **MAKCU**            | Connect the device. Moonlight normally identifies its COM port by USB identity.                                         |
| **Medius**           | Connect a supported device running current Medius firmware. Moonlight normally identifies its COM port automatically.   |
| **Ferrum**           | Connect the device and select its COM port.                                                                             |
| **KMBox**            | Connect the supported wired device and select its COM port.                                                             |
| **Titan Two**        | Connect it and confirm Windows detects its interfaces. This is a supported Console output choice.                       |
| **Makcu Controller** | Connect the controller adapter. Moonlight normally locates its COM port automatically.                                  |

#### Moonlink Direct

Verify the complete hardware path:

1. Run Moonlink Flash.exe to flash the board.
2. For Arduino hardware wiring, use the guide for the exact board:

* [Arduino Due Moonlink Guide](https://guides.moonlight.zip/guides/arduino-section-legacy/arduino-due-section/due-ml)
* [Arduino Leonardo Moonlink Guide](https://guides.moonlight.zip/guides/arduino-section-legacy/arduino-leonardo-section/leo-ml)

1. Start the current Moonlink companion.
2. Confirm physical movement, buttons, and scroll reach the target correctly before starting Moonlight.
3. Select **Moonlink Direct** under **Input Device in Moonlight Client**.

#### Serial Devices

* Ferrum and KMBox require a selected COM port.
* MAKCU, Medius, and Makcu Controller are normally identified automatically.
* Close serial monitors, firmware flashing tools, and duplicate Moonlight processes.
* If a port is busy or disappears, reconnect the device and use the current refresh control before changing unrelated settings.

### Step 4: Set Up Video Capture

Choose one capture path for the actual setup.

| Situation                                       | Starting choice                           |
| ----------------------------------------------- | ----------------------------------------- |
| Dedicated capture card                          | **Capture Card**                          |
| Supported Magewell Pro Capture card             | **Magewell SDK**                          |
| Single PC without a capture card                | **Screenshot**                            |
| Two PCs on a reliable local network             | **NDI-V2**                                |
| Network stream requiring manual stream settings | **UDP**                                   |
| Supported PlayStation remote-play bridge        | **Chiaki Bridge (Not Available)**         |
| Moonlight Console edition                       | **Capture Card** or **Magewell SDK** only |

#### Capture Card

Choose the guide that matches the physical video path:

* [OBS Projector Capture Card Setup](https://guides.moonlight.zip/guides/capture-card/obs-capture-card-setup-guide)
* [Passthrough Capture Card Setup](https://guides.moonlight.zip/guides/capture-card/passthrough-capture-card-guide)

Before opening Moonlight, confirm Windows and the capture-card utility can see a stable signal. Close OBS, browser capture, camera software, or another Moonlight instance if it is holding the device.

In **Capture**, choose the device by name and select a resolution, frame rate, and pixel format the device actually reports. Capture FPS is the rate delivered by the capture source; it is not automatically the target monitor's refresh rate.

The current customer capture path uses **Native DirectShow C++**. Do not select instructions written for removed legacy capture methods.

#### NDI-V2

Choose the guide that matches the network layout:

* [NDI Network Switch](https://guides.moonlight.zip/guides/ndi/network-switch)
* [NDI Direct PC-to-PC](https://guides.moonlight.zip/guides/ndi/direct-pc-to-pc-link)

Start the sender first, allow NDI through the firewall on both PCs, and select the advertised source in Moonlight. A wired network is strongly preferred.

#### UDP

Choose the guide that matches the network layout:

* [UDP Network Switch](https://guides.moonlight.zip/guides/udp/network-switch)
* [UDP Direct PC-to-PC](https://guides.moonlight.zip/guides/udp/direct-pc-to-pc-link)

The sender and Moonlight must use matching IP, port, and stream settings. Allow the selected port through the firewall and confirm another application is not already listening on it.

#### Screenshot

Use Screenshot for supported single-PC configurations. Select the correct display and keep the Windows desktop unlocked. Remote Desktop, screen recorders, overlays, and other display-duplication applications can interfere with capture.

#### Chiaki Bridge (Not currently Available)

Chiaki Bridge is an advanced capture path. Start the supported bridge and confirm its configured feed is available before starting Moonlight.

### Step 5: Complete the Current In-App Setup

Moonlight may show an initial setup flow after the first successful login for an edition. Follow the controls shown by the current build, then verify the saved values in the main interface.

The current setup does **not** require selecting a named Aim preset. Configure aim behavior through the current Aim controls and the selected configuration profile.

Verify these items before starting:

* **Capture**: capture mode, source, resolution, frame rate, and format.
* **Detection**: the intended model and supported backend for Moonlight AI or Console.
* **Color**: the current color-detector settings for Moonlight Color.
* **Input Device**: the output device and COM port when one is required.
* **Game Profiles > Calibration**: the game-specific calibration values required by the setup.
* Mouse setups: real hardware DPI, exact in-game sensitivity, and correct FOV.
* Controller setups: the current controller calibration and sensitivity values.

To reopen the setup flow, use **Game Profiles > Calibration > Setup Wizard**.

For detailed settings, use:

* [Moonlight AI Configuration Overview](https://guides.moonlight.zip/overviews/moonlight-ai-configuration-overview)
* [Moonlight Color Settings Overview](https://guides.moonlight.zip/overviews/moonlight-color-settings-overview)

### Step 6: Select or Import a Configuration

Moonlight lists configuration profiles on the **Configs** page.

For a trusted community `.json` configuration supplied through the official Moonlight community:

1. Stop Moonlight.
2. Place the complete `.json` file in `C:\MoonLightAI\configs\`.
3. Open **Configs** and select **Refresh List** if the file has not appeared automatically.
4. Select the configuration.
5. Recheck every setup-specific value before starting.

Recheck at least:

* Edition and game.
* Capture source, resolution, frame rate, and format.
* Output device and COM port.
* Detection model and backend.
* DPI, in-game sensitivity, FOV, and assigned keys.

Community profiles are starting points. Do not change physical DPI or game settings blindly to copy another person's setup. Change one value at a time and test in a repeatable practice environment.

Marketplace Game Packs and Targeting Models use their own in-app import flow. Do not manually merge Marketplace assets with ordinary configuration files.

### Step 7: Start Moonlight and Verify the Pipeline

1. Start the game or video sender and confirm the intended scene is visible.
2. Start the Moonlink companion or other required device service.
3. Open **Aim** and turn on **Aim Enabled**.
4. Confirm the Aim key is correct. Aim and Flick should not use the same key.
5. Click **Start Moonlight** in the **Live Preview** header.
6. Wait for startup to complete.

If **Cannot Start - Issues Found** appears, use the listed model, capture, device, or COM-port problem as the next action. Correct that item and Start again.

If the UI displays **Restart required** and the button says **Stop to Apply Changes**, click **Stop to Apply Changes**, then click **Start Moonlight**. This restarts the Moonlight runtime only. It does not tell you to close the application or restart Windows.

Test in a practice range, training area, or private environment:

* The Live Preview shows the correct source and is not frozen.
* Capture FPS is non-zero and matches what the source can actually deliver.
* Detection processing is active in AI/Console, or color detection is active in Color.
* Latency remains stable instead of repeatedly climbing.
* Target boxes appear on valid targets.
* Holding the configured Aim key produces output through the selected device.
* Physical movement, buttons, and scroll still work when using passthrough hardware.

There is no universal correct detection-rate or latency number. Model size, input resolution, GPU, capture path, and backend all affect the result. Stable end-to-end behavior matters more than matching another PC's number.

### Step 8: Establish a Stable Baseline

Before advanced tuning:

* Verify DPI, in-game sensitivity, FOV, capture geometry, and output device.
* Start from the current configuration's default values.
* Leave advanced prediction, extra lead, recoil, neural, and experimental controls unchanged for the first test.
* Test target acquisition, tracking, release, and reacquisition.
* Change one setting at a time and repeat the same test.

High lead or prediction values can amplify noisy target motion. Establish stable normal tracking before adding more latency compensation.

### Detection Backend Quick Guide

| Backend      | Starting use                                     | Important behavior                                                                     |
| ------------ | ------------------------------------------------ | -------------------------------------------------------------------------------------- |
| **ONNX**     | General starting point on supported hardware     | Use the provider selected by the current build and GPU support.                        |
| **TensorRT** | Supported NVIDIA configurations                  | The first start can take longer while a local model cache is built.                    |
| **OpenVINO** | Supported Intel, CPU, or OpenVINO configurations | Start with the current automatic device choice unless a specific guide says otherwise. |

Changing a model, backend, capture source/format, or output device while the runtime is active may require Stop and Start. The UI will show **Restart required** only when a changed setting requires it.

#### Rebuilding a TensorRT Cache

If the cache is damaged or Moonlight explicitly reports a cache problem:

1. Stop Moonlight.
2. Open **Detection > Model Settings > TRT Optimization**.
3. Select **Rebuild TRT Cache**.
4. Start Moonlight and allow the rebuild to finish.

Do not delete protected `.enc` or ONNX model files. Do not install the CUDA Toolkit or Python packages to repair a customer build.

### Common First-Time Problems

#### Wrong Install Location

The complete folder must be `C:\MoonLightAI`, with `Moonlight.exe` directly inside it. Move the entire folder; do not move only the executable.

#### `No module named 'widgets'` or another missing component

The release is incomplete, mixed with another version, or a file was quarantined. Save the current log, check Windows Security **Protection history**, and reinstall the complete official release. Do not download the missing file by itself.

#### Authentication or clock error

Sync the Windows clock, install Windows updates, temporarily remove VPN/proxy filtering from the test, and confirm the correct account and edition.

#### Your session ended / Runtime session inactive

Close the same Moonlight edition on another PC, restore the network connection, and log in again inside Moonlight. Session reauthentication does not require an application restart.

#### Capture is waiting, black, or frozen

* Confirm the source is active before Start.
* Confirm the selected device name and supported format.
* Close other applications using the source.
* For NDI-V2 or UDP, verify the sender, network, firewall, and stream settings.
* For Screenshot, unlock the desktop and close competing capture or remote-desktop software.

#### Moonlink Direct does not connect

Close duplicate companion processes, start the current Moonlink companion, verify the hardware independently, then Stop and Start Moonlight.

#### A serial device or COM port does not open

Close flashing and serial tools, reconnect the device, refresh the port list, and select the correct port when manual selection is required.

#### First TensorRT start takes much longer than later starts

Allow the first cache build to finish while progress is changing. Use **Rebuild TRT Cache** only after stopping Moonlight and only when the cache is suspected or reported to be damaged.

#### Low or unstable capture/detection performance

* Confirm the capture source is delivering the configured rate.
* Test the default supported backend and a smaller model.
* Update the GPU driver and run **Install / Optimize This PC**.
* Close overlays, recorders, browser video, and heavy background applications.
* Check CPU/GPU temperatures and power limits on laptops and mini PCs.

Do not install CUDA, Python, or random runtime packages as a generic performance fix.

#### A setting does not appear to apply

Look for **Restart required**. If it appears, use **Stop to Apply Changes**, then Start again. Settings that do not show this state are expected to update normally; if one has no effect, record the old and new values and report it.

#### Moonlight closes or shows a traceback

Take a full screenshot and save the current `_app_log.log` before reopening Moonlight. Use the current [Moonlight AI Troubleshooting Guide](https://guides.moonlight.zip/troubleshoot/moonlight-ai-troubleshooting), then report repeatable failures on the complete current release.

### Getting Help and Sending Logs

When the runtime is active, select **Upload Logs** and open a private support ticket with the resulting information.

If Moonlight cannot Start, attach the file ending in `_app_log.log` from `C:\MoonLightAI` manually.

**Save the log before reopening Moonlight.** The application log is recreated on launch, so reopening the app can replace the session containing the useful error.

Include:

* A full screenshot of the error.
* Moonlight version and edition.
* Windows version.
* Capture mode, source, resolution, FPS, and format.
* Detection model and backend.
* Output device and COM port, if applicable.
* Exact steps that reproduce the issue.
* Moonlink companion and firmware versions when Moonlink is involved.

Upload Logs requires an active runtime. If the runtime is not active, preserve and send the application log manually. Send diagnostics only through private support.

### Do Not Use Developer Repairs

Customer builds are complete releases. Customers should not:

* Run `Loader.py`, `loader.py`, release-parity scripts, tests, or `.pyx` files.
* Install packages with `pip`.
* Install PyTorch or the CUDA Toolkit to restore a shipped feature.
* Copy DLLs, `.pyd` files, source files, or a `runtime` folder from another machine.
* Delete protected `.enc` or ONNX model files to rebuild a cache.
* Edit HWID, session, edition, or authentication data.
* Flash firmware not supplied for the exact supported board.

If a customer build appears to require one of these actions, capture the exact message and contact support. It is a release/support issue, not a customer setup step.

### Quick Setup Order

1. Update Windows and the GPU driver; sync the clock.
2. Install the complete release at `C:\MoonLightAI`.
3. Select the purchased edition and log in.
4. Run **Install / Optimize This PC** and restart Windows only if requested.
5. Configure and independently verify the output device.
6. Configure and independently verify the capture source.
7. Verify detection, calibration, DPI/sensitivity, FOV, keys, and the selected config.
8. Turn on **Aim Enabled** and select **Start Moonlight** in the Live Preview header.
9. Verify preview, processing, target detection, and final device output.
10. Establish a stable baseline before changing advanced settings.

### Related Guides

* [Moonlink Overview](https://guides.moonlight.zip/overviews/moonlink-overview)
* [Arduino Due Moonlink Guide](https://guides.moonlight.zip/guides/arduino-section-legacy/arduino-due-section/due-ml)
* [Arduino Leonardo Moonlink Guide](https://guides.moonlight.zip/guides/arduino-section-legacy/arduino-leonardo-section/leo-ml)
* [OBS Projector Capture Card Setup](https://guides.moonlight.zip/guides/capture-card/obs-capture-card-setup-guide)
* [Passthrough Capture Card Setup](https://guides.moonlight.zip/guides/capture-card/passthrough-capture-card-guide)
* [NDI Network Switch](https://guides.moonlight.zip/guides/ndi/network-switch)
* [NDI Direct PC-to-PC](https://guides.moonlight.zip/guides/ndi/direct-pc-to-pc-link)
* [UDP Network Switch](https://guides.moonlight.zip/guides/udp/network-switch)
* [UDP Direct PC-to-PC](https://guides.moonlight.zip/guides/udp/direct-pc-to-pc-link)
* [Moonlight AI Configuration Overview](https://guides.moonlight.zip/overviews/moonlight-ai-configuration-overview)
* [Moonlight AI Troubleshooting](https://guides.moonlight.zip/troubleshoot/moonlight-ai-troubleshooting)
* [Moonlight Color Settings Overview](https://guides.moonlight.zip/overviews/moonlight-color-settings-overview)
* [Optimize Windows for Moonlight](https://guides.moonlight.zip/optimize/optimize-windows-for-moonlight)