Terminal-based, real-time traffic monitoring and statistics for your AdGuard Home instanceView on GitHub
Terminal-based, real-time traffic monitoring and statistics for your AdGuard Home instance
AdGuardian Terminal Eddition - Keep an eye on your traffic, with this (unofficial) buddy for your AdGuard Home instance
AdGuard Home is a free and open source self-hosted (or managed) network-wide ad + tracker blocker. It operates as a DNS server that re-routes tracking domains to a "black hole", thus preventing your devices from connecting to those servers. It makes your internet, faster, safer and gives you a bunch of useful features, like encrypted DNS (DoH, DoT, DNSCrypt), parental controls, blocking of malware / phishing, per-device configs, custom DNS rules, etc.
There are several options for running...
docker run -it lissy93/adguardian
You may also pass in your AdGuard info with env vars (using
-e), see the Configuring section for an example, and list of availible config params.
If you experience issues with DockerHub, or would rather use a different registry, the image is also available via GHCR - just replace the image name with:
ghcr.io/lissy93/adguardian. Alternatively, if you'd like to build it yourself from source, you can do so with
docker buildx build -t adguardian .then run it with
docker run -it adguardian.
curl -o adguardian https://github.com/Lissy93/AdGuardian-Term/releases/latest/download/adguardian-linux && \ chmod +x adguardian && \ ./adguardian
In the above example, don't forget to update the URL to download the latest stable version for your operating system
You may also just head over the the Releases tab, download the latest executable, and double-click on it to run
cargo install adguardian adguardian
AdGuardian is published as a crate to crates.io/crates/adguardian. So providing you've got Cargo installed, you can pull the binary directly, and then execute it as above. Again, see the Configuring section below for how to pass in your AdGuard info.
git clone [email protected]:Lissy93/AdGuardian-Term.git && \ cd AdGuardian-Term && \ make
make(see here for installation notes). You can also run the cargo commands defined in the Makefile directly, e.g.
scoop install extras/adguardian
For Windows users, AdGuardian is availible via the Scoop package manager, as part of the
extrasbucket - You'll need Scoop installed, then follow these instructions. This was contributed by @kzshantonu in ScoopInstaller/Extras#11386
bash <(curl -sL https://raw.githubusercontent.com/Lissy93/AdGuardian-Term/main/quick-start.sh)
This will run the quick-start.sh Bash script, which downloads and executes the latest binary for your system type. Be sure to read and understand the file first
The app requires the details of an AdGuard instance to connect to. This info can be provided either as environmental variables, or passed in as flag parameters. If any of these fields are missing or incomplete, you'll be prompted to enter a value once the app starts.
The following params are accepted:
--adguard-ip- The IP address of your local AdGuard Home instance
--adguard-port- The port that AdGuard is running on
--adguard-username- An AdGuard Home username
--adguard-password- An AdGuard Home password
There's also some additional optional environment variables that you may set:
ADGUARD_PROTOCOL- The protocol to use when connecting to AdGuard (defaults to
ADGUARD_UPDATE_INTERVAL- The rate at which to refresh the UI in seconds (defaults to
adguardian -- \ --adguard-ip "192.168.180.1" \ --adguard-port "3000" \ --adguard-username "admin" \ --adguard-password "bobs-your-uncle"
ADGUARD_IP="192.168.180.1" ADGUARD_PORT="3000" ADGUARD_USERNAME="admin" ADGUARD_PASSWORD="bobs-your-uncle" adguardian
docker run \ -e "ADGUARD_IP=192.168.180.1" \ -e "ADGUARD_PORT=3000" \ -e "ADGUARD_USERNAME=admin" \ -e "ADGUARD_PASSWORD=bobs-your-uncle" \ -it lissy93/adguardian
The terminal dashboard can also be viewed via a browser, thanks to ttyd.
AdGuardian is fully compatible with ttyd, so once you've installed it, you can just precede your run command with ttyd.
ttyd docker run -it lissy93/adguardian or
This might be useful for embedding into another app or dashboard (like Dashy 😉 - although Dashy already has an AdGuard widget!)
Another great option is gotty, which works in a similar way. Note that if you want to allow user input, you'll need to pass the
You can also combine this with a service like ngrok to forward the port, and access the dashboard from anywhere. But be careful to apply the correct access controls!
Then clone the repo, and cd into it, with:
git clone [email protected]:Lissy93/AdGuardian-Term.git &&
You can view the full list of availible project commands in the Makefile
To build and run the project for development, run
The documentation can be viewed at:
cargo test- Run unit tests
cargo check- Ensure app is compilable
cargo bench- Execute benchmarks
cargo clippy- Analyse areas for improvement
cargo doc- Generate the documentation
Once your finished developing, you can build the project for production with:
cargo build --release
The binaries for your system will then be available in the
./target/release/ directory of the project.
You can execute this directly, e.g. by running
./target/release/adguardian (add .exe if on Windows)
The testing, building, and publishing of the app is done with GitHub Actions.
This project was made possible by the maintainers of the following dependencies
A mirror of this repository is published at: codeberg.org/alicia/adguardian
To get started, fork the repo, make your changes, add, commit and push the code, then come back here to open a pull request. If you're new to GitHub or open source, this guide or the git docs may help you get started, but feel free to reach out if you need any support.
You can support the project in other ways too, drop us a star, consider sponsoring us on GitHub, share within your network, and report any bugs you come across.
The MIT License (MIT) Copyright (c) Alicia Sykes <[email protected]> Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sub-license, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included install copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANT ABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NON INFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.