🛡️ AdGuard VPN — DankMaterialShell Plugin

Control, monitor, and configure AdGuard VPN directly from your DankBar — no terminal needed. Language / Idioma: English is the primary documentation language. A Portuguese (Brazil) version is provided below for the same user-facing guidance.

✨ Features

Category	What you get
Live monitoring	Real-time status, account info, tunnel interface, SOCKS endpoint, and ranked locations
One-click actions	Connect / Disconnect / Fastest / Location quick-connect — Enter in the field connects too
Runtime config	Mode (TUN / SOCKS), Protocol (Auto / HTTP2 / QUIC), Update channel, DNS upstream
Location tools	Search & filter, city/country quick-connect, favorites pinned on top, "show more" paging
Resilience	Auto-connect on startup, auto-reconnect with 3-step backoff, connect preflight checks
Diagnostics	Last command log, tunnel log viewer, login-required banner with copyable command
Accessibility	Full keyboard navigation (Tab + Enter/Space) with visible focus and Accessible roles
Multilingual	22 fully translated languages (EN, PT-BR + 20 additional locales)
Tested parsers	ANSI-safe, multi-format CLI parsing covered by 31 unit tests in CI

📋 Requirements

Dependency	Version
DankMaterialShell	`>= 1.4.0`
`adguardvpn-cli`	Any recent version — install guide
AdGuard account	Logged in (`adguardvpn-cli login`)

🚀 Installation

Optional systemd-managed tunnel

By default the plugin invokes adguardvpn-cli directly, so it works without extra system services. Advanced setups can set useSystemdService: true in the plugin settings and provide /usr/local/sbin/adguardvpn-dms-control; in that mode connect and disconnect actions delegate the persistent tunnel to a root systemd service rather than leaving it in the DMS cgroup. Keep this opt-in unless the matching service and control wrapper have been installed.

A reference implementation ships in scripts/adguardvpn-dms-control:

sudo install -m 755 -o root -g root \
  scripts/adguardvpn-dms-control /usr/local/sbin/adguardvpn-dms-control

Then grant the desktop user a NOPASSWD sudoers rule for that exact path — the plugin always calls it through sudo -n, so an interactive prompt makes the action fail silently.

Write your own helper? Make connect-fastest and connect-location idempotent. systemctl restart tears the tunnel down for a few seconds: NetworkManager flags the interface as unmanaged, systemd-resolved swaps DNS servers, and every in-flight connection dies with it — downloads, SSH, long HTTP sessions. A helper that restarts unconditionally turns a no-op click ("connect to the location I'm already on") into a real network outage. The reference implementation exits 0 without restarting when the unit is already active and /var/lib/adguardvpn-dms/location already matches the requested target; --force restores the unconditional behaviour for deliberately re-picking a server.

1. Clone into DMS plugins directory

git clone https://github.com/bernardopg/dms-adguard-vpn-plugin.git \
  ~/.config/DankMaterialShell/plugins/adguardVPplugin

2. Reload & enable

dms ipc plugins reload adguardVPplugin
dms ipc plugins enable adguardVPplugin

3. Add to DankBar

Open DMS Settings → Widgets and add AdGuard VPN to your bar.

⚙️ Settings

All settings are configurable through the DMS plugin settings screen.

Setting	Type	Default	Description
`adguardBinary`	string	`adguardvpn-cli`	CLI binary name or absolute path
`refreshIntervalSec`	int	`8`	Status polling interval (3–120 s)
`locationsCount`	int	`20`	How many locations to fetch (5–100)
`connectStrategy`	enum	`fastest`	Default connect behavior: `fastest` or `location`
`defaultLocation`	string	—	Preferred location (city, country, or ISO code)
`ipStack`	enum	`auto`	Force `ipv4` or `ipv6` on connect
`autoRefreshLocations`	bool	`true`	Periodically refresh ranked server list
`autoConnectOnStartup`	bool	`false`	Auto-connect when plugin / session starts
`autoReconnectOnDrop`	bool	`false`	Auto-reconnect when the tunnel drops unexpectedly
`showLocationInBar`	bool	`true`	Display connection text next to bar icon
`bypassMultiRouteCheck`	bool	`false`	Skip the pre-connect multi-default-route check (Settings → Advanced) if it false-positives on your setup
`useSystemdService`	bool	`false`	Delegate connect/disconnect to the optional, separately installed `adguardvpn-dms-control` systemd helper
`languageOverride`	enum	`auto`	UI language: `auto`, `en_US`, `pt_BR`, `es_ES`, `zh_CN`, `hi_IN`, `ar`, `bn_BD`, `fr_FR`, `de_DE`, `ja_JP`, `ru_RU`, `ko_KR`, `id_ID`, `tr_TR`, `vi_VN`, `it_IT`, `pl_PL`, `nl_NL`, `fa_IR`, `th_TH`, `ur_PK`, `ms_MY`

🏗️ Project Structure

adguardVPplugin/
├── plugin.json                 # Manifest & permissions
├── qmldir                      # QML singleton registration
├── AdGuardVpnWidget.qml        # Bar pill + popout UI
├── AdGuardVpnSettings.qml      # DMS settings screen
├── AdGuardVpnService.qml       # Singleton: polling, actions, state
├── AdGuardVpnParsers.js        # CLI output parsers (status, config, license, locations)
├── AdGuardVpnI18n.qml          # Localization singleton
├── i18n/
│   ├── en.js                   # English (fallback)
│   ├── pt_BR.js                # Português (Brasil)
│   ├── es_ES.js                # Espanol
│   ├── zh_CN.js                # Chinese (Simplified)
│   ├── hi_IN.js                # Hindi
│   ├── ar.js                   # Arabic
│   ├── bn_BD.js                # Bengali
│   ├── fr_FR.js                # French
│   ├── de_DE.js                # German
│   ├── ja_JP.js                # Japanese
│   ├── ru_RU.js                # Russian
│   ├── ko_KR.js                # Korean
│   ├── id_ID.js                # Indonesian
│   ├── tr_TR.js                # Turkish
│   ├── vi_VN.js                # Vietnamese
│   ├── it_IT.js                # Italian
│   ├── pl_PL.js                # Polish
│   ├── nl_NL.js                # Dutch
│   ├── fa_IR.js                # Persian
│   ├── th_TH.js                # Thai
│   ├── ur_PK.js                # Urdu
│   ├── ms_MY.js                # Malay
│   └── README.md               # Translation guide
├── scripts/
│   ├── check-i18n-keys.mjs     # i18n key parity checker
│   ├── test-parsers.mjs        # Parser unit tests (status/license/config/locations)
│   ├── lint-markdown.sh        # Markdown linter
│   └── validate-qml.sh         # QML syntax validator
├── docs/
│   ├── ARCHITECTURE.md         # Component design & data flow
│   ├── COMMANDS.md             # CLI command mapping
│   ├── RELEASE_CHECKLIST.md    # Release process
│   └── releases/               # Per-version release notes
├── CHANGELOG.md
├── CONTRIBUTING.md
└── LICENSE                     # MIT

For detailed architecture and data flow, see docs/ARCHITECTURE.md. For the CLI command map, see docs/COMMANDS.md.

🔒 Security & Permissions

The plugin only executes local CLI commands through the DMS process API. No credentials are stored — secrets live in adguardvpn-cli's own config. Network traffic is entirely managed by the CLI itself.

Permission	Purpose
`settings_read`	Load plugin settings
`settings_write`	Persist plugin settings
`process`	Execute `adguardvpn-cli` commands

🔍 Troubleshooting

adguardvpn-cli unavailable

Verify the binary is accessible:

adguardvpn-cli --version

If using a custom path, update it in plugin settings (adguardBinary).

Auth / session issues

Authenticate interactively, then refresh in the widget:

adguardvpn-cli login

Location connect errors (city / country / ISO not found)

Hit Refresh in the widget to update the location list.
Prefer the visible city, country label from the list, or an ISO code when you want the CLI to choose within a country.
If a saved preferred location is stale, update it in settings.

Plugin not loading

dms ipc plugins status  adguardVPplugin
dms ipc plugins reload  adguardVPplugin

💻 Development

Follow the DMS plugin development guide.

Recommended loop:

# edit code…
dms ipc plugins reload adguardVPplugin

Quality checks before committing:

node scripts/check-i18n-keys.mjs   # i18n key parity
node scripts/test-parsers.mjs      # parser unit tests
bash scripts/lint-markdown.sh       # markdown lint
bash scripts/validate-qml.sh       # QML syntax

🌐 Localization

This plugin is now officially multilang and ships with:

Full locales: English, Português (Brasil)
Full locales (previously extended with English fallback): Español, 中文 (简体), हिन्दी, العربية, বাংলা, Français, Deutsch, 日本語, Русский, 한국어, Indonesia, Türkçe, Tiếng Việt, Italiano, Polski, Nederlands, فارسی, ไทย, اردو, Bahasa Melayu

Every shipped locale is now fully translated (all 179 message keys). Untranslated strings, if any are added later, fall back to English.

Adding or extending locales is straightforward — see i18n/README.md.

🤝 Contributing

See CONTRIBUTING.md for workflow, quality checks, and release process.

📦 Publishing

Follow the Release Checklist, then:

git tag vX.Y.Z
git push origin main --tags

Submit to the DMS Plugin Registry.

📄 License

MIT — Bernardo Gomes

Português (Brasil)

Controle, monitore e configure o AdGuard VPN diretamente pela DankBar — sem precisar abrir o terminal.

Recursos

Categoria	O que você recebe
Monitoramento ao vivo	Status, conta, interface do túnel, endpoint SOCKS e localizações ranqueadas em tempo real
Ações em um clique	Conectar / Desconectar / Mais rápida / Conectar por localização — Enter no campo também conecta
Configuração em runtime	Modo (TUN / SOCKS), Protocolo (Auto / HTTP2 / QUIC), canal de atualização e DNS upstream
Ferramentas de localização	Busca, filtro, favoritos fixados no topo e paginação "mostrar mais"
Resiliência	Auto-conectar ao iniciar, auto-reconectar com backoff em 3 etapas e preflight de conexão
Diagnóstico	Último comando, visualizador do log do túnel e banner de login com comando copiável
Acessibilidade	Navegação completa por teclado (Tab + Enter/Espaço) com foco visível e roles Accessible
Multilíngue	22 idiomas totalmente traduzidos (EN, PT-BR + 20 locales adicionais)
Parsers testados	Remoção de ANSI e parsing multi-formato cobertos por 31 testes unitários no CI

Requisitos

Dependência	Versão
DankMaterialShell	`>= 1.4.0`
`adguardvpn-cli`	Qualquer versão recente; veja o guia oficial de instalação
Conta AdGuard	Sessão iniciada com `adguardvpn-cli login`

Instalação

git clone https://github.com/bernardopg/dms-adguard-vpn-plugin.git \
  ~/.config/DankMaterialShell/plugins/adguardVPplugin

dms ipc plugins reload adguardVPplugin
dms ipc plugins enable adguardVPplugin

Depois, abra DMS Settings → Widgets e adicione AdGuard VPN à barra.

Túnel gerenciado por systemd (opcional)

Por padrão o plugin chama o adguardvpn-cli direto e funciona sem nenhum serviço extra. Configurações avançadas podem ativar useSystemdService: true e fornecer /usr/local/sbin/adguardvpn-dms-control; nesse modo, conectar e desconectar delegam o túnel persistente a um serviço systemd de root em vez de deixá-lo no cgroup do DMS. Há uma implementação de referência em scripts/adguardvpn-dms-control:

sudo install -m 755 -o root -g root \
  scripts/adguardvpn-dms-control /usr/local/sbin/adguardvpn-dms-control

Depois conceda ao usuário do desktop uma regra NOPASSWD no sudoers para esse caminho exato — o plugin sempre chama por sudo -n, então um prompt interativo faz a ação falhar em silêncio.

Vai escrever seu próprio helper? Faça connect-fastest e connect-location serem idempotentes. O systemctl restart derruba o túnel por alguns segundos: o NetworkManager marca a interface como unmanaged, o systemd-resolved troca de servidor DNS e toda conexão em curso morre junto — downloads, SSH, sessões HTTP longas. Um helper que reinicia incondicionalmente transforma um clique que não muda nada ("conectar na localização em que já estou") numa queda de rede real. A implementação de referência sai com 0 sem reiniciar quando a unit já está ativa e /var/lib/adguardvpn-dms/location já corresponde ao destino pedido; --force restaura o comportamento incondicional para reescolher servidor de propósito.

Configurações

Todas as configurações ficam na tela de settings do plugin no DMS.

Configuração	Tipo	Padrão	Descrição
`adguardBinary`	string	`adguardvpn-cli`	Nome do binário ou caminho absoluto do CLI
`refreshIntervalSec`	int	`8`	Intervalo de polling de status (3–120 s)
`locationsCount`	int	`20`	Quantidade de localizações carregadas (5–100)
`connectStrategy`	enum	`fastest`	Estratégia padrão: `fastest` ou `location`
`defaultLocation`	string	—	Localização preferida: cidade, país ou ISO
`ipStack`	enum	`auto`	Forçar IPv4 ou IPv6 nas conexões
`autoRefreshLocations`	bool	`true`	Atualizar lista de localizações periodicamente
`autoConnectOnStartup`	bool	`false`	Conectar automaticamente ao iniciar plugin/sessão
`autoReconnectOnDrop`	bool	`false`	Reconectar se o túnel cair inesperadamente
`showLocationInBar`	bool	`true`	Mostrar texto/localização ao lado do ícone
`bypassMultiRouteCheck`	bool	`false`	Pular a checagem de múltiplas rotas padrão antes de conectar (Configurações → Avançado) em setups com falso positivo
`useSystemdService`	bool	`false`	Delegar conexão/desconexão ao helper systemd opcional `adguardvpn-dms-control`, instalado separadamente
`languageOverride`	enum	`auto`	Idioma da UI; `auto` segue o locale do sistema

Segurança e permissões

O plugin executa apenas comandos locais pelo processo do DMS. Credenciais não são armazenadas pelo plugin; elas ficam no próprio adguardvpn-cli.

Permissão	Finalidade
`settings_read`	Ler configurações do plugin
`settings_write`	Persistir configurações do plugin
`process`	Executar comandos locais do `adguardvpn-cli`

Solução de problemas

Se o CLI aparecer como indisponível, verifique:

adguardvpn-cli --version

Se usa caminho customizado, atualize adguardBinary nas configurações. Para problemas de sessão, rode adguardvpn-cli login. Para erros de localização, atualize a lista no widget e prefira o rótulo visível cidade, país; use ISO quando quiser deixar o CLI escolher dentro do país.

Desenvolvimento

Loop recomendado:

dms ipc plugins reload adguardVPplugin

Checks antes de commitar:

node scripts/check-i18n-keys.mjs
node scripts/test-parsers.mjs
bash scripts/lint-markdown.sh
bash scripts/validate-qml.sh

Licença

MIT — Bernardo Gomes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

🛡️ AdGuard VPN — DankMaterialShell Plugin

✨ Features

📋 Requirements

🚀 Installation

Optional systemd-managed tunnel

1. Clone into DMS plugins directory

2. Reload & enable

3. Add to DankBar

⚙️ Settings

🏗️ Project Structure

🔒 Security & Permissions

🔍 Troubleshooting

💻 Development

🌐 Localization

🤝 Contributing

📦 Publishing

📄 License

Português (Brasil)

Recursos

Requisitos

Instalação

Túnel gerenciado por systemd (opcional)

Configurações

Segurança e permissões

Solução de problemas

Desenvolvimento

Licença

About

Releases

Used by

Contributors

Languages

Name		Name	Last commit message	Last commit date
Latest commit History 38 Commits
.github		.github
docs		docs
i18n		i18n
scripts		scripts
.gitignore		.gitignore
.markdownlint.json		.markdownlint.json
AdGuardVpnI18n.qml		AdGuardVpnI18n.qml
AdGuardVpnParsers.js		AdGuardVpnParsers.js
AdGuardVpnService.qml		AdGuardVpnService.qml
AdGuardVpnSettings.qml		AdGuardVpnSettings.qml
AdGuardVpnWidget.qml		AdGuardVpnWidget.qml
CHANGELOG.md		CHANGELOG.md
CONTRIBUTING.md		CONTRIBUTING.md
DONE.md		DONE.md
LICENSE		LICENSE
README.md		README.md
To-Do.md		To-Do.md
package-lock.json		package-lock.json
package.json		package.json
plugin.json		plugin.json
qmldir		qmldir

Folders and files

Latest commit

History

Repository files navigation

🛡️ AdGuard VPN — DankMaterialShell Plugin

✨ Features

📋 Requirements

🚀 Installation

Optional systemd-managed tunnel

1. Clone into DMS plugins directory

2. Reload & enable

3. Add to DankBar

⚙️ Settings

🏗️ Project Structure

🔒 Security & Permissions

🔍 Troubleshooting

💻 Development

🌐 Localization

🤝 Contributing

📦 Publishing

📄 License

Português (Brasil)

Recursos

Requisitos

Instalação

Túnel gerenciado por systemd (opcional)

Configurações

Segurança e permissões

Solução de problemas

Desenvolvimento

Licença

About

Topics

Resources

Contributing

Stars

Watchers

Forks

Releases

Used by

Contributors

Languages