Automate AdGuard Home on Windows 10

AdGuard Home is a free and open source DNS server that you can install on your computer or LAN to blocks ads & trackers. It’s highly configurable and is comparable to the more widely known Pi-Hole. AdGuard Home however is easier to setup locally and has a smaller footprint than Pi-Hole. It’s also available as a native Windows binary.

VDesk is a free and open-source utility that let’s you launch programs on new virtual desktops in Windows 10 using the command line. The automation capabilities of VDesk will allow us to fire up AdGuard non-interactively and also get it out of the way by launching it in a separate virtual desktop.

Download and Install VDesk

The VDesk releases page on GitHub has the latest version for download:

Download AdGuard Home

AdGuard Home for Windows can be found on GitHub here:

Extract and Configure AdGuard Home

After you’ve downloaded the ZIP file containing AdGuard, extract the content to a more-or-less permanent folder to run it (e.g. C:\Users\paramdeo\AdGuard).

The AdGuard folder contains AdGuardHome.exe, which upon first run will create a YAML file AdGuardHome.yaml that contains an initial configuration structure that stores among other things the username and password specified for the management portal.

If you didn’t specify a username and password for the portal upon first run, AdGuard will continue to prompt you for authentication options each time you run it.

If entered your credentials, then they would have been written to the YAML file and we can move on. If not, open that file and specify the credentials for the AdGuard portal by changing the following values:

auth_name: root auth_pass: root

Since the scope of this guide is automation not configuration, no other values need to be changed in order to run AdGuard Home non-interactively.

However, I do recommend editing bootstrap_dns: to use the value i.e. using Cloudflare’s DNS instead of Google’s DNS for obvious privacy reasons.

Script the VDesk Command

To run any program using VDesk, the syntax is pretty straightforward. For the purposes of AdGuard, I’ll run AdGuard and force it to open in my second virtual desktop, and also instruct Windows not to suddenly switch to the open program in that desktop. The command structure is as follows:

vdesk on:2 noswitch:true run:"C:\Users\paramdeo\AdGuard\AdGuardHome.exe"

As you can guess:

  • on:2 specifies the second virtual desktop. You should create this desktop first by pressing Windows Key + Tab and clicking New Desktop
  • noswitch:true explicity instructs Windows not to switch to that desktop when the program is opened
  • run: specifies the path and executable to run, which in this case is AdGuard

So, let’s create a batch file to store the above command. Open your preferred text editor and insert the following:

@ECHO OFF vdesk on:2 noswitch:true run:"C:\Users\paramdeo\AdGuard\AdGuardHome.exe"

Save that file as AdGuardHome.bat somewhere sensible, ideally in the same folder as AdGuard itself for ease of use.

Create Scheduled Task for AdGuard

  1. Find and open Task Scheduler (Control Panel > Administrative Tools) or just hit Windows Key + R and type taskschd.msc and press Enter.

  2. Click “Create Task” and give your task a name. I called mine AdGuard because I’m creative like that.

  3. Under “Security Options” choose Run only when user is logged on and Configure for Windows 10

  4. Under “Triggers” choose New and select At log on.

  5. Under “Actions” choose New and browse for the batch file you just created containing the VDesk command.

  6. Ideally, under “Conditions” disable the Start the task only if the computer is on AC power option.

  7. Also, under “Settings” disable the Stop the task if it runs longer than and enable the Allow task to be run on demand options.

Save and Test

After you’ve saved your task, right click it in the Task Scheduler Library list and hit Run. Once the task executes, press Windows Key + Tab and select your second virtual desktop and you should see AdGuard up and running.

The next logical step is to simply specify your DNS servers as and (for fallback) in your Wi-Fi or other network interface’s settings so that your local computer can now serve DNS queries to AdGuard’s upstream recursive resolvers.

Once AdGuard Home is running, open a browser and goto localhost:3000 to access the portal and see it in action. The AdGuard dashboard has lots of information and the accompanying options are very self-explanatory and easy to tweak.

Go ahead and browse some sites that have ads, you’ll notice a reduction or complete removal of ads and the accompanying statistics generated in the dashboard relative to queried domains as you browse.

As a plus, you can create a shortcut on your Bookmarks Bar that points to http://root:root@localhost:3000/ for easy access to the AdGuard dashboard when needed.


Since the launching of the nextdns project, I’ve decided to write a guide on using that HERE. While this tutorial still applies to running AdGuard locally, I’m now using nextdns for all my adblocking needs as it works across all devices when paired with a VPN and has a much larger selection of blocklists.