Getting started

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 for the current Windows preparation instructions.

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

#Two ways to set up

Moonlight runs on its own PC, not on the one you play on.

• Two PCs. The gaming PC runs the game. The Moonlight PC runs Moonlight, reads the picture and sends the output back through an output device. Most of these guides describe this setup.
• Console. A PS5 or Xbox runs the game, and the Moonlight PC runs Moonlight Console. Follow Console setup alongside this page; it covers the picture, the controller output and tuning for a controller.

#Confirm your edition

Use the edition that matches your purchase and intended setup.

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.

The login screen has a Use the web panel instead of the app window checkbox. With it ticked, the main window stays hidden after sign-in and a tray icon offers Open Moonlight window and Quit. It also turns web control on.

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.

#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
• Arduino Leonardo Moonlink Guide

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, Ferrum Controller 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.

#Capture card

Try the methods in this order. Display clone adds the least delay; OBS projector adds the most.

1. Display Clone Capture Card Setup (preferred)
2. Passthrough Capture Card Setup
3. OBS Projector Capture Card Setup

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
• NDI Direct PC-to-PC

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
• UDP Direct PC-to-PC

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.

#Moonlight Stream

Sunshine on the gaming PC streams its picture to Moonlight over your network. Pair once with the four-digit PIN Sunshine asks for. See Moonlight Stream.

#PS5 Remote Play

Moonlight reads a PS5's picture over your home network and, with PS5 Remote Play as the output device too, sends your controller back to it. Pair the PS5 once. See PS5 Remote Play.

For a console on a capture card, see Capture card for a console.

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

Moonlight AI and Console ship without detection models. If none is installed, the setup's model page says so, and finishing setup opens Marketplace > Targeting Models so you can get one for your game.

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: a linear response curve in the game, then In-game Stick Sensitivity and Deadzone Compensation in Moonlight. See Tune aim for a controller.

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

For detailed settings, use:

• Moonlight AI Configuration Overview
• Moonlight Color Settings Overview

#Step 6: Select or import a configuration

Moonlight lists configuration profiles on the Configs page.

To get community configs, use Configs → Community configs → Browse community configs.

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\<edition>\ (ai, console or color).
3. Select Refresh List next to Config in the top bar 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.
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

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 > Backend & Model (Backend set to TensorRT).
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.

#New PC, reinstalled Windows, or changed parts

Your account is tied to the PC it first ran on. After a Windows reinstall, a hardware change or a move to another PC, login will not complete until support resets it. Open a HWID reset ticket in the Moonlight Discord; nothing on the PC itself fixes this.

#Coming back after a long break

There is no license key any more: sign in with the Discord account you bought with. Accounts from before Discord login sometimes need linking once by staff, so open a ticket with your old username if login does not complete. Install the complete current release fresh; do not reuse an old folder or old Moonlink firmware.

#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 a capture card on a PS5, turn off Enable HDCP in the PS5's HDMI settings.
• For PS5 Remote Play or Moonlight Stream, check both devices are on the same network and paired.

#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. The runtimes Moonlight needs ship inside the Moonlight folder.

#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, then report repeatable failures on the complete current release.

#Getting help and sending logs

Post your question in the #support channel of the Moonlight Discord, which opens a support thread, and attach the file ending in _app_log.log from C:\MoonLightAI. Something private, such as an order or your account, goes in a ticket instead. You can also ask support to open a support session; web control must be on.

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.

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

• Console setup
• Moonlight Stream
• Moonlink Overview
• Arduino Due Moonlink Guide
• Arduino Leonardo Moonlink Guide
• Display Clone Capture Card Setup
• Passthrough Capture Card Setup
• OBS Projector Capture Card Setup
• NDI Network Switch
• NDI Direct PC-to-PC
• UDP Network Switch
• UDP Direct PC-to-PC
• Moonlight AI Configuration Overview
• Moonlight AI Troubleshooting
• Moonlight Color Settings Overview
• Optimize Windows for Moonlight