Network scripting and WinDivert

Some scripts inspect, change or block network packets while they run. This page covers what those scripts need on your PC: WinDivert, which you install yourself, and one administrator approval each time the script runs. Scripts that don't use the network need none of this.

Pre-release documentation: this page describes Atlas for Windows as built from source in September 2026, before public release. Labels and behavior can change before release.

What network scripting does

A script that declares on_network_recv or on_network_send and calls network.capture() receives the packets that match its filter. For each packet it can let it through, change it, or drop it. Packets that don't match the filter never reach the script.

Capturing packets needs a Windows driver, WinDivert, and a small Atlas helper, Atlas.NetworkBroker.exe, that runs with administrator rights. The helper only moves packets between Windows and Atlas; your script still runs inside Atlas. Capture stops when the script stops.

Writing these scripts is covered in the Atlas Script guide: Network events and Network capture and packets.

Before you start

A script that uses network events. Other scripts work without any of this.
A Windows account that can approve an administrator prompt, or someone who can approve it for you.
WinDivert 2.2.2, installed as described below. Atlas does not include or download it.

Install WinDivert

Atlas does not include WinDivert because it is licensed under the LGPL, so you install it yourself. Atlas then checks that the files are the official release before it uses them.

Open the official WinDivert 2.2.2 release page and download WinDivert-2.2.2-A.zip.
Open the zip and go to its x64 folder.
In File Explorer, create the folder C:\Program Files\Atlas\WinDivert. Windows asks for administrator permission, because it is under Program Files.
Copy WinDivert.dll and WinDivert64.sys from the zip's x64 folder into that folder.

You can use a different folder, but it must follow the same rules as Program Files. It must be a real folder, not a shortcut, junction or link, on a local fixed drive. Only administrators may be able to change it or any folder above it. Folders in your user profile, such as Downloads or Desktop, don't qualify. Atlas only checks a folder; it never changes its permissions.

Both files must be the unmodified 2.2.2 x64 files. The x86 folder's WinDivert.dll, or files from another WinDivert version, are refused.

Run a network script

Run the script. If Atlas can't use WinDivert, a Set up WinDivert window names the folder it checked and what is wrong:
- Yes opens a folder picker. Choose the folder that holds WinDivert.dll and WinDivert64.sys. Atlas checks it again before saving it and explains if it can't use it.
- No opens the official WinDivert download page.
- Cancel does nothing for now.
When the script starts capturing, Windows shows an administrator (UAC) prompt for Atlas.NetworkBroker.exe. Approve it to start capture. Atlas asks once each time you run a script; stopping the script closes the helper, so the next run asks again.

Capture covers all network interfaces. The Atlas window doesn't have an interface selector yet.

If you skip setup or decline the prompt

The script still runs; only packet capture is missing. If WinDivert isn't set up, the session log shows WinDivert is not set up, so on_network_recv and on_network_send will not fire. The script's network.capture() still opens the administrator prompt; after you approve it, the helper refuses to load WinDivert and network.error says what is missing. Install WinDivert, then stop the script and run it again.

If you decline the administrator prompt, the script's network.error reads Network capture needs administrator approval, and the prompt was declined. Restart the script to try again. Atlas doesn't ask again during that run. Stop the script and run it again to get a new prompt.

Troubleshooting

Atlas shows these messages in the Set up WinDivert window and in the script's network.error.

What you see	What to do
WinDivert.dll and WinDivert64.sys were not found in a folder	Put both files directly in the folder it names, not in a subfolder, or choose the folder that holds them.
Atlas could not open '…'. Check the WinDivert folder setting.	The folder does not exist yet, which is normal before you install WinDivert. Create it and copy the two files into it, or choose the folder that holds them.
… is not safe for Atlas to load a driver from because …	That folder, or a folder above it, can be changed by accounts other than administrators. Use a folder under `C:\Program Files`, as in Install WinDivert.
WinDivert.dll (or WinDivert64.sys) is not safe for Atlas to load because …	The file's own permissions let accounts other than administrators change it. Copy the files again into a folder under `C:\Program Files`, which gives them the folder's permissions.
… is a junction or shortcut.	Choose the real folder instead of a shortcut or link to it.
The WinDivert folder must be on a local fixed drive …	Move WinDivert off the network share, mapped drive or removable drive, to a folder under `C:\Program Files`.
… is not the official WinDivert 2.2.2 file Atlas expects.	Download WinDivert-2.2.2-A.zip again from the official release page and copy the two files from its x64 folder.
No administrator prompt appears.	Check `network.error`. The script hasn't called `network.capture()` yet; Atlas refused the filter (more than 2048 characters, characters other than printable ASCII, or unbalanced parentheses); the call came from a global variable's initializer or `on_stop`, where capture can't start; or the prompt was already declined, or the helper failed to start, earlier in this run. Stop the script and run it again.
`network.error` starts with Capture filter error:	WinDivert couldn't read the script's filter. The rest of the message says why; fix the filter in the script.
Network traffic slows down while the script runs.	Every matching packet waits for the script. A narrower filter sends fewer packets through it. If the script takes longer than 50 ms with a packet, Atlas lets it through unchanged and counts it in `network.failed_open`. A runtime error, such as running out of the instruction budget, also lets the packet through and is written to the session log.

For other problems, see Troubleshooting.

WinDivert licence

WinDivert is a separate open-source project, available under the LGPL-3.0 or the GPL-2.0. Atlas doesn't include or distribute it: you get it from the official release, and Atlas loads the copy you installed. Atlas shows its third-party notices the first time it starts.